pbkdf2

README

PBKDF2-HMAC-SHA512

Warning
Key derivation functions requiring constant memory cost such as PBKDF2 and bcrypt are deprecated in favor of those with tunable memory cost, such as scrypt and argon2. Setting a high memory usage for key derivation allows us to thwart hardware (FPGA / ASIC) based attacks.

This package provides a convenience wrapper around Go's pbkdf2 implementation, making it simpler to securely hash and verify passwords using PBKDF2.

It enforces use of the PBKDF2-HMAC-SHA512 algorithm variant and cryptographically-secure random salts.

Usage

package main

import (
	"log"

	"github.com/pganguli/pbkdf2"
)

func main() {
	// CreateHash returns a PBKDF2-HMAC-SHA512 hash of a plain-text password using the
	// provided algorithm parameters. The returned hash follows the format:
	// $pbkdf2-sha512$210000$yvu2ZftdlhcP4Tbpe2TYqA$XJsU2xkzTyRZur3/+VW07FljLcgKGfmNw+en6y3WJ0JWHHEkn4e46VcaddErsqc9jkJC5IVl4XSlh4lgv0dlug
	hash, err := pbkdf2.CreateHash("pa$$word", pbkdf2.DefaultParams)
	if err != nil {
		log.Fatal(err)
	}

	// ComparePasswordAndHash performs a constant-time comparison between a
	// plain-text password and PBKDF2-HMAC-SHA512 hash, using the parameters and salt
	// contained in the hash. It returns true if they match, otherwise it returns
	// false.
	match, err := pbkdf2.ComparePasswordAndHash("pa$$word", hash)
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("Match: %v", match)
}

Changing the Parameters

When creating a hash you can and should configure the parameters to be suitable for the environment that the code is running in. The parameters are:

• Iterations — The number of iterations (or passes). 210000 is recommended for PBKDF2-HMAC-SHA512.
• Salt length — Length of the random salt. 16 bytes is recommended for password hashing.
• Key length — Length of the generated key (or password hash). 32 bytes or more is recommended.

The Iterations parameter controls the computational cost of hashing the password. The higher this figure is, the greater the cost of generating the hash and the longer the runtime. It also follows that the greater the cost will be for any attacker trying to guess the password.

params := &pbkdf2.Params{
	Iterations:  210000,
	SaltLength:  16,
	KeyLength:   64,
}


hash, err := pbkdf2.CreateHash("pa$$word", params)
if err != nil {
	log.Fatal(err)
}

For guidance and an outline process for choosing appropriate parameters see https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2.

Documentation

Overview

Package pbkdf2 provides a convience wrapper around Go's golang.org/x/crypto/pbkdf2 implementation, making it simpler to securely hash and verify passwords using PBKDF2.

It enforces use of the PBKDF2-HMAC-SHA512 algorithm variant and cryptographically-secure random salts.

Index

• Variables
• func ComparePasswordAndHash(password, hash string) (match bool, err error)
• func CreateHash(password string, params *Params) (hash string, err error)
• type Params
  • func CheckHash(password, hash string) (match bool, params *Params, err error)
  • func DecodeHash(hash string) (params *Params, salt, key []byte, err error)

Variables

var (
	// ErrInvalidHash in returned by ComparePasswordAndHash if the provided
	// hash isn't in the expected format.
	ErrInvalidHash = errors.New("pbkdf2: hash is not in the correct format")

	// ErrIncompatibleVariant is returned by ComparePasswordAndHash if the
	// provided hash was created using a unsupported variant of PBKDF2.
	// Currently only PBKDF2-HMAC-SHA512 is supported by this package.
	ErrIncompatibleVariant = errors.New("pbkdf2: incompatible variant of pbkdf2")
)

var DefaultParams = &Params{
	Iterations: 210000,
	SaltLength: 16,
	KeyLength:  64,
}

DefaultParams provides some sane default parameters for hashing passwords.

Follows recommendations given by the NIST.

The default parameters should generally be used for development/testing purposes only. Custom parameters should be set for production applications depending on available memory/CPU resources and business requirements.

Functions

func ComparePasswordAndHash

func ComparePasswordAndHash(password, hash string) (match bool, err error)

ComparePasswordAndHash performs a constant-time comparison between a plain-text password and PBKDF2-HMAC-SHA512 hash, using the parameters and salt contained in the hash. It returns true if they match, otherwise it returns false.

func CreateHash

func CreateHash(password string, params *Params) (hash string, err error)

CreateHash returns a PBKDF2-HMAC-SHA512 hash of a plain-text password using the provided algorithm parameters. The returned hash follows the format:

$pbkdf2-sha512${Iterations}${b64Salt}${b64Key}

It looks like this:

$pbkdf2-sha512$210000$yvu2ZftdlhcP4Tbpe2TYqA$XJsU2xkzTyRZur3/+VW07FljLcgKGfmNw+en6y3WJ0JWHHEkn4e46VcaddErsqc9jkJC5IVl4XSlh4lgv0dlug

Types

type Params

type Params struct {
	// The number of iterations.
	Iterations uint32

	// Length of the random salt. 16 bytes is recommended for password hashing.
	SaltLength uint32

	// Length of the generated key. 16 bytes or more is recommended.
	KeyLength uint32
}

Params describes the input parameters used by the PBKDF2 algorithm. The Iterations parameter controls the computational cost of hashing the password. The higher this figure is, the greater the cost of generating the hash and the longer the runtime. It also follows that the greater the cost will be for any attacker trying to guess the password. Important note: Changing the value of the Iterations parameter changes the hash output.

For guidance and an outline process for choosing appropriate parameters see https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2

func CheckHash

func CheckHash(password, hash string) (match bool, params *Params, err error)

CheckHash is like ComparePasswordAndHash, except it also returns the params that the hash was created with. This can be useful if you want to update your hash params over time (which you should).

func DecodeHash

func DecodeHash(hash string) (params *Params, salt, key []byte, err error)

DecodeHash expects a hash created from this package, and parses it to return the params used to create it, as well as the salt and key (password hash).