totp

Documentation

Index

• Constants
• func CompareBackupCode(code, hash string) bool
• func ConstantTimeCompare(a, b string) bool
• func GenerateCode(secret string, t time.Time) (string, error)
• func GeneratePendingToken(userID string, secret []byte) string
• func GenerateSecret() (string, error)
• func HashBackupCode(code string) (string, error)
• func OTPAuthURI(secret, account, issuer string) string
• func Validate(code string, secret string) (bool, error)
• func ValidateBackupCode(inputCode string, codes []BackupCode) int
• func ValidateBackupCodeSimple(inputCode string, codeHashes []string, usedFlags []bool) (bool, int)
• func ValidatePendingToken(token string, secret []byte) (string, error)
• type BackupCode
• type BackupCodes
  • func GenerateBackupCodes(count int) (*BackupCodes, error)
  • func (bc *BackupCodes) GetCodeHashes() []string
  • func (bc *BackupCodes) GetPlaintextCodes() []string
  • func (bc *BackupCodes) GetRemainingCount() int

Constants

const (
	// DefaultBackupCodeCount is the default number of backup codes to generate
	DefaultBackupCodeCount = 10

	// BackupCodeLength is the length of each backup code (before formatting)
	BackupCodeLength = 8
)

const (
	// DefaultDigits is the number of digits in a TOTP code
	DefaultDigits = 6
	// DefaultPeriod is the time step in seconds
	DefaultPeriod = 30
	// DefaultSecretSize is the size of the TOTP secret in bytes (160 bits)
	DefaultSecretSize = 20
	// DefaultIssuer is the default issuer name for otpauth URIs
	DefaultIssuer = "usulnet"
	// DefaultSkew allows codes from adjacent time periods (1 = ±30s)
	DefaultSkew = 1
)

const (
	// PendingTokenTTL is how long a TOTP pending token is valid.
	PendingTokenTTL = 5 * time.Minute
)

Functions

func CompareBackupCode

func CompareBackupCode(code, hash string) bool

CompareBackupCode compares a plaintext backup code with a hash

func ConstantTimeCompare

func ConstantTimeCompare(a, b string) bool

ConstantTimeCompare performs constant-time comparison of two strings

func GenerateCode

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

GenerateCode generates a TOTP code for the given secret at the current time.

func GeneratePendingToken

func GeneratePendingToken(userID string, secret []byte) string

GeneratePendingToken creates a signed short-lived token for the TOTP verification step. It contains the user ID and an expiration timestamp, signed with HMAC-SHA256.

func GenerateSecret

func GenerateSecret() (string, error)

GenerateSecret creates a new random TOTP secret encoded as base32.

func HashBackupCode

func HashBackupCode(code string) (string, error)

HashBackupCode creates a bcrypt hash of a backup code

func OTPAuthURI

func OTPAuthURI(secret, account, issuer string) string

OTPAuthURI generates an otpauth:// URI for QR code generation. Format: otpauth://totp/{issuer}:{account}?secret={secret}&issuer={issuer}&algorithm=SHA1&digits=6&period=30

func Validate

func Validate(code string, secret string) (bool, error)

Validate checks if a TOTP code is valid for the given secret. It checks the current time period and ±DefaultSkew adjacent periods.

func ValidateBackupCode

func ValidateBackupCode(inputCode string, codes []BackupCode) int

ValidateBackupCode checks if a backup code is valid and marks it as used Returns the index of the used code, or -1 if not found

func ValidateBackupCodeSimple

func ValidateBackupCodeSimple(inputCode string, codeHashes []string, usedFlags []bool) (bool, int)

ValidateBackupCodeSimple checks if a backup code matches any unused code hash Uses constant-time comparison to prevent timing attacks Returns true if valid, false otherwise

func ValidatePendingToken

func ValidatePendingToken(token string, secret []byte) (string, error)

ValidatePendingToken verifies a TOTP pending token and returns the user ID if valid.

Types

type BackupCode

type BackupCode struct {
	Code     string `json:"code"`      // The plaintext code (only shown once)
	CodeHash string `json:"code_hash"` // Bcrypt hash for storage
	Used     bool   `json:"used"`      // Whether the code has been used
}

BackupCode represents a single backup code

type BackupCodes

type BackupCodes struct {
	Codes     []BackupCode `json:"codes"`
	CreatedAt int64        `json:"created_at"` // Unix timestamp
}

BackupCodes represents a set of backup codes

func GenerateBackupCodes

func GenerateBackupCodes(count int) (*BackupCodes, error)

GenerateBackupCodes creates a new set of backup codes

func (*BackupCodes) GetCodeHashes

func (bc *BackupCodes) GetCodeHashes() []string

GetCodeHashes returns just the hashed codes (for storage)

func (*BackupCodes) GetPlaintextCodes

func (bc *BackupCodes) GetPlaintextCodes() []string

GetPlaintextCodes returns just the plaintext codes (for showing to user)

func (*BackupCodes) GetRemainingCount

func (bc *BackupCodes) GetRemainingCount() int

GetRemainingCount returns the number of unused backup codes