otp

otp

A Go library for generating and validating One-Time Passwords (OTPs), implementing HOTP (RFC 4226) and TOTP (RFC 6238).

Features

• HOTP — Counter-based OTP (RFC 4226)
• TOTP — Time-based OTP (RFC 6238)
• 10 hash algorithms — SHA1, SHA224, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512, MD5
• Steam Guard encoder support
• Secret management — Generate, import (Base32/Hex/Bytes), and securely clear secrets
• QR code generation — For authenticator app enrollment
• Replay protection — Prevent re-use of previously accepted OTPs
• Unicode NFKC normalization — Fullwidth digit support for international users
• RFC-compliant defaults — SHA1/6-digit/30s for Google Authenticator compatibility
• Security guardrails — HTTPS-only image URLs, parameter injection prevention, window/digit/period limits

Install

go get github.com/unitsvc/otp

Quick Start

TOTP — Generate and Validate

package main

import (
    "fmt"
    "time"

    "github.com/unitsvc/otp/totp"
)

func main() {
    // Generate a new TOTP key
    key, err := totp.Generate(totp.GenerateOpts{
        Issuer:      "Example",
        AccountName: "user@example.com",
    })
    if err != nil {
        panic(err)
    }

    // Display the secret and QR code
    fmt.Println("Secret:", key.Secret())

    // Validate a passcode
    passcode := "123456" // user-provided
    valid := totp.Validate(passcode, key.Secret())
    fmt.Println("Valid:", valid)
}

HOTP — Counter-based

key, _ := hotp.Generate(hotp.GenerateOpts{
    Issuer:      "Example",
    AccountName: "user@example.com",
})

code, _ := hotp.GenerateCode(key.Secret(), 0)
valid := hotp.Validate(code, 0, key.Secret())

Secret Management

// Generate a random 20-byte secret
sec, _ := secret.New(20)
fmt.Println(sec.Base32())  // JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

// Import from Base32
sec, _ = secret.FromBase32("JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP")

// Securely clear when done
sec.Clear()

API Reference

Core Types (otp package)

algo, _ := otp.ParseAlgorithm("SHA256")     // parse from string (accepts aliases: SHA-256, SHA2-256, SSL3-SHA1)
key, _ := otp.NewKeyFromURL("otpauth://...")  // parse otpauth URI
h, _ := algo.HashChecked()                    // safe hash accessor (errors on unknown algorithms)
key.GetExtraParam("source")                   // read custom URI parameter → "web"

TOTP (totp package)

// Custom algorithm and digits
code, _ := totp.GenerateCodeCustom(secret, time.Now(), totp.ValidateOpts{
    Period:    60,
    Digits:    otp.DigitsEight,
    Algorithm: otp.AlgorithmSHA512,
})

// Replay protection — reject codes from steps already used
valid, step, _ := totp.ValidateCustomStep(code, secret, time.Now(), totp.ValidateOpts{
    Period:    30,
    AfterStep: lastUsedStep, // zero-value = disabled
})

// Structured result with clock drift detection
result, _ := totp.ValidateCustomResult(code, secret, time.Now(), opts)
fmt.Println(result.Delta) // 0=exact, -1=past, +1=future

HOTP (hotp package)

// Window validation with replay protection
delta, found, _ := hotp.ValidateCustomWindow(code, expectedCounter, secret,
    hotp.ValidateOptsWithWindow{
        Window:       2,
        AfterCounter: lastUsedCounter, // reject counters <= this value
    })

Secret (secret package)

Secret methods: Bytes(), Base32(), Base32WithPadding(), Hex(), Len(), Clear()

Advanced Usage

QR Code Enrollment

key, _ := totp.Generate(totp.GenerateOpts{
    Issuer:      "MyApp",
    AccountName: "alice@example.com",
    ImageURL:    "https://myapp.com/logo.png", // HTTPS required
})

// Generate 200x200 QR code image
img, _ := key.Image(200, 200)

