mfa

package
v1.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 17, 2026 License: GPL-3.0 Imports: 14 Imported by: 0

Documentation

Overview

Package mfa provides multi-factor authentication helpers with safe defaults.

Index

Constants

View Source 
const (
	// AlgorithmSHA1 uses HMAC-SHA1.
	AlgorithmSHA1 = otp.AlgorithmSHA1
	// AlgorithmSHA256 uses HMAC-SHA256.
	AlgorithmSHA256 = otp.AlgorithmSHA256
	// AlgorithmSHA512 uses HMAC-SHA512.
	AlgorithmSHA512 = otp.AlgorithmSHA512
)
View Source 
const (
	// DigitsSix uses 6-digit OTP codes.
	DigitsSix = otp.DigitsSix
	// DigitsEight uses 8-digit OTP codes.
	DigitsEight = otp.DigitsEight
)

Variables

View Source 
var (
	// ErrInvalidMFAConfig indicates the MFA configuration is invalid.
	ErrInvalidMFAConfig = ewrap.New("invalid mfa config")
	// ErrMFAConflictingOptions indicates MFA options are conflicting.
	ErrMFAConflictingOptions = ewrap.New("mfa options are conflicting")
	// ErrMFAMissingIssuer indicates the issuer is required.
	ErrMFAMissingIssuer = ewrap.New("mfa issuer is required")
	// ErrMFAMissingAccountName indicates the account name is required.
	ErrMFAMissingAccountName = ewrap.New("mfa account name is required")
	// ErrMFAInvalidSecret indicates the secret is invalid.
	ErrMFAInvalidSecret = ewrap.New("mfa secret is invalid")
	// ErrMFASecretTooShort indicates the secret is too short.
	ErrMFASecretTooShort = ewrap.New("mfa secret is too short")
	// ErrMFASecretTooLong indicates the secret is too long.
	ErrMFASecretTooLong = ewrap.New("mfa secret is too long")
	// ErrMFAInvalidCode indicates the otp code is invalid.
	ErrMFAInvalidCode = ewrap.New("mfa otp code is invalid")
	// ErrMFARateLimited indicates an MFA verification was rate limited.
	ErrMFARateLimited = ewrap.New("mfa rate limit exceeded")
	// ErrMFABackupGenerationFailed indicates backup code generation failed.
	ErrMFABackupGenerationFailed = ewrap.New("mfa backup code generation failed")
	// ErrMFABackupHashFailed indicates backup code hashing failed.
	ErrMFABackupHashFailed = ewrap.New("mfa backup code hashing failed")
	// ErrMFABackupVerificationFailed indicates backup code verification failed.
	ErrMFABackupVerificationFailed = ewrap.New("mfa backup code verification failed")
	// ErrMFAInvalidCounter indicates the hotp counter is invalid.
	ErrMFAInvalidCounter = ewrap.New("mfa counter is invalid")
)

Functions

func GenerateHOTPKey 

func GenerateHOTPKey(opts ...HOTPKeyOption) (*otp.Key, error)

GenerateHOTPKey creates a new provisioning key with a randomized secret.

func GenerateTOTPKey 

func GenerateTOTPKey(opts ...TOTPKeyOption) (*otp.Key, error)

GenerateTOTPKey creates a new provisioning key with a randomized secret.

Types

type Algorithm 

type Algorithm = otp.Algorithm

Algorithm defines the HMAC algorithm used by OTP.

type BackupCodeManager 

type BackupCodeManager struct {
	// contains filtered or unexported fields
}

BackupCodeManager generates and verifies recovery codes. Instances are immutable and safe for concurrent use.

func NewBackupCodeManager 

func NewBackupCodeManager(opts ...BackupOption) (*BackupCodeManager, error)

NewBackupCodeManager constructs a backup code manager with safe defaults.

func (*BackupCodeManager) Generate 

func (m *BackupCodeManager) Generate() (BackupCodeSet, error)

Generate produces a set of backup codes and hashes for storage.

func (*BackupCodeManager) Verify 

func (m *BackupCodeManager) Verify(code string, hashes []string) (bool, []string, error)

Verify checks a backup code and returns the remaining hashes if it matched.

type BackupCodeSet 

type BackupCodeSet struct {
	Codes  []string
	Hashes []string
}

BackupCodeSet contains the generated backup codes and their hashes.

type BackupHasher 

