kdfcrypt

README

Key derivation function for password hashing

kdfcrypt is a library for using KDF (key derivation function) to generate password hashing.

With this library, it is easy to make multiple password hashing algorithms coexist in the same program.

The currently supported KDFs are argon2, scrypt, pbkdf2 and hkdf. argon2id is the recommended choice for password hashing.

These algorithms are implemented in golang.org/x/crypto.

Example

Password verification

package main

import (
	"fmt"

	"github.com/xianghuzhao/kdfcrypt"
)

func main() {
	encoded, _ := kdfcrypt.Encode("password", &kdfcrypt.Option{
		Algorithm:        "argon2id",
		Param:            "m=65536,t=1,p=4",
		RandomSaltLength: 16,
		HashLength:       32,
	})

	// $argon2id$v=19,m=65536,t=1,p=4$mD+rvcR+6nuAV6MJFOmDjw$IqfwTPk9RMGeOv4pCE1QiURuSoi655GUVjcQAk81eXM
	fmt.Println(encoded)

	match, _ := kdfcrypt.Verify("password", encoded)
	fmt.Println(match) // true
}

Generate key for AES-256

For the case of getting a derived key for AES-256 (which needs a 32-byte key):

kdf, err := kdfcrypt.CreateKDF("argon2id", "m=4096,t=1,p=1")
salt, err := kdfcrypt.GenerateRandomSalt(16)
aes256Key, err := kdf.Derive("password", salt, 32)

The KDF algorithm, param and salt must be preserved in order to get the same key again.

Format of the encoded password

Password will be encoded into a single string which could be safely saved.

There are four parts of the encoded string which are splitted by "$".

1. The name of KDF.
2. Param string of the KDF, which depends on KDF.
3. Salt encoded with base64.
4. Hash key encoded with base64.

$argon2id$v=19,m=4096,t=1,p=1$4ns1ibGJDR6IQufkbT8E/w$WQ2lAwbDhZmZQMCMg74L00OHUFzn/IvbwDaxU6bgIys
$ KDF    $ param             $ salt (base64)        $ hash (base64)

Option

The Option struct is passed as argument for Encode.

1. Algorithm: Could be one of argon2id, argon2i, scrypt, pbkdf, hkdf.
2. Param: String for the KDF param. Different items are separated by comma ",". The detailed items vary among different KDFs.
3. RandomSaltLength: The length for the random salt in byte. If Salt is not empty, RandomSaltLength will be ignored.
4. Salt: Salt for the hash.
5. HashLength: The length of the hash result in byte.

You are able to set the salt explicitly:

encoded, _ := kdfcrypt.Encode("password", &kdfcrypt.Option{
	Algorithm:        "argon2id",
	Param:            "m=4096,t=1,p=1",
	Salt:             "This_is_fixed_salt",
	HashLength:       32,
})

If you would like to use random salt, do not set the Salt and set the RandomSaltLength:

encoded, _ := kdfcrypt.Encode("password", &kdfcrypt.Option{
	Algorithm:        "argon2id",
	Param:            "m=4096,t=1,p=1",
	RandomSaltLength: 16,
	HashLength:       32,
})

Supported KDF

Argon2

Two variants argon2i and argon2id are provided.

encodedArgon2i, _ := kdfcrypt.Encode("password", &kdfcrypt.Option{
	Algorithm:        "argon2i",
	Param:            "m=4096,t=1,p=1",
})
// $argon2i$v=19,m=4096,t=1,p=1$HGi1YMTQxF+LYrcsnAz2YQ$vB3J0eDGCeq2l8Ky96OqB1P9rr8KPOQZzEScZnq1IUA

encodedArgon2id, _ := kdfcrypt.Encode("password", &kdfcrypt.Option{
	Algorithm:        "argon2id",
	Param:            "m=4096,t=1,p=1",
})
// $argon2id$v=19,m=4096,t=1,p=1$23wOTcL162eix5YdOdOvqg$Il5kKW+CX+s6a8d6LtEnQ5k0bvBnfkuZXKkXq+Krx1I

The param consists of three parts:

1. m: memory, memory usage.
2. t: iterations, CPU cost.
3. p: parallelism, number of threads.

Scrypt

encoded, _ := kdfcrypt.Encode("password", &kdfcrypt.Option{
	Algorithm:        "scrypt",
	Param:            "N=32768,r=8,p=1",
})
// $scrypt$N=32768,r=8,p=1$v3T+aMCko9ZsovBnyWIdxQ$GTDo1AEPht8SL8Q+3y0FvWpPvzn5ZZNpwoqG+WOLsyI

1. N: CPU/memory cost parameter, which must be a power of two greater than 1.
2. r: The blocksize parameter, which fine-tunes sequential memory read size and performance. 8 is commonly used.
3. p: Parallelization parameter.

PBKDF2

encoded, _ := kdfcrypt.Encode("password", &kdfcrypt.Option{
	Algorithm:        "pbkdf2",
	Param:            "iter=1024,hash=sha512",
})
// $pbkdf2$iter=1024,hash=sha512$fvGxGq7tHzPgTJ3lGvl6XQ$O19iePvAQtlZ7nC5f5cS4C76bur9qMLp6dlPdXFiFTc

The iter is the iteration count for PBKDF.

The hash type could be one of the followings:

• md5
• sha1
• sha224
• sha256
• sha512
• sha384
• sha512/224
• sha512/256

HKDF

HKDF should not be used for password storage.

