Documentation
¶
Index ¶
- Variables
- type Argon2Option
- type BcryptOption
- type Encoder
- func NewArgon2Encoder(opts ...Argon2Option) Encoder
- func NewBcryptEncoder(opts ...BcryptOption) Encoder
- func NewCipherEncoder(cipher crypto.Cipher, encoder Encoder) Encoder
- func NewCompositeEncoder(defaultEncoderId EncoderId, encoders map[EncoderId]Encoder) Encoder
- func NewMd5Encoder(opts ...Md5Option) Encoder
- func NewPbkdf2Encoder(opts ...Pbkdf2Option) Encoder
- func NewPlaintextEncoder() Encoder
- func NewScryptEncoder(opts ...ScryptOption) Encoder
- func NewSha256Encoder(opts ...Sha256Option) Encoder
- type EncoderId
- type Md5Option
- type Pbkdf2Option
- type ScryptOption
- type Sha256Option
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidCost is returned when bcrypt cost is outside valid range (4-31). ErrInvalidCost = errors.New("invalid bcrypt cost: must be between 4 and 31") // ErrInvalidMemory is returned when argon2 memory parameter is too small. ErrInvalidMemory = errors.New("invalid argon2 memory: must be at least 8 KiB") // ErrInvalidIterations is returned when iteration count is less than 1. ErrInvalidIterations = errors.New("invalid iterations: must be at least 1") // ErrInvalidParallelism is returned when parallelism is less than 1. ErrInvalidParallelism = errors.New("invalid parallelism: must be at least 1") // ErrInvalidEncoderId is returned when CompositeEncoder receives an unknown encoder ID. ErrInvalidEncoderId = errors.New("invalid encoder id: encoder not found") // ErrInvalidHashFormat is returned when encoded password has unexpected format. ErrInvalidHashFormat = errors.New("invalid hash format") // ErrDefaultEncoderNotFound is returned when the default encoder ID is not registered in CompositeEncoder. ErrDefaultEncoderNotFound = errors.New("default encoder not found in registered encoders") // ErrCipherRequired is returned when cipher is not provided to CipherEncoder. ErrCipherRequired = errors.New("cipher is required") // ErrEncoderRequired is returned when encoder is not provided to CipherEncoder. ErrEncoderRequired = errors.New("encoder is required") )
Functions ¶
This section is empty.
Types ¶
type Argon2Option ¶
type Argon2Option func(*argon2Encoder)
Argon2Option configures argon2Encoder.
func WithArgon2Iterations ¶
func WithArgon2Iterations(iterations uint32) Argon2Option
WithArgon2Iterations sets the number of iterations.
func WithArgon2Memory ¶
func WithArgon2Memory(memory uint32) Argon2Option
WithArgon2Memory sets the memory parameter in KiB.
func WithArgon2Parallelism ¶
func WithArgon2Parallelism(parallelism uint8) Argon2Option
WithArgon2Parallelism sets the parallelism factor.
type BcryptOption ¶
type BcryptOption func(*bcryptEncoder)
BcryptOption configures bcryptEncoder.
func WithBcryptCost ¶
func WithBcryptCost(cost int) BcryptOption
WithBcryptCost sets the bcrypt cost factor (4-31). Higher cost increases security but also computation time.
type Encoder ¶
type Encoder interface {
// Encode encodes the raw password (e.g., hashing, encrypting).
// Returns the encoded password or an error if encoding fails.
Encode(password string) (string, error)
// Matches verifies whether the raw password matches the encoded password.
// Returns true if the passwords match, false otherwise.
Matches(password, encodedPassword string) bool
// UpgradeEncoding determines whether the encoded password should be re-encoded.
// This is useful for algorithm migration or cost factor upgrades.
// Returns true if the password should be upgraded, false otherwise.
UpgradeEncoding(encodedPassword string) bool
}
Encoder defines the interface for password encoding and verification.
func NewArgon2Encoder ¶
func NewArgon2Encoder(opts ...Argon2Option) Encoder
NewArgon2Encoder creates a new Argon2id-based password encoder. Defaults: memory=64MB, iterations=3, parallelism=4 (OWASP recommendations for 2024).
func NewBcryptEncoder ¶
func NewBcryptEncoder(opts ...BcryptOption) Encoder
NewBcryptEncoder creates a new bcrypt-based password encoder. Default cost is bcrypt.DefaultCost (10).
func NewCipherEncoder ¶
NewCipherEncoder creates a new cipher-based password encoder that decrypts passwords before encoding. The cipher decrypts encrypted passwords, and the encoder performs the actual password encoding. Both cipher and encoder are required parameters.
func NewCompositeEncoder ¶
NewCompositeEncoder creates a composite encoder that supports multiple password formats. The defaultEncoderId specifies which encoder to use for new passwords. Encoders map contains encoder ID to Encoder implementations.
func NewMd5Encoder ¶
NewMd5Encoder creates a new MD5-based password encoder. WARNING: Use only for legacy system compatibility.
func NewPbkdf2Encoder ¶
func NewPbkdf2Encoder(opts ...Pbkdf2Option) Encoder
NewPbkdf2Encoder creates a new PBKDF2-based password encoder. Defaults: 310,000 iterations with SHA-256 (OWASP 2023 recommendations).
func NewPlaintextEncoder ¶
func NewPlaintextEncoder() Encoder
NewPlaintextEncoder creates a new plaintext password encoder. WARNING: Provides NO security. Use only for testing/development.
func NewScryptEncoder ¶
func NewScryptEncoder(opts ...ScryptOption) Encoder
NewScryptEncoder creates a new scrypt-based password encoder. Defaults: N=32768 (2^15), r=8, p=1 (OWASP recommendations for interactive logins).
func NewSha256Encoder ¶
func NewSha256Encoder(opts ...Sha256Option) Encoder
NewSha256Encoder creates a new SHA-256-based password encoder. WARNING: Use only for legacy system compatibility.
type Md5Option ¶
type Md5Option func(*hashEncoder)
Md5Option configures MD5 encoder.
func WithMd5Salt ¶
WithMd5Salt sets a static salt value. WARNING: Static salts provide minimal security. Use modern algorithms like Argon2 for new systems.
func WithMd5SaltPosition ¶
WithMd5SaltPosition sets where the salt is placed ("prefix" or "suffix").
type Pbkdf2Option ¶
type Pbkdf2Option func(*pbkdf2Encoder)
Pbkdf2Option configures pbkdf2Encoder.
func WithPbkdf2HashFunction ¶
func WithPbkdf2HashFunction(hashFunction string) Pbkdf2Option
WithPbkdf2HashFunction sets the hash function ("sha256" or "sha512").
func WithPbkdf2Iterations ¶
func WithPbkdf2Iterations(iterations int) Pbkdf2Option
WithPbkdf2Iterations sets the number of iterations.
type ScryptOption ¶
type ScryptOption func(*scryptEncoder)
ScryptOption configures scryptEncoder.
func WithScryptN ¶
func WithScryptN(n int) ScryptOption
WithScryptN sets the CPU/memory cost parameter (must be a power of 2).
func WithScryptP ¶
func WithScryptP(p int) ScryptOption
WithScryptP sets the parallelization parameter.
type Sha256Option ¶
type Sha256Option func(*hashEncoder)
Sha256Option configures SHA-256 encoder.
func WithSha256Salt ¶
func WithSha256Salt(salt string) Sha256Option
WithSha256Salt sets a static salt value. WARNING: Static salts provide minimal security. Use modern algorithms like Argon2 for new systems.
func WithSha256SaltPosition ¶
func WithSha256SaltPosition(position string) Sha256Option
WithSha256SaltPosition sets where the salt is placed ("prefix" or "suffix").
Source Files