auth

Documentation

Overview

Package auth implements SCRAM-SHA-256 (RFC 5802) over the lsqlited JSON framing instead of the SASL text encoding. The password never travels over the wire:

saltedPassword = PBKDF2-SHA256(password, salt, iterations)
clientKey      = HMAC-SHA256(saltedPassword, "Client Key")
storedKey      = SHA256(clientKey)
serverKey      = HMAC-SHA256(saltedPassword, "Server Key")
clientProof    = clientKey XOR HMAC-SHA256(storedKey, authMessage)

The server stores only salt, iterations, storedKey and serverKey, so a leaked configuration file does not by itself allow an attacker to authenticate, and answers with HMAC-SHA256(serverKey, authMessage), which authenticates the server in turn. Both directions are bound to fresh random nonces, so recorded handshakes cannot be replayed.

Index

• Constants
• func AuthMessage(user string, clientNonce, serverNonce, salt []byte, iterations int) string
• func ClientProof(saltedPassword []byte, authMessage string) []byte
• func Nonce() ([]byte, error)
• func SaltPassword(password string, salt []byte, iterations int) ([]byte, error)
• func Secret() ([]byte, error)
• func ServerSignature(saltedPassword []byte, authMessage string) []byte
• type Verifier
  • func DecoyVerifier(secret []byte, user string, iterations int) *Verifier
  • func NewVerifier(password string, iterations int) (*Verifier, error)
  • func ParseVerifier(s string) (*Verifier, error)
  • func (v *Verifier) ServerSignature(authMessage string) []byte
  • func (v *Verifier) String() string
  • func (v *Verifier) Verify(authMessage string, proof []byte) bool

Constants

const (
	// DefaultIterations matches the PostgreSQL default: clients run the derivation once per new connection, so a much
	// larger count would make connection setup noticeably slower.
	DefaultIterations = 4096
	// MinIterations is the smallest count accepted by both peers, and MaxIterations bounds the work a malicious server can
	// force on a client.
	MinIterations = 1000
	MaxIterations = 1 << 20

	// SaltLen is the length of a generated salt. MinSaltLen is the floor recommended by RFC 8018, and what crypto/pbkdf2
	// demands under GODEBUG=fips140=only.
	SaltLen    = 16
	MinSaltLen = 16
	// NonceLen is the length of a generated nonce; MinNonceLen is the smallest accepted from the peer.
	NonceLen    = 24
	MinNonceLen = 16
)

const Mechanism = "SCRAM-SHA-256"

Mechanism is the name of the authentication mechanism, used as the prefix of the textual verifier encoding.

Functions

func AuthMessage

func AuthMessage(user string, clientNonce, serverNonce, salt []byte, iterations int) string

AuthMessage builds the string both peers sign. It covers every parameter that influences the handshake, so a man in the middle cannot swap the salt or downgrade the iteration count without the proof failing. The user name is base64-encoded to keep the separators unambiguous.

func ClientProof

func ClientProof(saltedPassword []byte, authMessage string) []byte

ClientProof computes the proof the client sends to the server.

func Nonce

func Nonce() ([]byte, error)

Nonce returns NonceLen cryptographically random bytes.

func SaltPassword

func SaltPassword(password string, salt []byte, iterations int) ([]byte, error)

SaltPassword derives the salted password shared by both peers. It fails only on out-of-range parameters, which both peers reject before getting this far, or under GODEBUG=fips140=only with a salt that is too short.

func Secret

func Secret() ([]byte, error)

Secret returns a random per-process secret used to derive decoy verifiers.

func ServerSignature

func ServerSignature(saltedPassword []byte, authMessage string) []byte

ServerSignature computes the signature the client expects back from the server, from the client's own salted password.

Types

type Verifier

type Verifier struct {
	Iterations int
	Salt       []byte
	StoredKey  []byte
	ServerKey  []byte
}

Verifier holds everything the server needs to check a client proof. It is password-equivalent only in that it allows offline guessing; it cannot be replayed as a credential.

func DecoyVerifier

func DecoyVerifier(secret []byte, user string, iterations int) *Verifier

DecoyVerifier deterministically fabricates a verifier for an unknown user so that the server's challenge looks identical whether or not the account exists. Proofs checked against it never succeed, and repeated probes for the same name always observe the same salt.

func NewVerifier

func NewVerifier(password string, iterations int) (*Verifier, error)

NewVerifier derives a verifier for password using a freshly generated random salt. A non-positive iterations value selects DefaultIterations.

func ParseVerifier

func ParseVerifier(s string) (*Verifier, error)

ParseVerifier decodes the textual form produced by Verifier.String.

func (*Verifier) ServerSignature

func (v *Verifier) ServerSignature(authMessage string) []byte

ServerSignature returns the proof of possession the server sends back so that the client can authenticate the server.

func (*Verifier) String

func (v *Verifier) String() string

String encodes the verifier in the PostgreSQL SCRAM format, with the salt and keys in standard base64:

SCRAM-SHA-256$<iterations>:<salt>$<storedKey>:<serverKey>

func (*Verifier) Verify

func (v *Verifier) Verify(authMessage string, proof []byte) bool

Verify reports whether proof is a valid client proof for authMessage.