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.
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
}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.
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 "$".
- The name of KDF.
- Param string of the KDF, which depends on KDF.
- Salt encoded with base64.
- Hash key encoded with base64.
$argon2id$v=19,m=4096,t=1,p=1$4ns1ibGJDR6IQufkbT8E/w$WQ2lAwbDhZmZQMCMg74L00OHUFzn/IvbwDaxU6bgIys
$ KDF $ param $ salt (base64) $ hash (base64)
The Option struct is passed as argument for Encode.
- Algorithm: Could be one of
argon2id,argon2i,scrypt,pbkdf,hkdf. - Param: String for the KDF param. Different items are separated by
comma "
,". The detailed items vary among different KDFs. - RandomSaltLength: The length for the random salt in byte. If
Saltis not empty,RandomSaltLengthwill be ignored. - Salt: Salt for the hash.
- 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,
})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+Krx1IThe param consists of three parts:
- m: memory, memory usage.
- t: iterations, CPU cost.
- p: parallelism, number of threads.
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- N: CPU/memory cost parameter, which must be a power of two greater than 1.
- r: The blocksize parameter, which fine-tunes sequential memory read size and performance. 8 is commonly used.
- p: Parallelization parameter.
encoded, _ := kdfcrypt.Encode("password", &kdfcrypt.Option{
Algorithm: "pbkdf2",
Param: "iter=1024,hash=sha512",
})
// $pbkdf2$iter=1024,hash=sha512$fvGxGq7tHzPgTJ3lGvl6XQ$O19iePvAQtlZ7nC5f5cS4C76bur9qMLp6dlPdXFiFTcThe 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 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent