Vaultx.Secrets.TOTP (Vaultx v0.7.0)

View Source

Unified TOTP secrets engine interface for HashiCorp Vault.

This module provides a comprehensive, enterprise-grade interface for the TOTP (Time-based One-Time Password) secrets engine, offering dynamic TOTP key management, code generation, and validation capabilities.

Enterprise TOTP Management

  • Dynamic Key Generation: Vault-generated TOTP keys with QR codes
  • Key Import: Import existing TOTP keys from external sources
  • Code Generation: Time-based one-time password generation
  • Code Validation: Secure TOTP code validation with skew tolerance
  • Multi-Algorithm Support: SHA1, SHA256, SHA512 algorithms
  • Flexible Configuration: Customizable periods, digits, and parameters

Supported TOTP Features

Key Management

  • Vault-Generated Keys: Automatic key generation with QR codes
  • Imported Keys: Support for existing TOTP URLs and raw keys
  • Multiple Algorithms: SHA1 (default), SHA256, SHA512
  • Configurable Digits: 6 or 8 digit codes
  • Custom Periods: Configurable time periods (default 30 seconds)

Security Features

  • Time Skew Tolerance: Configurable skew for clock drift
  • QR Code Generation: Base64-encoded PNG QR codes
  • URL Export: Standard otpauth:// URL format
  • Secure Storage: Encrypted key storage in Vault

Configuration Examples

# Generate a new TOTP key with QR code
config = %{
  generate: true,
  exported: true,
  issuer: "MyApp",
  account_name: "user@example.com",
  algorithm: "SHA256",
  digits: 6,
  period: 30,
  qr_size: 200
}
{:ok, response} = TOTP.create_key("user-key", config)

# Import an existing TOTP key
config = %{
  url: "otpauth://totp/Google:test@gmail.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Google"
}
{:ok, _} = TOTP.create_key("imported-key", config)

# Generate and validate codes
{:ok, code} = TOTP.generate_code("user-key")
{:ok, result} = TOTP.validate_code("user-key", code.code)

API Compliance

Fully implements HashiCorp Vault TOTP secrets engine:

Summary

Functions

create_key(name, config, opts \\ [])

Create or update a TOTP key.

delete_key(name, opts \\ [])

Delete a TOTP key.

generate_code(name, opts \\ [])

Generate a TOTP code for a key.

list_keys(opts \\ [])

List all configured TOTP keys.

read_key(name, opts \\ [])

Read a TOTP key configuration.

validate_code(name, code, opts \\ [])

Validate a TOTP code against a key.

Functions

create_key(name, config, opts \\ [])

Create or update a TOTP key.

Creates a new TOTP key definition that can be used to generate time-based one-time passwords. Supports both Vault-generated keys and imported keys from external sources.

Parameters

  • name - Key name
  • config - Key configuration
  • opts - Request options including mount path

Examples

# Generate a new key with QR code
config = %{
  generate: true,
  exported: true,
  issuer: "MyApp",
  account_name: "user@example.com",
  algorithm: "SHA256",
  digits: 6,
  period: 30,
  qr_size: 200
}
{:ok, response} = TOTP.create_key("user-key", config)

# Import existing key from URL
config = %{
  url: "otpauth://totp/Google:test@gmail.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Google"
}
{:ok, _} = TOTP.create_key("imported-key", config)

# Import raw key
config = %{
  key: "Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G",
  issuer: "MyApp",
  account_name: "user@example.com"
}
{:ok, _} = TOTP.create_key("raw-key", config)

delete_key(name, opts \\ [])

Delete a TOTP key.

Examples

:ok = TOTP.delete_key("old-key")

generate_code(name, opts \\ [])

Generate a TOTP code for a key.

Generates a new time-based one-time password based on the named key. The code is valid for the period configured in the key definition.

Parameters

  • name - Key name to generate code for
  • opts - Request options

Returns

  • {:ok, code} - Successfully generated code
  • {:error, error} - Failed to generate code

Examples

{:ok, code} = TOTP.generate_code("user-key")
%{
  code: "810920"
}

list_keys(opts \\ [])

List all configured TOTP keys.

Examples

{:ok, keys} = TOTP.list_keys()
["user-key", "admin-key", "service-key"]

read_key(name, opts \\ [])

Read a TOTP key configuration.

Examples

{:ok, info} = TOTP.read_key("user-key")
%{
  account_name: "user@example.com",
  algorithm: "SHA1",
  digits: 6,
  issuer: "MyApp",
  period: 30
}

validate_code(name, code, opts \\ [])

Validate a TOTP code against a key.

Validates a time-based one-time password generated from the named key. Takes into account the configured skew tolerance for clock drift.

Parameters

  • name - Key name to validate against
  • code - TOTP code to validate
  • opts - Request options

Returns

  • {:ok, result} - Successfully validated code
  • {:error, error} - Failed to validate code

Examples

{:ok, result} = TOTP.validate_code("user-key", "123456")
%{
  valid: true
}