:key: Idiotproof golang password validation library inspired by Python's passlib

Related tags


passlib for go

godocs.io Build status No modules 100% modules-free.

Python's passlib is quite an amazing library. I'm not sure there's a password library in existence with more thought put into it, or with more support for obscure password formats.

This is a skeleton of a port of passlib to Go. It dogmatically adopts the modular crypt format, which passlib has excellent documentation for.

Currently, it supports:

  • Argon2i
  • scrypt-sha256
  • sha512-crypt
  • sha256-crypt
  • bcrypt
  • passlib's bcrypt-sha256 variant
  • pbkdf2-sha512 (in passlib format)
  • pbkdf2-sha256 (in passlib format)
  • pbkdf2-sha1 (in passlib format)

By default, it will hash using scrypt-sha256 and verify existing hashes using any of these schemes.

Example Usage

There's a default context for ease of use. Most people need only concern themselves with the functions Hash and Verify:

// Hash a plaintext, UTF-8 password.
func Hash(password string) (hash string, err error)

// Verifies a plaintext, UTF-8 password using a previously derived hash.
// Returns non-nil err if verification fails.
// Also returns an upgraded password hash if the hash provided is
// deprecated.
func Verify(password, hash string) (newHash string, err error)

Here's a rough skeleton of typical usage.

import "gopkg.in/hlandau/passlib.v1"

