Documentation
¶
Overview ¶
Package crypto provides password hashing and verification using the argon2id algorithm. The PHC string format is used so parameters are self-describing and future algorithm changes do not require a separate migration column.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidKey is returned by NewCipher when the key is not 32 bytes. ErrInvalidKey = errors.New("crypto: encryption key must be 32 bytes") // ErrMalformedCiphertext is returned by Decrypt when the input is too short // to contain a nonce or otherwise fails authentication. ErrMalformedCiphertext = errors.New("crypto: malformed ciphertext") )
Crypto errors for the symmetric cipher.
var ErrMalformedHash = errors.New("crypto: malformed argon2id hash")
ErrMalformedHash is returned by Verify when the encoded string is not a valid PHC-format argon2id hash produced by Hash.
Functions ¶
func Hash ¶
Hash derives a new argon2id hash from password using a freshly generated random salt and returns the PHC-encoded string. Each call produces a different output even for the same password (due to the random salt), so the returned string must be stored and compared with Verify, not compared directly.
Hash returns an error only when the system's random source is unavailable, which is a fatal condition.
func Verify ¶
Verify checks whether password matches the PHC-encoded argon2id hash produced by Hash. It returns (true, nil) on a match, (false, nil) on a mismatch, and (false, ErrMalformedHash) when encoded is not a valid PHC argon2id string. The comparison is constant-time to resist timing attacks.
Types ¶
type Cipher ¶
type Cipher struct {
// contains filtered or unexported fields
}
Cipher encrypts and decrypts small secrets (e.g. OAuth tokens) at rest using AES-256-GCM, which provides confidentiality and authentication. The key is injected via the constructor (never a package global) so it can be sourced from configuration and kept out of logs.
func NewCipher ¶
NewCipher constructs a Cipher from a 32-byte key, returning ErrInvalidKey for any other length.
type Hasher ¶
type Hasher struct {
// contains filtered or unexported fields
}
Hasher derives and verifies argon2id hashes at a fixed cost. Construct one with NewHasher and inject it, rather than calling the package-level Hash and Verify, wherever the cost needs to be selectable (see Params).
func (*Hasher) Hash ¶
Hash derives a new argon2id hash at h's configured cost. See the package-level Hash for the full contract.
func (*Hasher) Verify ¶
Verify checks password against the PHC-encoded hash. See the package-level Verify for the full contract.
The receiver's Params are deliberately unused: the cost parameters come from the encoded hash itself, so a Hasher verifies hashes produced at ANY cost, including ones written before it was configured. Verify is a method purely so that Hash and Verify can be injected together as one seam.
type Params ¶
type Params struct {
// Time is the number of passes over the memory.
Time uint32
// Memory is the memory cost in KiB.
Memory uint32
// Threads is the degree of parallelism.
Threads uint8
}
Params holds the tunable argon2id cost parameters. Only the cost knobs are configurable; the salt and key lengths are fixed package-wide (see above).
Production code must use DefaultParams. The type is exported so that tests, which would otherwise pay a 64 MiB memory-hard derivation per hash, can construct a Hasher with cheap parameters: recovery-code flows hash ten codes per enrollment, which dominated the test suite's runtime.
Lowering these values weakens resistance to offline dictionary attacks and is only ever safe for throwaway test fixtures.
func DefaultParams ¶
func DefaultParams() Params
DefaultParams returns the OWASP-recommended production cost parameters.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cryptotest provides test-only helpers for the crypto package, following the convention of the standard library's httptest.
|
Package cryptotest provides test-only helpers for the crypto package, following the convention of the standard library's httptest. |