age-otp

Generate time-based OTP codes from age public keys – no shared secret required.

Overview

age-otp derives deterministic one‑time passwords solely from an age public key (format age1...).
Unlike standard TOTP (RFC 6238), there is no shared secret – the verifier only needs the user’s public key.

age1ysxuae... ──Bech32 decode──► [32‑byte X25519 key]
                                      │
                                      ▼
                              HKDF‑SHA256 ("age-otp-v1")
                                      │
                                      ▼
                              [32‑byte seed]
                                      │
                                      ▼
                              HMAC‑SHA256(time_step)
                                      │
                                      ▼
                              Dynamic truncation
                                      │
                                      ▼
                                  "123456"

Why this matters

Installation

[dependencies]
age-otp = "0.2"

Quick Start

use age_otp::prelude::*;

fn main() -> Result<()> {
    // 1. Create a keypair (or load an existing one)
    let keypair = build_keypair()?;
    let public_key = &keypair.public;

    // 2. Build the OTP engine from the public key
    let engine = OtpEngine::from_public_key(public_key)?;

    // 3. Generate a 6‑digit numeric code for the current 30‑second window
    let now = now_ts();
    let step = now / 30;
    let code = engine.generate(6, step, 30, Charset::Numeric)?;
    println!("Your OTP: {}", code); // e.g. 847291

    // 4. Verify a user‑supplied code (with ±1 step clock skew)
    let user_input = "847291";
    let result = engine.verify_with_skew(
        user_input, 6, step, 30, 30, Charset::Numeric, 1,
    )?;
    assert!(result.is_ok());

    Ok(())
}

API Reference

Public re‑exports

The crate root (age_otp) re‑exports the most important items:

use age_otp::{
    // Key management (from age‑setup)
    PublicKey, build_keypair,
    // Core engine
    OtpEngine,
    // Data types
    OtpSeed, OtpCode, Charset,
    // Utility functions
    now_ts, compute_hmac, truncate, ct_eq,
    // Constants
    SEED_LEN, MIN_CODE_LEN, MAX_CODE_LEN,
    MIN_STEP_SECS, MAX_STEP_SECS, MAX_SKEW_STEPS,
    // Error types
    Error, KeyError, GenerationError, VerificationError, Result,
};
// Convenience prelude
use age_otp::prelude::*;

OtpEngine

The main entry point.

Construction

Generation

Verification

OtpSeed

A 32‑byte seed derived from a public key.

let pk: PublicKey = "age1...".parse()?;
let seed = OtpSeed::from_public_key(&pk)?;

seed.as_bytes();           // &[u8; 32]
seed.to_hex();             // 64‑character hex string (for debugging)

let seed2 = OtpSeed::from_bytes([0u8; 32]);   // create from raw bytes

Debug safety – Debug only prints the first 8 hex characters.

OtpCode

An OTP code together with its birth timestamp.

let code = OtpCode::new("123456".into(), time_step, step_secs)?;

code.as_str();              // "123456"
code.len();                 // 6
code.born_at();             // time_step * step_secs (UNIX seconds)

code.is_valid_at(current_ts, ttl); // true if current_ts is within [born, born+ttl)

Debug safety – Debug masks the code (e.g. 12***), Display shows the full code.

Charset

Supported character sets for OTP codes.

let cs = Charset::Numeric;
assert_eq!(cs.len(), 10);
assert!(cs.validate("123456"));
assert!(!cs.validate("abc")); // wrong charset

Constants

use age_otp::{SEED_LEN, MIN_CODE_LEN, MAX_CODE_LEN, MIN_STEP_SECS, MAX_STEP_SECS, MAX_SKEW_STEPS};
// SEED_LEN = 32
// MIN_CODE_LEN = 4, MAX_CODE_LEN = 64
// MIN_STEP_SECS = 1, MAX_STEP_SECS = 3600
// MAX_SKEW_STEPS = 10

Utility functions

These are re‑exported at the crate root, but are also available under age_otp::types.

Error handling

All fallible operations return Result<T, Error>.
Error is an enum:

pub enum Error {
    Key(KeyError),                // invalid public key
    Generation(GenerationError),  // HMAC failure, invalid parameters, overflow
    Verification(VerificationError), // mismatch, expired, invalid format
}

Sub‑errors:

• KeyError – Empty, InvalidPrefix, Bech32Decode, InvalidDecodedLength
• GenerationError – HmacFailed, TruncateFailed, InvalidLength, Overflow
• VerificationError – Mismatch, Expired { expired_at, current }, InvalidFormat

Example:

match engine.verify_raw("123456", 6, step, 30, 30, Charset::Numeric) {
    Ok(()) => println!("✓"),
    Err(Error::Verification(VerificationError::Mismatch)) => println!("✗ Wrong code"),
    Err(Error::Verification(VerificationError::Expired { .. })) => println!("⏰ Expired"),
    Err(e) => eprintln!("Error: {}", e),
}

Security

✅ What this library provides

• No shared secrets – OTP codes are derived from the public key only.
• Proper key derivation – The age public key is Bech32‑decoded first, then fed into HKDF‑SHA256. The original Bech32 string is never used as the HMAC key directly.
• Constant‑time comparison – All code comparisons use the subtle crate to prevent timing attacks.
• Overflow safety – All arithmetic uses checked operations (checked_mul, saturating_add).
• Bounded parameters – Code length, step seconds, and skew steps have hard limits to prevent abuse.
• Debug protection – OtpSeed shows only a short hex prefix; OtpCode masks the code.
• Zeroization – Secret keys (via age‑setup) are zeroized on drop.

⚠️ Deployment checklist

• Use HTTPS – OTP codes must be transmitted over encrypted channels.
• Short TTL – 30–60 seconds is recommended.
• Rate limiting – Throttle verification attempts to prevent brute force (library does not implement rate limiting).
• Store the seed securely – If you cache OtpSeed, treat it as sensitive (it can generate valid codes).
• Do not log full OTP codes – Use the Debug representation (masked) for logging.

🚫 Known limitations

• Not TOTP compatible – Does not follow RFC 6238; cannot be used with standard authenticator apps.
• No replay protection – A code remains valid for the entire TTL window. The application must enforce one‑time use if desired.
• Single charset per code – Characters cannot be mixed.

Architecture

src/
├── lib.rs          # Crate root, re‑exports
├── engine.rs       # OtpEngine (generation & verification)
├── types.rs        # OtpSeed, OtpCode, Charset, constants, utility functions
└── error.rs        # Error and Result types

Dependencies

Examples

More runnable examples are in the examples/ directory.
Run them with:

cargo run --example main

Testing

cargo test                  # run all unit & integration tests
cargo test --lib            # run only unit tests (inside src/)
cargo test --test engine_tests  # run integration tests only

License

Licensed under either of

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

References

• age encryption spec
• RFC 5869 – HKDF
• BIP‑173 – Bech32
• subtle crate – constant‑time operations