func RegisterUser() {

  password := get a (UTF-8, plaintext) password from somewhere

  hash, err := passlib.Hash(password)
  if err != nil {
    // couldn't hash password for some reason

  (store hash in database, etc.)

func CheckPassword() bool {
  password := get the password the user entered
  hash := the hash you stored from the call to Hash()

  newHash, err := passlib.Verify(password, hash)
  if err != nil {
    // incorrect password, malformed hash, etc.
    // either way, reject
    return false

  // The context has decided, as per its policy, that
  // the hash which was used to validate the password
  // should be changed. It has upgraded the hash using
  // the verified password.
  if newHash != "" {
    (store newHash in database, replacing old hash)

  return true

scrypt Modular Crypt Format

Since scrypt does not have a pre-existing modular crypt format standard, I made one. It's as follows:


...where N, r and p are the respective difficulty parameters to scrypt as positive decimal integers without leading zeroes, and salt and hash are base64-encoded binary strings. Note that the RFC 4648 base64 encoding is used (not the one used by sha256-crypt and sha512-crypt).


passlib is partially derived from Python's passlib and so maintains its BSD license.

© 2008-2012 Assurance Technologies LLC.  (Python passlib)  BSD License
© 2014 Hugo Landau <[email protected]>  BSD License
  • Add argon2 crypter

    Add argon2 crypter

    Adds an argon2 crypter and promote it as the default scheme.

    Argon2 is the winner of the password hashing competition and is now available in other languages: PHP, Javascript, Ruby etc.

    The crypter uses the pure go implementation of argon2 here: https://godoc.org/golang.org/x/crypto/argon2

    Closes #4

    opened by F21 4
  • Password migration?

    Password migration?

    First of all, thanks for this package! No nonsense, works as expected, and easy to extend. 👍

    For an app I'm working on, I wrote a small wrapper for the phpass package (used to authenticate users after a migration from Wordpress). However I'd also love to be able to migrate those users to more secure password hashes transparently as they sign in. But at the moment, Verify() only returns new hashes computed with the same algorithm as the "old" one.

    So would it be possible to either:

    • add a global (per-context) flag to "force" upgrading old hashes to the first in the context schemes?
    • or add a DeprecatedSchemes field to the passlib context that contain schemes that can be used to check passwords, but which will always trigger an upgrade to one in the normal Schemes?

    IMO the latter would be nicer. It's also similar to what the Python passlib does. What do you think? (I'm interested in writing a patch myself to implement whichever you prefer...)

    opened by Schnouki 3
  • Argon2 support

    Argon2 support

    Are there any plans for argon2 support? I think it would be a great addition to the library :smiley:

    opened by F21 2
  • Add pbkdf2 derivative support in line with Pythons PassLib standards.

    Add pbkdf2 derivative support in line with Pythons PassLib standards.

    Requires custom base64 encoding/decoding as per the ab64_* methods in Python's PassLib. Substitutes + for . in the encoded version and vice versa when decoding.

    Includes tests to verify comparability with Python generated hashes.

    Includes benchmarks to compare derivatives.

    Adds all deriviatives to default verify context.

    Update README.md to include new methods and create a standard list to make it easier to read. Also remove TODO item.

    opened by tomtom5152 2
  • PBKDF2 salt length is only 16 bytes?

    PBKDF2 salt length is only 16 bytes?


    A 15 year old book recommends at least 32 bytes: https://stackoverflow.com/a/9622855

    Even if you leave the salt length as-is, a code comment for SaltLength would be nice explaining the rationale.

    P.S. yesterday I coded up a super small https://github.com/function61/gokit/blob/master/storedpassword/ package. After writing it, I searched around and found your library. I got many improvements by studying this design (for example Verify() returns upgraded version automatically), and am considering on just ditching my own and using this.. only advantage my library has is that it's smaller and serialization is simpler by embedding the cost parameter in algorithm id.

    opened by joonas-fi 2
  • allow building on 32-bit platforms

    allow building on 32-bit platforms


    opened by deoxxa 2
  • Metrics


    I almost decided to use this library (and contribute PBKDF2). Then I found dependency on your metrics library. I like metrics too, but I don't think that hard dependency inside library (as apposed to application) is a good thing. Please consider to remove it.

    opened by AlekSi 1
  • Example of how to change the hashing scheme from user code

    Example of how to change the hashing scheme from user code

    Can you please provide a simple example of how to change the hashing scheme preference from the user code. I am trying to create a Context with different order but as soon as I import the hashing packages, I start getting duplicate exported symbol errors.

    opened by kuchlous 1
  • It should be possible to set DefaultSchemes using strings

    It should be possible to set DefaultSchemes using strings

    If you're building a piece of software that plugs in to existing systems, you need to be able to configure the set of hashes that passlib will use, since unless you're using passlib (or maybe the Python version of passlib) everywhere, the chances are that the set of hashes that are supported is smaller than that supported by passlib, and you don't want passlib "upgrading" to a hash that other system components don't support.

    It's possible, of course, to import all the sub-packages in passlib and build a DefaultSchemes array yourself, but really there should be functionality in passlib to allow you to pass in a list of string tokens that passlib then converts to abstract.Schemes itself.

    opened by al45tair 1
  • go get

    go get

    can you add go get to the documentation? please

    opened by ghost 1
Hugo Landau
Hugo Landau
sops is an editor of encrypted files that supports YAML, JSON, ENV, INI and BINARY formats and encrypts with AWS KMS, GCP KMS, Azure Key Vault, age, and PGP

sops is an editor of encrypted files that supports YAML, JSON, ENV, INI and BINARY formats and encrypts with AWS KMS, GCP KMS, Azure Key Vault, age, and PGP. (demo)

Mozilla 7.9k Jul 17, 2021
Split and distribute your private keys securely amongst untrusted network

cocert An experimental tool for splitting and distributing your private keys safely* cocert, generates ECDSA - P521 key and uses a technique known as

Furkan Türkal 132 Jul 15, 2021
Finds common flaws in passwords. Like cracklib, but written in Go.

crunchy Finds common flaws in passwords. Like cracklib, but written in Go. Detects: ErrEmpty: Empty passwords ErrTooShort: Too short passwords ErrNoDi

Christian Muehlhaeuser 368 Jul 18, 2021
The bare metal Go smart card

Authors Andrea Barisani [email protected] | [email protected] Introduction The GoKey application implements a USB smartcard in pure Go

F-Secure Foundry 106 Jul 13, 2021
A convenience library for generating, comparing and inspecting password hashes using the scrypt KDF in Go 🔑

simple-scrypt simple-scrypt provides a convenience wrapper around Go's existing scrypt package that makes it easier to securely derive strong keys ("h

Matt Silverlock 172 Jul 12, 2021
Secret - Encrypt anything with a password

Secret - Encrypt anything with a password Ever wanted to hide a file? Now you can do it really easily! Usage secret {-e/--encrypt | -d/--decrypt} <sou

Ishan Goel 30 Jul 16, 2021
A dead simple tool to sign files and verify digital signatures.

minisign minisign is a dead simple tool to sign files and verify signatures. $ minisign -G

Andreas Auernhammer 35 Jul 15, 2021
go seof: Simple Encrypted os.File

Encrypted implementation of golang' os.File. It handles WriteAt, Seek, Truncate, etc. Can deal with huge files, random access, etc.

Ed Riccardi 44 May 11, 2021
Pure Go Kerberos library for clients and services

gokrb5 It is recommended to use the latest version: Development will be focused on the latest major version. New features will only be targeted at thi

Jonathan Turner 515 Jul 16, 2021
Merchant API reference implementation

mAPI More details available in the BRFC Spec for Merchant API. The old golang (v1.1) implementation is no longer being maintained and has been moved t

Bitcoin SV 11 Jun 24, 2021
An easy-to-use XChaCha20-encryption wrapper for io.ReadWriteCloser (even lossy UDP) using ECDH key exchange algorithm, ED25519 signatures and Blake3+Poly1305 checksums/message-authentication for Go (golang). Also a multiplexer.

Quick start Prepare keys (on both sides): [ -f ~/.ssh/id_ed25519 ] && [ -f ~/.ssh/id_ed25519.pub ] || ssh-keygen -t ed25519 scp ~/.ssh/id_ed25519.pub

null 18 Jul 19, 2021
TLS/SSL Tunnel - A modern STunnel replacement written in golang

go-tunnel - Robust Quic/TLS Tunnel (Stunnel replacement) What is it? A supercharged Stunnel replacement written in golang. is in a sense a proxy enabl

Sudhi Herle 124 Jul 15, 2021
Get any cryptocurrencies ticker and trade data in real time from multiple exchanges and then save it in multiple storage systems.

Cryptogalaxy is an app which will get any cryptocurrencies ticker and trade data in real time from multiple exchanges and then saves it in multiple storage systems.

Pavan Shetty 38 Jul 26, 2021
hack-browser-data is an open-source tool that could help you decrypt data from the browser.

hack-browser-data is an open-source tool that could help you decrypt data ( password|bookmark|cookie|history|credit card|download

idiotc4t 73 Jul 19, 2021