totpyx

A tiny, dependency-free TOTP generator (RFC 6238) with a strict RFC 4648 Base32 decoder.

This project exists for a single purpose: to provide a fully auditable TOTP implementation with no third-party crypto dependencies, no hidden behavior, and a deliberately minimal attack and trust surface.

What it is

TOTP (RFC 6238) generator
HMAC algorithms: SHA-1, SHA-256, SHA-512
Digits: 6, 7, or 8
Period (X): configurable (default 30 seconds)
T0: configurable (default 0)
Time override: supply an explicit Unix timestamp to reproduce test vectors or debug clock drift
Base32 decoding: RFC 4648 alphabet (A–Z2–7), case-insensitive, optional = padding

What it is not

Not a password manager
Not a QR or provisioning URI parser
Not secret storage
Not a general-purpose cryptography library
Not a formally audited security product

This crate computes TOTP codes. Secret storage, lifecycle, and protection are intentionally left to the caller.

Install

As a CLI:

cargo install totpyx

As a library:

cargo add totpyx

CLI usage

totpyx <base32-secret> \
  [--algo sha1|sha256|sha512] \
  [--digits 6|7|8] \
  [--period <seconds>] \
  [--t0 <unix>] \
  [--time <unix>]

Examples

Generate a standard 6-digit TOTP (SHA-1, 30s period, T0=0):

totpyx JBSWY3DPEHPK3PXP

Generate SHA-256 with 8 digits:

totpyx JBSWY3DPEHPK3PXP --algo sha256 --digits 8

Generate with a custom period:

totpyx JBSWY3DPEHPK3PXP --period 60

Reproduce a code for a specific Unix timestamp (debugging drift, server-side validation):

totpyx JBSWY3DPEHPK3PXP --time 1710000000

Notes on secrets

If your issuer provides a Base32 secret with spaces or hyphens, remove them first.
Padding = at the end is allowed but not required.
Invalid lengths or padding are rejected intentionally.

Library usage

Minimal example:

use totpyx::crypto::HashAlgo;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let secret = totpyx::base32::decode("JBSWY3DPEHPK3PXP")?;

    let unix_time = 1_710_000_000u64;

    let code = totpyx::totp::generate_totp(
        &secret,
        unix_time,
        30,        // period (X)
        0,         // T0
        6,         // digits
        HashAlgo::Sha1,
    )?;

    println!("{code}");
    Ok(())
}

Spec compliance

TOTP is computed as HOTP(K, T) where T = (unix_time - T0) / X (RFC 6238 §4).
Dynamic truncation follows the HOTP truncation method, including MSB masking to avoid signed/unsigned ambiguity (RFC 4226 §5.3).
Output digits are restricted to 6, 7, or 8 (RFC 4226 §5.4).
HMAC modes SHA-1, SHA-256, and SHA-512 are implemented and validated against the RFC 6238 Appendix B test vectors.
Base32 decoding follows RFC 4648 strictly, including alphabet, padding rules, and invalid length handling.

References

This create implements the relevant standards directly, without abstraction or reinterpretation. The primary references are:

RFC 6238 — Time-Based One-Time Password Algorithm (TOTP) https://www.rfc-editor.org/rfc/rfc6238
RFC 4226 — HMAC-Based One-Time Password Algorithm (HOTP) https://www.rfc-editor.org/rfc/rfc4226
RFC 2104 — HMAC: Keyed-Hashing for Message Authentication https://www.rfc-editor.org/rfc/rfc2104
FIPS 180-4 — Secure Hash Standard (SHS) https://csrc.nist.gov/publications/detail/fips/180/4/final
RFC 4648 — The Base16, Base32, and Base64 Data Encodings https://www.rfc-editor.org/rfc/rfc4648

All test vectors included in this repository are taken directly from the referenced specifications.

totpyx 1.0.0