gopasswordhash

README

gopasswordhash

Go Password Hashing Module, for more background information on the implementation details and rationale, please see http://crackstation.net/hashing-security.htm

The library consists of two functions:

func CreateHash (password string) (string, error)

CreateHash creates a salted cryptographic hash with key stretching (PBKDF2), suitable for storage and usage in password authentication mechanisms.

func ValidatePassword(password string, correctHash string) bool

ValidatePassword hashes a password according to the setup found in the correct hash string and does a constant time compare on the correct hash and calculated hash.

Documentation

Overview

Package gopasswordhash implements functions to create and verify salted cryptographic hashes suitable for building password authentication mechanisms. Code has been inspired by the excellent article "Salted Password Hashing - Doing it Right" which can be found at https://crackstation.net/hashing-security.htm

When needing highly secure password verification / storage solutions use this library in combination with a secret key to be added to the password which should be stored on an external system or special hardware device like the YubiHSM

Index

• Constants
• func CreateHash(password string) (string, error)
• func ValidatePassword(password string, correctHash string) bool

Constants

const (
	// PBKDF2_HASH_ALGORITHM can be set to sha1, sha224, sha256, sha384 or sha512 as the underlying hashing mechanism to be used by the PBKDF2 function
	PBKDF2_HASH_ALGORITHM string = "sha512"
	// PBKDF2_ITERATIONS sets the amount of iterations used by the PBKDF2 hashing algorithm
	PBKDF2_ITERATIONS int = 15000
	// SCRYPT_N is a CPU/memory cost parameter, which must be a power of two greater than 1
	SCRYPT_N int = 32768
	// SCRYPT_R is the block size parameter
	SCRYPT_R int = 8
	// SCRYPT_P is the parallelization parameter, a positive integer less than or equal to ((2^32-1) * 32) / (128 * r)
	SCRYPT_P int = 1

	// SALT_BYTES sets the amount of bytes for the salt used in the PBKDF2 / scrypt hashing algorithm
	SALT_BYTES int = 64
	// HASH_BYTES sets the amount of bytes for the hash output from the PBKDF2 / scrypt hashing algorithm
	HASH_BYTES int = 64
)

The PBKDF2_* and SCRYPT_* constants may be changed without breaking existing stored hashes.

const (
	// HASH_SECTIONS identifies the expected amount of parameters encoded in a hash generated and/or tested in this package
	HASH_SECTIONS int = 4
	// HASH_ALGORITHM_INDEX identifies the position of the hash algorithm identifier in a hash generated and/or tested in this package
	HASH_ALGORITHM_INDEX int = 0
	// HASH_ITERATION_INDEX identifies the position of the iteration count used by PBKDF2 in a hash generated and/or tested in this package
	HASH_ITERATION_INDEX int = 1
	// HASH_SALT_INDEX identifies the position of the used salt in a hash generated and/or tested in this package
	HASH_SALT_INDEX int = 2
	// HASH_PBKDF2_INDEX identifies the position of the actual password hash in a hash generated and/or tested in this package
	HASH_PBKDF2_INDEX int = 3
	// HASH_SCRYPT_R_INDEX identifies the position of the scrypt block size parameter in a hash generated and/or tested in this package
	HASH_SCRYPT_R_INDEX int = 4
	// HASH_SCRYPT_R_INDEX identifies the position of the scrypt parallelization parameter in a hash generated and/or tested in this package
	HASH_SCRYPT_P_INDEX int = 5
)

altering the HASH_* constants breaks existing stored hashes

Functions

func CreateHash

func CreateHash(password string) (string, error)

CreateHash creates a salted cryptographic hash with key stretching (PBKDF2), suitable for storage and usage in password authentication mechanisms.

func ValidatePassword

func ValidatePassword(password string, correctHash string) bool

ValidatePassword hashes a password according to the setup found in the correct hash string and does a constant time compare on the correct hash and calculated hash.