Password Hashing

The crypto/password package provides a KDF-agnostic Encoder interface and a DelegatingEncoder that tags each stored hash with an {id} algorithm prefix, so multiple algorithms can coexist in the same password column.

Import

import "github.com/thuongh2/go-security/crypto/password"

Encoder interface

type Encoder interface {
    Encode(raw string) (string, error)
    Matches(raw, encoded string) bool
}

Matches must run in constant time to resist timing attacks.

DelegatingEncoder

Routes encode/verify calls to the right algorithm based on the {id} prefix.

enc := password.NewDelegatingEncoder(password.IDBcrypt)

Pre-registered delegates:

ID	Algorithm
`{bcrypt}`	bcrypt (default)
`{argon2id}`	Argon2id
`{argon2}`	Accepted alias for argon2id
`{noop}`	Plaintext (tests only)

Legacy unprefixed hashes

For a column with unprefixed bcrypt hashes (predating the {id} prefix convention):

enc := password.NewDelegatingEncoder(password.IDBcrypt,
    password.WithDefaultForMatches(
        password.NewBcryptEncoder(password.DefaultBcryptCost), // cost=10
    ),
)

Old rows verify with the fallback; new writes get the {bcrypt} prefix. No re-hashing migration job required.

Registering a custom encoder

enc := password.NewDelegatingEncoder(password.IDBcrypt,
    password.WithEncoder("scrypt", myScryptEncoder),
)

BcryptEncoder

enc := password.NewBcryptEncoder(password.DefaultBcryptCost) // cost=10
enc := password.NewBcryptEncoder(14)                         // higher cost

DefaultBcryptCost is 10 — a widely-used baseline that balances hashing time against brute-force resistance. A cost outside bcrypt’s valid range falls back to the default.

Argon2idEncoder

enc := password.NewArgon2idEncoder()

Default parameters: m=65536 (64 MiB), t=3 iterations, p=2 threads. Override any of them with functional options:

enc := password.NewArgon2idEncoder(
    password.WithArgon2Memory(131072), // 128 MiB
    password.WithArgon2Iterations(4),
    password.WithArgon2Parallelism(4),
    password.WithArgon2SaltLen(16),
    password.WithArgon2KeyLen(32),
)

Out-of-range values are clamped to RFC 9106’s floor and a resource ceiling rather than erroring, so a misconfigured option can’t silently produce a weak hash or an accidental denial-of-service.

NoopEncoder

enc := password.NewNoopEncoder()

Stores and compares passwords as plain text. Tests and local development only — never use it in production.

Choosing an algorithm

Algorithm	Use when
bcrypt	Default; wide ecosystem support
argon2id	New systems; memory-hard; OWASP recommended
noop	Unit tests only — never in production

Encoding a new password

hash, err := enc.Encode("s3cret")
// e.g. "{bcrypt}$2a$10$..."

Store hash in your users.password_hash column.

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Import

Encoder interface

DelegatingEncoder

Legacy unprefixed hashes

Registering a custom encoder

BcryptEncoder

Argon2idEncoder

NoopEncoder

Choosing an algorithm

Encoding a new password

​Import

​Encoder interface

​DelegatingEncoder

​Legacy unprefixed hashes

​Registering a custom encoder

​BcryptEncoder

​Argon2idEncoder

​NoopEncoder

​Choosing an algorithm

​Encoding a new password

Import

Encoder interface

DelegatingEncoder

Legacy unprefixed hashes

Registering a custom encoder

BcryptEncoder

Argon2idEncoder

NoopEncoder

Choosing an algorithm

Encoding a new password