Documentation
¶
Overview ¶
Package kdf defines the KeyDerivation interface for key derivation functions. It also provides common KDF implementations including PBKDF2, scrypt, and Argon2id.
Index ¶
- Variables
- type KeyDerivation
- func CheapArgon2id() KeyDerivation
- func CheapHkdf() KeyDerivation
- func CheapPbkdf2() KeyDerivation
- func CheapScrypt() KeyDerivation
- func NewArgon2id(time uint32, memory uint32, threads uint8) KeyDerivation
- func NewHkdf(hashFunc func() hash.Hash, info []byte, iter int) KeyDerivation
- func NewPbkdf2(iter int, hashFunc func() hash.Hash) KeyDerivation
- func NewScrypt(N, r, p int) KeyDerivation
- func RecommendedArgon2id() KeyDerivation
- func RecommendedHkdf() KeyDerivation
- func RecommendedPbkdf2() KeyDerivation
- func RecommendedScrypt() KeyDerivation
- func StrongArgon2id() KeyDerivation
- func StrongHkdf() KeyDerivation
- func StrongPbkdf2() KeyDerivation
- func StrongScrypt() KeyDerivation
Constants ¶
This section is empty.
Variables ¶
var ( ErrNegKeyLen = errors.New("invalid key length (negative)") ErrPanic = errors.New("recovered from panic") ErrKdfConfig = errors.New("invalid KDF configuration") )
ErrNegKeyLen indicates that the provided key length (keyLen) is negative, which is invalid for key derivation functions. In such cases, a nil byte slice and ErrNegKeyLen should be returned by the Derive method.
Functions ¶
This section is empty.
Types ¶
type KeyDerivation ¶
type KeyDerivation interface {
// Derive derives a key from the given password and salt.
Derive(password, salt []byte, keyLen int) ([]byte, error)
}
KeyDerivation is a key derivation function (KDF) interface.
Prefer:
- generic key derivation: Argon2id > scrypt > PBKDF2.
- for machine secrets (fast key splitting/refining): use HKDF.
Edge cases:
- password and salt can be any legal []byte value, including empty byte slice, nil, and arbitrary length.
- keyLen can be zero: resulting in an empty key and nil error ([]byte{}, nil).
- keyLen cannot be negative: resulting in a nil key and an error (nil, ErrNegKeyLen).
- keyLen is limited to maximum of 1<<20 bytes for PBKDF2 and 1<<11 bytes for HKDF, for performance and entropy reasons respectively. Argon2id and scrypt are limited to 1<<31 bytes.
KeyDerivation is for internal use in simplecipher only. So it is NOT simplified to accept string args like the outer Block/Stream interfaces do. This is by design.
func CheapArgon2id ¶
func CheapArgon2id() KeyDerivation
CheapArgon2id will comfortably run in ~ 10ms on modern (2025) laptops.
func CheapHkdf ¶
func CheapHkdf() KeyDerivation
CheapHkdf uses SHA256 with no info and no extra iterations for HKDF.
func CheapPbkdf2 ¶
func CheapPbkdf2() KeyDerivation
CheapPbkdf2 uses 10,000 SHA1 iterations for low memory usage and fast derivation. Commonly take <=1ms on modern (2025) hardware.
It is NOT recommended for new applications.
func CheapScrypt ¶
func CheapScrypt() KeyDerivation
CheapScrypt use N=2^13 (8 MiB) for low memory usage and fast derivation.
Commonly take around 10ms on modern (2025) hardware.
func NewArgon2id ¶
func NewArgon2id(time uint32, memory uint32, threads uint8) KeyDerivation
NewArgon2id creates a new Argon2id key derivation function with the specified parameters. The CPU cost and parallelism degree must be greater than zero.
RFC 9106 Section 7.3 recommends time=1, and memory=64*1024 as a sensible number. If using that amount of memory (64 MB) is not possible in some contexts then the time parameter can be increased to compensate.
The time parameter specifies the number of passes over the memory and the memory parameter specifies the size of the memory in KiB. For example memory=64*1024 sets the memory cost to ~64 MB. The number of threads can be adjusted to the numbers of available CPUs. The cost parameters should be increased as memory latency and CPU parallelism increases.
func NewPbkdf2 ¶
func NewPbkdf2(iter int, hashFunc func() hash.Hash) KeyDerivation
NewPbkdf2 creates a PBKDF2 key derivation function.
pbkdf2 derives a key based on the method described as PBKDF2 with the HMAC variant using the supplied hash function.
Using a higher iteration count will increase the cost of an exhaustive search but will also make derivation proportionally slower.
func NewScrypt ¶
func NewScrypt(N, r, p int) KeyDerivation
NewScrypt creates a scrypt key derivation function.
scrypt derives a key that can be used as cryptographic key.
N is a CPU/memory cost parameter, which must be a power of two greater than 1. r and p must satisfy r * p < 2^30. If the parameters do not satisfy the limits, the function returns a nil byte slice and an error.
The recommended parameters for interactive logins as of 2017 are N=32768, r=8 and p=1. The parameters N, r, and p should be increased as memory latency and CPU parallelism increases; consider setting N to the highest power of 2 you can derive within 100 milliseconds.
func RecommendedArgon2id ¶
func RecommendedArgon2id() KeyDerivation
RecommendedArgon2id is in the middle of the OWASP RECOMMENDATION and the RFC 9106 SECOND RECOMMENDATION.
It requires about 64MB of RAM and will take around 80ms.
func RecommendedHkdf ¶
func RecommendedHkdf() KeyDerivation
RecommendedHkdf uses SHA256 with hardcoded info "MGUwOTRj" (random generated by developer) and 1 extra iteration for HKDF.
func RecommendedPbkdf2 ¶
func RecommendedPbkdf2() KeyDerivation
RecommendedPbkdf2 uses 100,000 SHA256 iterations as of 2024 recommendations.
Commonly take around 10ms on modern (2025) hardware.
func RecommendedScrypt ¶
func RecommendedScrypt() KeyDerivation
RecommendedScrypt use N=2^15 (32 MiB) as golang.org/x/crypto/scrypt RECOMMENDED.
Commonly take around 40ms on modern (2025) hardware.
func StrongArgon2id ¶
func StrongArgon2id() KeyDerivation
StrongArgon2id is the FIRST RECOMMENDED SETTINGS from RFC 9106 Section 7.4.
It requires about 2GB of RAM and will take more than 1s (<2s) on common hardware in 2025.
func StrongHkdf ¶
func StrongHkdf() KeyDerivation
StrongHkdf uses SHA256 with hardcoded info "ZTQwODc2ZWYtMmQy" (random generated by developer) and 2 extra iterations for HKDF.
func StrongPbkdf2 ¶
func StrongPbkdf2() KeyDerivation
StrongPbkdf2 uses 600,000 SHA256 iterations for stronger security as of OWASP recommendations.
Commonly take around 50ms on modern (2025) hardware.
func StrongScrypt ¶
func StrongScrypt() KeyDerivation
StrongScrypt use N=2^17 (128 MiB) as OWASP RECOMMENDED.
Commonly take ~160ms on modern (2025) hardware.
Source Files