Documentation
¶
Overview ¶
Package scram generates and verifies SCRAM-SHA-256 password hashes in the form PostgreSQL stores them in pg_authid.rolpassword, namely "SCRAM-SHA-256$<iter>:<salt>$<StoredKey>:<ServerKey>".
It is concerned with the on-disk representation of the secret only; it does not implement the SCRAM SASL authentication exchange between client and server.
Index ¶
Constants ¶
const DefaultPostgresIterations = 4096
DefaultPostgresIterations is the default number of PBKDF2 iterations used by PostgreSQL when hashing a SCRAM-SHA-256 secret, mirroring SCRAM_DEFAULT_ITERATIONS from PostgreSQL's src/include/common/scram-common.h.
const DefaultSaltLength = 16
DefaultSaltLength is the default raw-salt length used by PostgreSQL, mirroring SCRAM_DEFAULT_SALT_LEN from PostgreSQL's src/include/common/scram-common.h.
Variables ¶
var ( // ErrWrongComponents is returned when the hash is not split into the // three '$'-separated sections of the canonical SCRAM-SHA-256 form. ErrWrongComponents = errors.New("wrong number of components in password hash: expected 3 sections divided by '$'") // ErrWrongHashType is returned when the leading section of the hash is // not the literal "SCRAM-SHA-256". ErrWrongHashType = errors.New("wrong hash type (expected SCRAM-SHA-256)") // ErrWrongHashConfig is returned when the iter/salt section is not in // the expected "<iterations>:<salt>" form. ErrWrongHashConfig = errors.New( "wrong hash config (expected '<iterations>:<salt>' in the first '$' section)") // ErrWrongKeyComponents is returned when the key section is not in the // expected "<StoredKey>:<ServerKey>" form. ErrWrongKeyComponents = errors.New( "wrong key components (expected '<StoredKey>:<ServerKey>' in the last '$' section)") // ErrInvalidIterations is returned when the iteration count is not a // positive integer. ErrInvalidIterations = errors.New("iteration count must be a positive integer") // ErrInvalidStoredKey is returned when the StoredKey does not decode to // the SHA-256 digest size. ErrInvalidStoredKey = errors.New("stored key must decode to 32 bytes") // ErrInvalidServerKey is returned when the ServerKey does not decode to // the SHA-256 digest size. ErrInvalidServerKey = errors.New("server key must decode to 32 bytes") )
Functions ¶
func Verify ¶
Verify checks if the passed SCRAM hash, in the format used by PostgreSQL, corresponds to the given plain text. It returns true on a match, false on mismatch, and a non-nil error only when hash is malformed.
Verify performs PBKDF2 work proportional to the iteration count parsed from the hash, which the parser caps at 2^31-1 to match libpq. Callers that may receive attacker-influenced hashes should validate or cap the count further; PostgreSQL itself stores 4096 by default.
Types ¶
type GenerateOptions ¶
type GenerateOptions struct {
// Salt is the raw salt to be used. If empty, Generate uses a fresh
// salt of DefaultSaltLength bytes drawn from crypto/rand.
Salt []byte
// Iterations is the PBKDF2 iteration count. If zero, Generate uses
// DefaultPostgresIterations. A negative value is rejected with
// ErrInvalidIterations.
Iterations int
// PlainText is the password to be hashed.
PlainText string
}
GenerateOptions is the set of inputs to Generate.
func (*GenerateOptions) Generate ¶
func (options *GenerateOptions) Generate() (string, error)
Generate returns a SCRAM hash for these options. It does not mutate the receiver, so repeated calls with Salt unset each draw a fresh salt.
Source Files