otp

Documentation

Overview

Package otp provides implementations for generating and validating One-Time Passwords.

Index

• Variables
• type Algorithm
  • func (a Algorithm) Hash() hash.Hash
  • func (a Algorithm) String() string
• type Digits
  • func (d Digits) Format(in int32) string
  • func (d Digits) Length() int
  • func (d Digits) String() string
• type Encoder
• type Key
  • func NewKeyFromURL(orig string) (*Key, error)
  • func (k *Key) AccountName() string
  • func (k *Key) Algorithm() Algorithm
  • func (k *Key) Digits() Digits
  • func (k *Key) Encoder() Encoder
  • func (k *Key) Image(width, height int, color ...color.Color) (image.Image, error)
  • func (k *Key) Issuer() string
  • func (k *Key) Period() uint64
  • func (k *Key) Secret() string
  • func (k *Key) String() string
  • func (k *Key) Type() string
  • func (k *Key) URL() string
• type Option
  • func WithAccountName(name string) Option
  • func WithAlgorithm(alg Algorithm) Option
  • func WithDigits(digits Digits) Option
  • func WithIssuer(issuer string) Option
  • func WithPeriod(period uint) Option
  • func WithSecretSize(secretSize uint) Option
  • func WithSkew(skew uint) Option
  • func WithTime(t time.Time) Option
• type Options
  • func Apply(opts ...Option) *Options

Variables

var (
	// ErrValidateSecretInvalidBase32 is returned when the secret cannot be decoded from base32.
	ErrValidateSecretInvalidBase32 = errors.New("Decoding of secret as base32 failed.")
	// ErrValidateInputInvalidLength is returned when the provided OTP input has an unexpected length.
	ErrValidateInputInvalidLength = errors.New("Input length unexpected")
	// ErrGenerateMissingIssuer is returned when attempting to generate a key without an issuer.
	ErrGenerateMissingIssuer = errors.New("Issuer must be set")
	// ErrGenerateMissingAccountName is returned when attempting to generate a key without an account name.
	ErrGenerateMissingAccountName = errors.New("AccountName must be set")
)

Standard errors for OTP validation and generation.

Types

type Algorithm

type Algorithm int

Algorithm represents the hashing algorithm used for the OTP.

const (
	// AlgorithmSHA1 uses the SHA1 hashing algorithm.
	AlgorithmSHA1 Algorithm = iota
	// AlgorithmSHA256 uses the SHA256 hashing algorithm.
	AlgorithmSHA256
	// AlgorithmSHA512 uses the SHA512 hashing algorithm.
	AlgorithmSHA512
	// AlgorithmMD5 uses the MD5 hashing algorithm.
	AlgorithmMD5
)

func (Algorithm) Hash

func (a Algorithm) Hash() hash.Hash

Hash returns a new hash.Hash instance for the specified Algorithm.

func (Algorithm) String

func (a Algorithm) String() string

String returns the string representation of the hashing Algorithm.

type Digits

type Digits int

Digits represents the number of digits in a generated OTP.

const (
	// Six represents a 6-digit OTP.
	Six Digits = 6
	// Eight represents an 8-digit OTP.
	Eight Digits = 8
)

func (Digits) Format

func (d Digits) Format(in int32) string

Format formats the given integer as a string with the specified number of digits, padding with leading zeros if necessary.

func (Digits) Length

func (d Digits) Length() int

Length returns the integer value of the Digits.

func (Digits) String

func (d Digits) String() string

String returns the string representation of the Digits.

type Encoder

type Encoder string

Encoder represents the encoding type for the OTP.

const (
	// EncoderDefault is the standard OTP encoder.
	EncoderDefault Encoder = "default:encoder"

	// EncoderSteam is the encoder used for Steam Guard OTPs.
	EncoderSteam Encoder = "steam:encoder"
)

type Key

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

Key represents an OTP key derived from an otpauth:// URI.

func NewKeyFromURL

func NewKeyFromURL(orig string) (*Key, error)

NewKeyFromURL parses an otpauth:// URI string and returns a new Key instance. It returns an error if the URI string cannot be parsed.

func (*Key) AccountName

func (k *Key) AccountName() string

AccountName returns the account name associated with the OTP, extracting it from the path.

func (*Key) Algorithm

func (k *Key) Algorithm() Algorithm

Algorithm returns the hashing algorithm for the OTP. It defaults to AlgorithmSHA1 if the algorithm parameter is unrecognized or not set.

