Registry / auth-security / oathtool

oathtool

JSON →
library2.4.0pypypi✓ verified 82d ago

oathtool is a command-line tool and Python library for generating one-time passwords, supporting both HOTP (HMAC-based) and TOTP (Time-based) algorithms. The current version is 2.4.0, and it maintains a stable, albeit infrequent, release schedule, focusing on reliability and security.

pip install oathtool
INSTALL
IMPORT
SIG · OATHTOOL
O
oathtool
auth-securitypythonv2.4.0
Install
1.7s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.2MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

generate_otp
from oathtool import generate_otp
from oathtool.totp import TOTP
generate_otp
import oathtool
from oathtool.totp import TOTP

This quickstart demonstrates how to generate a TOTP code using a base32-encoded secret key, typically obtained from a 2FA setup process. It emphasizes retrieving the secret securely from an environment variable and includes basic error handling for common key issues.

import os from oathtool.totp import TOTP # Retrieve your base32-encoded secret key from an environment variable. # Example: 'JBSWY3DPEHPK3PXP' (this is a placeholder, use your actual secret) secret_base32 = os.environ.get('OATHTOOL_SECRET', 'JBSWY3DPEHPK3PXP') if secret_base32 == 'JBSWY3DPEHPK3PXP': print("WARNING: Using a placeholder secret. Set OATHTOOL_SECRET environment variable for actual use.") try: # Initialize the TOTP generator with your secret. # oathtool expects the secret to be base32-encoded or raw bytes. # If a base32 string is provided, it will be decoded automatically. totp = TOTP(secret_base32) # Generate the current time-based one-time password. current_otp = totp.code() print(f"Generated TOTP: {current_otp}") # You can also get the remaining time until the next code. # time_left = totp.time_left() # print(f"Time left until next code: {time_left} seconds") except Exception as e: print(f"Error generating OTP: {e}") print("Ensure your OATHTOOL_SECRET is a valid base32 encoded string.")
oathtool --version
Debug
Known issues
gotchaSecret keys are typically expected to be base32-encoded strings. While `oathtool` can often handle raw bytes or attempt decoding, providing an invalid base32 string will lead to errors.
fix
Ensure your secret key is a valid base32-encoded string (e.g., from a QR code or provided by the service). Tools like `base64.b32decode` can verify format.
affects: All versions
gotchaHardcoding secret keys directly in your code is a significant security risk. Anyone with access to your code can compromise your accounts.
fix
Always store secret keys securely. Use environment variables (as shown in quickstart), dedicated secret management services, or secure configuration files. For CLI, `oathtool` offers keyring integration.
affects: All versions
gotchaWhen using HOTP, the 'counter' value must be meticulously synchronized between the client (your application) and the server. Desynchronization will lead to invalid codes.
fix
Implement a robust mechanism to store and increment the HOTP counter reliably. Both client and server must agree on the current counter value. If out of sync, a resynchronization process is usually required.
affects: All versions
Upgrade
Version history
2.4.0latest on PyPI · released May 3, 2025
Audit
Dependencies
keyringoptionalUsed for secure storage of keys in some CLI operations.
jaraco.clipboardoptionalUsed for clipboard interaction in some CLI operations.
Agent activity
27 hits · last 30 days
node
24
OpenAI (training)
1
Resources
oathtool — pip install oathtool · libregistry