scram

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
• Variables
• func Verify(hash string, plainText string) (bool, error)
• type GenerateOptions
  • func (options *GenerateOptions) Generate() (string, error)

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

func Verify(hash string, plainText string) (bool, error)

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.