type BackupHasher interface {
	Hash(code []byte) (string, error)
	Verify(code []byte, hash string) (bool, error)
}

BackupHasher hashes and verifies backup codes for storage.

type BackupOption 

type BackupOption func(*backupConfig) error

BackupOption configures backup code generation and verification.

func WithBackupCodeAlphabet 

func WithBackupCodeAlphabet(alphabet string) BackupOption

WithBackupCodeAlphabet sets the alphabet used for backup code generation.

func WithBackupCodeCount 

func WithBackupCodeCount(count int) BackupOption

WithBackupCodeCount sets the number of backup codes to generate.

func WithBackupCodeGroupSize 

func WithBackupCodeGroupSize(size int) BackupOption

WithBackupCodeGroupSize sets the grouping size for formatting.

func WithBackupCodeLength 

func WithBackupCodeLength(length int) BackupOption

WithBackupCodeLength sets the length of each backup code.

func WithBackupCodeReader 

func WithBackupCodeReader(reader io.Reader) BackupOption

WithBackupCodeReader sets the randomness source for backup code generation.

func WithBackupHasher 

func WithBackupHasher(hasher BackupHasher) BackupOption

WithBackupHasher sets a custom hasher for backup codes.

func WithBackupHasherArgon2id 

func WithBackupHasherArgon2id(params password.Argon2idParams) BackupOption

WithBackupHasherArgon2id configures Argon2id hashing for backup codes.

func WithBackupHasherBcrypt 

func WithBackupHasherBcrypt(cost int) BackupOption

WithBackupHasherBcrypt configures bcrypt hashing for backup codes.

func WithBackupRateLimiter 

func WithBackupRateLimiter(limiter RateLimiter) BackupOption

WithBackupRateLimiter sets a rate limiter for backup code verification.

type Digits 

type Digits = otp.Digits

Digits defines the number of digits in OTP codes.

type HOTP 

type HOTP struct {
	// contains filtered or unexported fields
}

HOTP generates and verifies counter-based one-time passwords. Instances of HOTP contain immutable configuration and can be used concurrently.

func NewHOTP 

func NewHOTP(secret string, opts ...HOTPOption) (*HOTP, error)

NewHOTP constructs an HOTP helper using the provided base32 secret.

func (*HOTP) Generate 

func (h *HOTP) Generate(counter uint64) (string, error)

Generate returns the HOTP code for the specified counter.

func (*HOTP) Resync 

func (h *HOTP) Resync(code1, code2 string, counter uint64) (bool, uint64, error)

Resync verifies two consecutive HOTP codes to recover a drifting counter. On success, it returns true and the next counter to persist.

func (*HOTP) Verify 

func (h *HOTP) Verify(code string, counter uint64) (bool, uint64, error)

Verify checks whether the supplied HOTP code is valid for the counter window. On success, it returns true and the next counter to persist.

type HOTPKeyOption 

type HOTPKeyOption func(*hotpKeyConfig) error

HOTPKeyOption configures provisioning for a new HOTP key.

func WithHOTPKeyAccountName 

func WithHOTPKeyAccountName(account string) HOTPKeyOption

WithHOTPKeyAccountName sets the account name for provisioning.

func WithHOTPKeyAlgorithm 

func WithHOTPKeyAlgorithm(algorithm Algorithm) HOTPKeyOption

WithHOTPKeyAlgorithm sets the HMAC algorithm for provisioning.

func WithHOTPKeyDigits 

func WithHOTPKeyDigits(digits Digits) HOTPKeyOption

WithHOTPKeyDigits sets the number of digits for provisioning.

func WithHOTPKeyIssuer 

func WithHOTPKeyIssuer(issuer string) HOTPKeyOption

WithHOTPKeyIssuer sets the issuer for provisioning.

func WithHOTPKeySecretSize 

func WithHOTPKeySecretSize(secretSize int) HOTPKeyOption

WithHOTPKeySecretSize sets the secret size in bytes for provisioning.

type HOTPOption 

type HOTPOption func(*hotpConfig) error

HOTPOption configures HOTP verification behavior.

func WithHOTPAlgorithm 

func WithHOTPAlgorithm(algorithm Algorithm) HOTPOption

WithHOTPAlgorithm sets the HMAC algorithm for HOTP codes.

func WithHOTPDigits 

func WithHOTPDigits(digits Digits) HOTPOption

WithHOTPDigits sets the number of digits for HOTP codes.