kdf, err := kdfcrypt.CreateKDF("hkdf", "hash=sha512,info=hkdf-test")
salt, err := kdfcrypt.GenerateRandomSalt(16)
key, err := kdf.Derive("password", salt, 32)

The hash type is the same as PBKDF. The info is optional.

Documentation

Index

• func Encode(password string, opt *Option) (string, error)
• func EncodeFromKDF(password string, kdf KDF, salt string, hashLength uint32) (string, error)
• func GenerateRandomSalt(saltLength uint32) ([]byte, error)
• func KDFName(kdf KDF) (string, error)
• func ListKDFAlgorithms() []string
• func RegisterKDF(algorithm string, kdf KDF)
• func Verify(password, encoded string) (bool, error)
• type Argon2
  • func (kdf *Argon2) SetDefaultParam()
• type Argon2i
  • func (kdf *Argon2i) Derive(password, salt []byte, hashLength uint32) ([]byte, error)
• type Argon2id
  • func (kdf *Argon2id) Derive(password, salt []byte, hashLength uint32) ([]byte, error)
• type HKDF
  • func (kdf *HKDF) Derive(password, salt []byte, hashLength uint32) ([]byte, error)
  • func (kdf *HKDF) SetDefaultParam()
• type KDF
  • func CreateKDF(algorithm, param string) (KDF, error)
• type Option
• type PBKDF2
  • func (kdf *PBKDF2) Derive(password, salt []byte, hashLength uint32) ([]byte, error)
  • func (kdf *PBKDF2) SetDefaultParam()
• type Scrypt
  • func (kdf *Scrypt) Derive(password, salt []byte, hashLength uint32) ([]byte, error)
  • func (kdf *Scrypt) SetDefaultParam()

Functions

func Encode

func Encode(password string, opt *Option) (string, error)

Encode generates encoded password.

func EncodeFromKDF

func EncodeFromKDF(password string, kdf KDF, salt string, hashLength uint32) (string, error)

EncodeFromKDF encode the password with the given KDF.

func GenerateRandomSalt

func GenerateRandomSalt(saltLength uint32) ([]byte, error)

GenerateRandomSalt generates random salt.

func KDFName

func KDFName(kdf KDF) (string, error)

KDFName returns the algorithm name of the KDF.

func ListKDFAlgorithms

func ListKDFAlgorithms() []string

ListKDFAlgorithms list all the available kdf algorithms.

func RegisterKDF

func RegisterKDF(algorithm string, kdf KDF)

RegisterKDF register a KDF with algorithm name.

func Verify

func Verify(password, encoded string) (bool, error)

Verify password and encoded password.

Types

type Argon2

type Argon2 struct {
	Version     uint8  `param:"v"`
	Memory      uint32 `param:"m"`
	Iteration   uint32 `param:"t"`
	Parallelism uint8  `param:"p"`
}

Argon2 base params.

func (*Argon2) SetDefaultParam

func (kdf *Argon2) SetDefaultParam()

SetDefaultParam sets the default param for argon2.

type Argon2i

type Argon2i struct {
	Argon2
}

Argon2i deals with argon2i KDF.

func (*Argon2i) Derive

func (kdf *Argon2i) Derive(password, salt []byte, hashLength uint32) ([]byte, error)

Derive hash with Argon2i.

type Argon2id

type Argon2id struct {
	Argon2
}

Argon2id deals with argon2id KDF.

func (*Argon2id) Derive

func (kdf *Argon2id) Derive(password, salt []byte, hashLength uint32) ([]byte, error)

Derive hash with Argon2id.

type HKDF

type HKDF struct {
	HashFunc string `param:"hash"`
	Info     string `param:"info"`
}

HKDF params.

func (*HKDF) Derive

func (kdf *HKDF) Derive(password, salt []byte, hashLength uint32) ([]byte, error)

Derive hash with hkdf.

func (*HKDF) SetDefaultParam

func (kdf *HKDF) SetDefaultParam()

SetDefaultParam sets the default param for hkdf.

type KDF

type KDF interface {
	SetDefaultParam()
	Derive(password, salt []byte, hashLength uint32) ([]byte, error)
}

KDF should be implemented for different kdfs.

func CreateKDF

func CreateKDF(algorithm, param string) (KDF, error)

CreateKDF creates key derivation function.

type Option

type Option struct {
	Algorithm        string
	Param            string
	RandomSaltLength uint32
	Salt             string
	HashLength       uint32
}

Option for generating hash from KDF.

type PBKDF2

type PBKDF2 struct {
	Iteration uint32 `param:"iter"`
	HashFunc  string `param:"hash"`
}

PBKDF2 params.

func (*PBKDF2) Derive

func (kdf *PBKDF2) Derive(password, salt []byte, hashLength uint32) ([]byte, error)

Derive hash with PBKDF2.

func (*PBKDF2) SetDefaultParam

func (kdf *PBKDF2) SetDefaultParam()

SetDefaultParam sets the default param for PBKDF2.

type Scrypt

type Scrypt struct {
	Cost            int `param:"N"`
	BlockSize       int `param:"r"`
	Parallelization int `param:"p"`
}

Scrypt params.

func (*Scrypt) Derive

func (kdf *Scrypt) Derive(password, salt []byte, hashLength uint32) ([]byte, error)

Derive hash with scrypt.

func (*Scrypt) SetDefaultParam

func (kdf *Scrypt) SetDefaultParam()

SetDefaultParam sets the default param for scrypt.