Steam Guard

code, _ := totp.GenerateCodeCustom(secret, time.Now(), totp.ValidateOpts{
    Digits: 5,
    Encoder: otp.EncoderSteam,
})

Unicode NFKC Normalization

// Accepts fullwidth digits: ＡＢＣ１２３ → ABC123
valid, _ := hotp.ValidateCustomNormalized(passcode, counter, secret, opts)

URI Generation with Custom Parameters

key, _ := totp.Generate(totp.GenerateOpts{
    Issuer:      "MyApp",
    AccountName: "user@example.com",
    Algorithm:   otp.AlgorithmSHA256,
    Digits:      otp.DigitsEight,
    Period:      60,
    SecretSize:  32,
    ExtraParams: map[string]string{"source": "web"}, // custom URI parameters
})
// URI omits default params (SHA1, 6 digits, 30s) for compact QR codes
fmt.Println(key.URL())
// otpauth://totp/MyApp:user@example.com?algorithm=SHA256&digits=8&period=60&source=web&...

// Read custom params back from a parsed key
key.GetExtraParam("source") // → "web"

SkewPolicy — Asymmetric Time Window

// RFC 6238 recommended: allow 1 past period only (no future)
valid, step, delta, _ := totp.ValidateCustomSkewPolicy(code, secret, time.Now(),
    totp.ValidateOptsWithSkewPolicy{
        SkewPolicy: totp.SkewPolicy{Past: 1, Future: 0},
    })

Google Authenticator Compatibility

// Append trailing & to work around Google Authenticator parsing bug
// See: https://github.com/pquerna/otp/issues/94
key, _ := totp.Generate(totp.GenerateOpts{
    Issuer:                    "MyApp",
    AccountName:               "user@example.com",
    GoogleAuthenticatorCompat: true,
})

T0 Epoch Offset

// Custom epoch for time-step calculation (default T0=0 = Unix epoch)
step := totp.CounterWithT0(30, 1700000000, time.Now())
remaining := totp.RemainingWithT0(30, 1700000000, time.Now())

IssuerInLabelOmit

// Omit issuer from URI label path (only in query parameter)
key, _ := totp.Generate(totp.GenerateOpts{
    Issuer:            "MyApp",
    AccountName:       "user@example.com",
    IssuerInLabelOmit: true,
})
// otpauth://totp/user@example.com?issuer=MyApp&secret=...

Algorithm Support

Aliases: ParseAlgorithm accepts "SHA-256", "SHA2-256", "SSL3-SHA1" etc.

Examples

See the example/ directory for complete working programs:

• example/main.go — Basic TOTP enrollment with QR code
• example/totp/ — TOTP features (algorithms, SkewPolicy, Steam, replay, ExtraParams, GoogleAuthenticatorCompat)
• example/hotp/ — HOTP features (counter, window, replay protection, ExtraParams, GoogleAuthenticatorCompat)
• example/otp/ — Core types (algorithms, URI parsing, HashChecked, GetExtraParam, ValidationResult)
• example/secret/ — Secret management (generate, import, clear)

Security Considerations

• Secrets are validated to be 16–64 bytes per RFC 4226 Section 4
• Image URLs must be HTTPS — HTTP, javascript:, and file:// are rejected
• Parameter injection is prevented — & and = in values are percent-encoded
• Window/digit/period limits — Prevent misconfiguration (e.g., window > 10)
• Replay protection — AfterCounter/AfterStep prevent OTP re-use
• Secret.Clear() — Zeros the internal buffer when no longer needed
• Secret.Bytes() — Returns a copy; mutating does not affect the original
• MD5 is rejected — 16-byte digest is too small for the dynamic truncation algorithm

Compatibility

Compatible with all major authenticator apps:

• Google Authenticator
• Microsoft Authenticator
• Authy
• FreeOTP
• andOTP / Aegis
• 1Password

License

Licensed under the Apache License, Version 2.0.