func (*Key) Digits

func (k *Key) Digits() Digits

Digits returns the number of digits for the OTP. It defaults to Six (6) if the digits parameter is not specified or cannot be parsed.

func (*Key) Encoder

func (k *Key) Encoder() Encoder

Encoder returns the encoder type for the OTP. It defaults to EncoderDefault if the encoder parameter is unrecognized or not set.

func (*Key) Image

func (k *Key) Image(
	width,
	height int,
	color ...color.Color,
) (image.Image, error)

Image generates a QR code image for the Key with the specified width and height. It returns an error if the QR code encoding fails.

func (*Key) Issuer

func (k *Key) Issuer() string

Issuer returns the issuer of the OTP. It first attempts to extract it from the query parameters, falling back to the path prefix if not found.

func (*Key) Period

func (k *Key) Period() uint64

Period returns the validity period of the OTP in seconds. It defaults to 30 if the period is not specified or cannot be parsed.

func (*Key) Secret

func (k *Key) Secret() string

Secret returns the base32-encoded secret of the OTP from the query parameters.

func (*Key) String

func (k *Key) String() string

String returns the original URI string used to create the Key.

func (*Key) Type

func (k *Key) Type() string

Type returns the type of the OTP (e.g., "totp" or "hotp") extracted from the URI host.

func (*Key) URL

func (k *Key) URL() string

URL returns the normalized string representation of the parsed URL.

type Option

type Option func(*Options)

Option is a function that applies a configuration value to Options.

func WithAccountName

func WithAccountName(name string) Option

WithAccountName sets the account name for the OTP.

func WithAlgorithm

func WithAlgorithm(alg Algorithm) Option

WithAlgorithm sets the hashing algorithm used for the OTP.

func WithDigits

func WithDigits(digits Digits) Option

WithDigits sets the number of digits for the generated OTP.

func WithIssuer

func WithIssuer(issuer string) Option

WithIssuer sets the issuer of the OTP.

func WithPeriod

func WithPeriod(period uint) Option

WithPeriod sets the validity period of the OTP in seconds.

func WithSecretSize

func WithSecretSize(secretSize uint) Option

WithSecretSize sets the byte size of the generated secret.

func WithSkew

func WithSkew(skew uint) Option

WithSkew sets the acceptable time skew window for OTP validation.

func WithTime

func WithTime(t time.Time) Option

WithTime sets the time used for OTP generation or validation.

type Options

type Options struct {
	// Issuer is the name of the organization or service issuing the OTP (e.g., "Google", "GitHub").
	// This is typically displayed in the authenticator app to identify the source of the code.
	Issuer string

	// AccountName is the name used to identify the specific account (e.g., "user@example.com").
	// In most apps, this is displayed alongside the Issuer to distinguish between multiple accounts.
	AccountName string

	// Period is the amount of time in seconds that a TOTP (Time-based One-Time Password)
	// is valid for. The default is typically 30 seconds.
	Period uint

	// Skew is the number of time steps (periods) allowed before and after the current time
	// during validation. A skew of 1 allows the previous, current, and next OTP to be valid,
	// accounting for clock drift between the server and the client's device.
	Skew uint

	// SecretSize is the length in bytes of the secret key to be generated if a
	// custom Secret is not provided. The default is usually 20 bytes.
	SecretSize uint

	// Secret is the raw byte array of the shared secret key. If this is provided,
	// SecretSize is ignored. This key must be kept secure.
	Secret []byte

	// Digits represents the length of the generated OTP code, usually Six (6) or Eight (8).
	Digits Digits

	// Algorithm is the hashing function used to generate the HMAC (e.g., SHA1, SHA256).
	// SHA1 is the most common default for compatibility with most authenticator apps.
	Algorithm Algorithm

	// Encoder specifies the formatting logic for the resulting code.
	// Use EncoderDefault for standard numeric codes or EncoderSteam for Steam-specific formats.
	Encoder Encoder

	// Time is the reference point used for TOTP calculation.
	// In production, this should always be set to the current UTC time.
	Time time.Time

	// Rand is the source of entropy used to generate a new Secret.
	// It defaults to crypto/rand.Reader for secure, cryptographically strong randomness.
	Rand io.Reader
}

Options holds configuration settings for generating and validating OTPs.

func Apply

func Apply(opts ...Option) *Options

Apply creates an Options struct with default values and applies the provided functional options.