pwdhash

README

pwdhash

Overview

pwdhash is a Go package for securely hashing passwords and for checking plaintext password guesses against a hashed password.

This package uses the PBKDF2 key derivation algorithm with HMAC variant in combination with a supplied hash function and cryptographically-secure, randomly-generated salt to achieve secure password hashing.

Note that while alternatives, such as bcrypt and scrypt, do exist, PBKDF2 is considered appropriate and secure for password hashing if used correctly (ie: appropriately high cost factor, secure hashing algorithm, unique salt per password).

Example

The following code uses HMAC-SHA-512 based PBKDF2 to protect the password "password" with a cost factor of 100,000 iterations.

package main

import (
    "crypto/sha512"

    "github.com/smotes/pwdhash"
)

func main() {
    pwd := []byte("password")
    cost := 100000  // cost as number of pbkdf2 iterations

    salt, err := pwdhash.GenerateSalt(sha512.Size)
    if err != nil {
        panic(err)
    }

    hpwd, err := pwdhash.GenerateFromPassword(pwd, salt, cost, sha512.Size, "sha512")
    if err != nil {
        panic(err)
    }

    err = pwdhash.CompareHashAndPassword(hpwd, pwd)
    if err != nil {
        panic(err)  // err = ErrMismatchedHashAndPassword
    }
}

Documentation

Overview

Package pwdhash is a Go package for securely hashing passwords and for checking plaintext password guesses against a hashed password.

This package uses the PBKDF2 key derivation algorithm with HMAC variant in combination with a supplied hash function and cryptographically-secure, randomly-generated salt to achieve secure password hashing.

Note that while alternatives, such as bcrypt and scrypt, do exist, PBKDF2 is considered appropriate and secure for password hashing if used correctly (ie: appropriately high cost factor, secure hashing algorithm, unique salt per password).

Index

• Constants
• Variables
• func CompareHashAndPassword(hpwd, pwd []byte) error
• func Cost(hpwd []byte) (int, error)
• func GenerateFromPassword(pwd, s []byte, cost, n int, alg string) ([]byte, error)
• func GenerateSalt(n int) (s []byte, err error)
• type ErrInvalidCost
  • func (err ErrInvalidCost) Error() string
• type ErrInvalidHashFormat
  • func (err ErrInvalidHashFormat) Error() string
• type ErrInvalidHashFunction
  • func (err ErrInvalidHashFunction) Error() string

Constants

const (
	MinCost int = 1             // the minimum allowable cost as passed in to GenerateFromPassword
	MaxCost int = math.MaxInt32 // the maximum allowable cost as passed in to GenerateFromPassword
)

Variables

var ErrMismatchedHashAndPassword = errors.New("github.com/smotes/phash: hashed password is not the hash of the given password")

The error returned from CompareHashAndPassword when the hashed password does not match the hash of the given password.

Functions

func CompareHashAndPassword

func CompareHashAndPassword(hpwd, pwd []byte) error

CompareHashAndPassword compares a PBKDF2 hashed password hpwd with its possible plaintext equivalent pwd. Returns nil on success, or an error on failure.

The comparison is done using a constant-length comparison algorithm to protect against possible timing attacks.

func Cost

func Cost(hpwd []byte) (int, error)

Cost returns the work factor used to create the given hashed password. When, in the future, the work factor needs to be increased in order to adjust for greater computational power, this function allows one to establish which passwords need to be updated.

func GenerateFromPassword

func GenerateFromPassword(pwd, s []byte, cost, n int, alg string) ([]byte, error)

GenerateFromPassword returns the PBKDF2 hash of the password from the given plaintext password pwd, salt s, number of iterations cost, key length n and name of the hash algorithm alg.

The cost is the work factor, or number of iterations. Returns an error if cost < 1, or if cost > 2^31.

The name of the hash function a must be a one of a number of supported one-way hash functions. Returns an error if an unsupported hash algorithm name is provided. The list of supported hash algorithm names are:

"md5"
"sha1"
"sha256"
"sha512"

Note that use of md5 or sha1 is not recommended as both are considered cryptographically broken, but are still supported for compatibility purposes. It is recommended to use sha256 and sha512 on 32-bit and 64-bit systems respectively.

Returns a byte slice containing the name of the hash algorithm, the cost, the salt and the password digest. Each component in the output is delimited by a '$' character. The cost, salt and digest are encoded in base64 format for storage in a database.

<algorithm>$<cost>$<salt>$<digest>

func GenerateSalt

func GenerateSalt(n int) (s []byte, err error)

GenerateSalt generates a cryptographically secure random salt s of specified byte length n.

On return, len(s) == n if and only if err == nil.

Do not reuse the same salt on multiple password hashes.

Do not make the salt too short. A common rule of thumb is to make the salt the same byte size as the digest.

Types

type ErrInvalidCost

type ErrInvalidCost int

The error returned from GenerateFromPassword when the provided work factor is outside of the valid range.

func (ErrInvalidCost) Error

func (err ErrInvalidCost) Error() string

type ErrInvalidHashFormat

type ErrInvalidHashFormat string

The error returned from CompareHashAndPassword when the provided hashed password hpwd does not have the expected format.

func (ErrInvalidHashFormat) Error

func (err ErrInvalidHashFormat) Error() string

type ErrInvalidHashFunction

type ErrInvalidHashFunction string

The error returned from GenerateFromPassword when the provided hash function is not supported/invalid.

func (ErrInvalidHashFunction) Error

func (err ErrInvalidHashFunction) Error() string