crypto

Documentation

Overview

Package crypto holds the password (argon2id), TOTP, and random/constant-time primitives for the security spine (plan §5.1, §5.3).

Index

• Variables
• func ConstantTimeEqualString(a, b string) bool
• func GenerateTOTPCode(secret string, t time.Time) (string, error)
• func GenerateTOTPSecret() (string, error)
• func HashPassword(password []byte, p Argon2Params) (string, error)
• func RandomBytes(n int) []byte
• func RandomToken(n int) string
• func ValidateTOTP(secret, code string, t time.Time, skew int) bool
• func ValidateTOTPStep(secret, code string, t time.Time, skew int) (matched uint64, ok bool)
• func VerifyPassword(encoded string, password []byte) (bool, error)
• type Argon2Params
  • func ParseArgon2(encoded string) (p Argon2Params, salt, hash []byte, err error)

Variables

var (
	// ErrInvalidHash means the encoded hash is not a parseable argon2id PHC string.
	ErrInvalidHash = errors.New("crypto: invalid argon2id hash")
	// ErrIncompatibleVersion means the argon2 version is not the one we support.
	ErrIncompatibleVersion = errors.New("crypto: incompatible argon2 version")
)

var DefaultArgon2Params = Argon2Params{
	Memory:      8 * 1024,
	Time:        2,
	Parallelism: 1,
	SaltLen:     16,
	KeyLen:      32,
}

DefaultArgon2Params is the small, tiny-box-safe default.

Functions

func ConstantTimeEqualString

func ConstantTimeEqualString(a, b string) bool

ConstantTimeEqualString compares two strings without leaking length-prefixed timing for equal-length inputs.

func GenerateTOTPCode

func GenerateTOTPCode(secret string, t time.Time) (string, error)

GenerateTOTPCode returns the TOTP code for secret at time t (RFC 6238). Useful for provisioning/display and for tests.

func GenerateTOTPSecret

func GenerateTOTPSecret() (string, error)

GenerateTOTPSecret returns a base32 (RFC 4648, no padding) secret suitable for `mooring gen-totp` and authenticator apps.

func HashPassword

func HashPassword(password []byte, p Argon2Params) (string, error)

HashPassword produces an argon2id PHC string for the given password.

func RandomBytes

func RandomBytes(n int) []byte

RandomBytes returns n cryptographically random bytes or panics — a CSPRNG failure is unrecoverable and must never be swallowed into a weak token.

func RandomToken

func RandomToken(n int) string

RandomToken returns n random bytes encoded as URL-safe base64 (no padding). Used for session ids (32 bytes = 256 bits, plan §5.3) and webhook tokens.

func ValidateTOTP

func ValidateTOTP(secret, code string, t time.Time, skew int) bool

ValidateTOTP reports whether code is valid for secret at time t, allowing ±skew steps of clock drift. Per plan §5.9 the TOTP window is NOT widened under detected skew; callers pass skew=1 as the normal allowance.

func ValidateTOTPStep

func ValidateTOTPStep(secret, code string, t time.Time, skew int) (matched uint64, ok bool)

ValidateTOTPStep is like ValidateTOTP but also returns the matched time step, so callers can persist a consumed-step watermark and reject replays of a code within its validity window (review #4). The whole window is scanned in constant time (no early return) so a match position can't be timed.

func VerifyPassword

func VerifyPassword(encoded string, password []byte) (bool, error)

VerifyPassword reports whether password matches the encoded argon2id hash. The comparison is constant-time. A malformed hash returns (false, error).

Types

type Argon2Params

type Argon2Params struct {
	Memory      uint32 // KiB
	Time        uint32 // iterations
	Parallelism uint8
	SaltLen     uint32
	KeyLen      uint32
}

Argon2Params are tuned small by default (plan §5.1: m≈8 MiB, t=2, p=1) so a login can never OOM a tiny box. Raise Memory on a larger host.

func ParseArgon2

func ParseArgon2(encoded string) (p Argon2Params, salt, hash []byte, err error)

ParseArgon2 validates and decodes an argon2id PHC string. It is also the fail-closed boot check for auth.password_hash (plan §5.1).