oathtool

Generate and verify one-time passwords

TLDR

Generate TOTP token (behaves like Google Authenticator)

$ oathtool --totp [[-b|--base32]] "[secret]"

Generate a TOTP token for a specific time

$ oathtool --totp [[-N|--now]] "[2004-02-29 16:21:42]" [[-b|--base32]] "[secret]"

Validate a TOTP token

$ oathtool --totp [[-b|--base32]] "[secret]" "[token]"

SYNOPSIS

oathtool [--totp | --hotp] [OPTIONS] KEY
oathtool --convert-otp-key [OPTIONS] KEY
oathtool --help | --version

--totp
    Generate or validate a TOTP code (Time-based One-Time Password).

--hotp
    Generate or validate a HOTP code (HMAC-based One-Time Password).

KEY
    The secret key used for OTP generation or validation. By default, it's interpreted as hexadecimal.

--base32
    Interpret the input KEY as Base32 encoded (RFC 4648).

--hex
    Interpret the input KEY as hexadecimal encoded (default).

--print-base32
    Print the generated KEY in Base32 encoding when using --convert-otp-key.

--print-hex
    Print the generated KEY in hexadecimal encoding when using --convert-otp-key (default output).

--count=
    Specify the HOTP counter value (step count) for --hotp operations.

--start-offset=
    Start the HOTP counter from N when validating a range for --hotp.

--now=
    Set the current time for TOTP operations. Accepts various time formats, e.g., 'now', '2023-10-27 10:00:00', or a Unix timestamp.

--time-step=
    Set the TOTP time-step size to N seconds (default 30 seconds).

--digits=
    Specify the number of digits for the OTP (default 6; can be 6, 7, 8, 9).

--check=    Validate a user-provided CODE against the KEY (requires --hotp or --totp). --force     Force validation for --check even if the current counter/time is outside a reasonable window. --verbose     Enable verbose output, showing intermediate calculations. --convert-otp-key     Convert the input KEY to a different encoding format based on output options (e.g., --print-base32). --rfc     Use RFC-compliant defaults for hashing algorithms and time steps (e.g., SHA1 for TOTP, 30s step). --help     Display help information and exit. --version     Display version information and exit.


        DESCRIPTION
        
          oathtool is a command-line utility from the OATH Toolkit for generating and validating one-time passwords (OTPs) based on the OATH (Open AuTHentication) standards. It supports both TOTP (Time-based One-Time Password) as defined in RFC 6238 and HOTP (HMAC-based One-Time Password) as defined in RFC 4226.

This tool is invaluable for developers, system administrators, and security professionals who need to work with OTPs in scripts, for testing authentication systems, or for offline token generation. It allows you to generate codes from a secret key, verify user-provided codes against a secret, and convert secret keys between different encodings like Base32 and hexadecimal. While powerful, it operates purely locally and does not integrate with any external authentication services.
        
        CAVEATS
        
          oathtool is a command-line utility and does not provide a full authentication system. It is designed for offline generation and validation of OTPs. 

Security Implications: Handling secret keys on the command line or in scripts can be insecure as the key might be exposed in shell history or process listings. Exercise caution when dealing with sensitive keys. For robust security, keys should be stored and managed securely, often requiring a secure key store or hardware security module (HSM). 

It's also crucial to ensure the system's clock is accurate for TOTP operations to work reliably, as time synchronization is vital.
        
        USAGE EXAMPLES
        
          Here are a few common examples demonstrating oathtool's capabilities:

1. Generate a TOTP code (default 6 digits, 30s step, hex key):
    oathtool --totp 3132333435363738393031323334353637383930

2. Generate a HOTP code with a specific counter (Base32 key):
    oathtool --hotp --base32 --count=10 JBSWY3DPEHPK3PXP

3. Convert a Base32 key to Hexadecimal:
    oathtool --convert-otp-key --base32 --print-hex JBSWY3DPEHPK3PXP

4. Validate a TOTP code (checks against current time):
    oathtool --totp --check=123456 3132333435363738393031323334353637383930

        
        KEY FORMATS
        
          oathtool supports secret keys in two primary formats:
    Hexadecimal: This is the default format. A hexadecimal key consists of characters '0'-'9' and 'a'-'f' (or 'A'-'F'). Each pair of characters represents a byte.
    Base32: This format is often used for human readability and URL-safety (RFC 4648). It uses characters 'A'-'Z' and '2'-'7'. When specifying a Base32 key, you must use the --base32 option.

The tool can also convert keys between these formats using the --convert-otp-key option.
        
        OATH STANDARDS (HOTP & TOTP)
        
          HOTP (HMAC-based One-Time Password) (RFC 4226): This algorithm generates an OTP based on a shared secret key and a moving counter. Each time a new OTP is generated, the counter is incremented. Validation requires the server to keep track of the client's current counter value.

TOTP (Time-based One-Time Password) (RFC 6238): This is an extension of HOTP that replaces the counter with a time-based value. The OTP is generated using a shared secret key and the current time (usually truncated to a 30 or 60-second window). Both client and server must have synchronized clocks for successful validation.
        
        HISTORY
        
          oathtool is a core component of the OATH Toolkit, an open-source software project that provides libraries and applications for implementing OATH (Open AuTHentication) standards. The toolkit was primarily developed by Simon Josefsson, known for his contributions to cryptographic software and standards. Its development aimed to provide robust, open-source implementations of HOTP and TOTP, making it accessible for integration into various systems and for testing purposes since its early releases around the mid-2000s.
        
        SEE ALSO
        
          base32(1), date(1), sha1sum(1), openssl(1)