func WithHOTPRateLimiter 

func WithHOTPRateLimiter(limiter RateLimiter) HOTPOption

WithHOTPRateLimiter sets a rate limiter for HOTP verification.

func WithHOTPResyncWindow 

func WithHOTPResyncWindow(resyncWindow uint) HOTPOption

WithHOTPResyncWindow sets the look-ahead window used for resync.

func WithHOTPSecretMinBytes 

func WithHOTPSecretMinBytes(minBytes int) HOTPOption

WithHOTPSecretMinBytes sets the minimum secret length in bytes.

func WithHOTPWindow 

func WithHOTPWindow(lookAhead uint) HOTPOption

WithHOTPWindow sets the look-ahead counter window.

type RateLimiter 

type RateLimiter interface {
	Allow() (bool, error)
}

RateLimiter enforces rate limiting for MFA verification attempts.

type TOTP 

type TOTP struct {
	// contains filtered or unexported fields
}

TOTP generates and verifies time-based one-time passwords. Instances of TOTP contain immutable configuration and can be used concurrently.

func NewTOTP 

func NewTOTP(secret string, opts ...TOTPOption) (*TOTP, error)

NewTOTP constructs a TOTP helper using the provided base32 secret.

func (*TOTP) Generate 

func (t *TOTP) Generate() (string, error)

Generate returns the current TOTP code using the configured clock.

func (*TOTP) Verify 

func (t *TOTP) Verify(code string) (bool, error)

Verify checks whether the supplied TOTP code is valid for the current time.

func (*TOTP) VerifyWithStep 

func (t *TOTP) VerifyWithStep(code string) (bool, uint64, error)

VerifyWithStep checks a TOTP code and returns the matched time step. Use the returned step to prevent replays by rejecting codes <= the last accepted step.

type TOTPKeyOption 

type TOTPKeyOption func(*totpKeyConfig) error

TOTPKeyOption configures provisioning for a new TOTP key.

func WithTOTPKeyAccountName 

func WithTOTPKeyAccountName(account string) TOTPKeyOption

WithTOTPKeyAccountName sets the account name for provisioning.

func WithTOTPKeyAlgorithm 

func WithTOTPKeyAlgorithm(algorithm Algorithm) TOTPKeyOption

WithTOTPKeyAlgorithm sets the HMAC algorithm for provisioning.

func WithTOTPKeyDigits 

func WithTOTPKeyDigits(digits Digits) TOTPKeyOption

WithTOTPKeyDigits sets the number of digits for provisioning.

func WithTOTPKeyIssuer 

func WithTOTPKeyIssuer(issuer string) TOTPKeyOption

WithTOTPKeyIssuer sets the issuer for provisioning.

func WithTOTPKeyPeriod 

func WithTOTPKeyPeriod(period time.Duration) TOTPKeyOption

WithTOTPKeyPeriod sets the period for provisioning.

func WithTOTPKeySecretSize 

func WithTOTPKeySecretSize(secretSize int) TOTPKeyOption

WithTOTPKeySecretSize sets the secret size in bytes for provisioning.

type TOTPOption 

type TOTPOption func(*totpConfig) error

TOTPOption configures TOTP verification behavior.

func WithTOTPAlgorithm 

func WithTOTPAlgorithm(algorithm Algorithm) TOTPOption

WithTOTPAlgorithm sets the HMAC algorithm for TOTP codes.

func WithTOTPAllowedSkew 

func WithTOTPAllowedSkew(skew uint) TOTPOption

WithTOTPAllowedSkew sets the number of adjacent time steps allowed.

func WithTOTPClock 

func WithTOTPClock(clock func() time.Time) TOTPOption

WithTOTPClock sets the clock used for code generation and verification.

func WithTOTPDigits 

func WithTOTPDigits(digits Digits) TOTPOption

WithTOTPDigits sets the number of digits for TOTP codes.

func WithTOTPPeriod 

func WithTOTPPeriod(period time.Duration) TOTPOption

WithTOTPPeriod sets the TOTP period.

func WithTOTPRateLimiter 

func WithTOTPRateLimiter(limiter RateLimiter) TOTPOption

WithTOTPRateLimiter sets a rate limiter for TOTP verification.

func WithTOTPSecretMinBytes 

func WithTOTPSecretMinBytes(minBytes int) TOTPOption

WithTOTPSecretMinBytes sets the minimum secret length in bytes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.