passlib

README

passlib for go

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 sha256-crypt, sha512-crypt, scrypt-sha256, bcrypt and passlib's bcrypt-sha256 variant. 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
    return
  }

  (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:

$s2$N$r$p$salt$hash

...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).

TODO

• PBKDF2

Licence

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 <hlandau@devever.net>  BSD License

Documentation

Overview

Package passlib provides a simple password hashing and verification interface abstracting multiple password hashing schemes.

Most people need concern themselves only with the functions Hash and Verify, which uses the default context and sensible defaults.

Index

• Variables
• func Hash(password string) (hash string, err error)
• func NeedsUpdate(stub string) bool
• func Verify(password, hash string) (newHash string, err error)
• type Context
  • func (ctx *Context) Hash(password string) (hash string, err error)
  • func (ctx *Context) NeedsUpdate(stub string) bool
  • func (ctx *Context) Verify(password, hash string) (newHash string, err error)

Examples

• Hash (Signup)
• Verify (Login)

Variables

var DefaultSchemes = []abstract.Scheme{
	scrypt.SHA256Crypter,
	sha2crypt.Crypter256,
	sha2crypt.Crypter512,
	bcryptsha256.Crypter,
	bcrypt.Crypter,
}

The default schemes, most preferred first. The first scheme will be used to hash passwords, and any of the schemes may be used to verify existing passwords. The contents of this value may change with subsequent releases.

Functions

func Hash

func Hash(password string) (hash string, err error)

Hashes a UTF-8 plaintext password using the default context and produces a password hash. Chooses the preferred password hashing scheme based on the configured policy. The default policy is sensible.

Example (Signup)

User signup example.

// User signup example.

// ... signup code ...

// Get the password the user chose by whatever means.
password := getSignupPassword()
username := getSignupUsername()

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

// hash now contains a hash in modular crypt form.
// Store hash in database, etc.
storeHashInDatabase(username, hash)

func NeedsUpdate

func NeedsUpdate(stub string) bool

Uses the default context to determine whether a stub or hash needs updating.

func Verify

func Verify(password, hash string) (newHash string, err error)

Verifies a UTF-8 plaintext password using a previously derived password hash and the default context. Returns nil err only if the password is valid.

If the hash is determined to be deprecated based on policy, and the password is valid, the password is hashed using the preferred password hashing scheme and returned in newHash. You should use this to upgrade any stored password hash in your database.

newHash is empty if the password was invalid or no upgrade is required.

You should treat any non-nil err as a password verification error.

Example (Login)

User login example.

// User login example.

// Get the password for the user we have stored in the database.
hash := getUserHashFromDatabase()

// Get the plaintext password the user tried to login with.
password := getLoginPassword()

newHash, err := Verify(password, hash)
if err != nil {
	// Incorrect password, malformed hash, etc.
	return
}

if newHash != "" {
	// passlib thinks we should upgrade to a new stronger hash.
	// ... store the new hash in the database ...
}

// ... log the user in ...

Types

type Context

type Context struct {
	// Slice of schemes to use, most preferred first.
	//
	// If left uninitialized, a sensible default set of schemes will be used.
	//
	// An upgrade hash (see the newHash return value of the Verify method of the
	// abstract.Scheme interface) will be issued whenever a password is validated
	// using a scheme which is not the first scheme in this slice.
	Schemes []abstract.Scheme
}

var DefaultContext Context

The default context, which uses sensible defaults. Most users should not reconfigure this. The defaults may change over time, so you may wish to reconfigure the context or use a custom context if you want precise control over the hashes used.

func (*Context) Hash

func (ctx *Context) Hash(password string) (hash string, err error)

Hashes a UTF-8 plaintext password using the context and produces a password hash.

If stub is "", one is generated automaticaly for the preferred password hashing scheme; you should specify stub as "" in almost all cases.

The provided or randomly generated stub is used to deterministically hash the password. The returned hash is in modular crypt format.

If the context has not been specifically configured, a sensible default policy is used. See the fields of Context.

func (*Context) NeedsUpdate

func (ctx *Context) NeedsUpdate(stub string) bool

Determines whether a stub or hash needs updating according to the policy of the context.

func (*Context) Verify

func (ctx *Context) Verify(password, hash string) (newHash string, err error)

Verifies a UTF-8 plaintext password using a previously derived password hash and the default context. Returns nil err only if the password is valid.

If the hash is determined to be deprecated based on the context policy, and the password is valid, the password is hashed using the preferred password hashing scheme and returned in newHash. You should use this to upgrade any stored password hash in your database.

newHash is empty if the password was not valid or if no upgrade is required.

You should treat any non-nil err as a password verification error.