kdbxtool.security.totp¶

TOTP (Time-based One-Time Password) implementation per RFC 6238.

This module provides TOTP code generation from otpauth:// URIs stored in KeePass entry otp fields.

Functions

`generate_totp`(config[, timestamp])	Generate a TOTP code.
`parse_keepassxc_legacy`(seed[, settings])	Parse KeePassXC legacy TOTP fields.
`parse_otpauth_uri`(uri)	Parse an otpauth:// URI into a TotpConfig.

Classes

`TotpCode`(code, period, generated_at)	A generated TOTP code with expiration info.
`TotpConfig`(secret[, digits, period, ...])	TOTP configuration parsed from an otpauth:// URI.

class kdbxtool.security.totp.TotpCode(code, period, generated_at)[source]¶

Bases: object

A generated TOTP code with expiration info.

Parameters:

code (str)
period (int)
generated_at (float)

code¶

The TOTP code as a zero-padded string (e.g., “123456”)

Type:: str

period¶

Time step in seconds (typically 30)

Type:: int

generated_at¶

Unix timestamp when code was generated

Type:: float

code: str¶

period: int¶

generated_at: float¶

property remaining: int¶

Seconds remaining until this code expires.

Note: This is calculated fresh each call based on current time.

property expires_at: datetime¶: Datetime when this code expires.

property is_expired: bool¶: Whether this code has expired.

__init__(code, period, generated_at)¶

Parameters:

code (str)
period (int)
generated_at (float)

Return type:

None

class kdbxtool.security.totp.TotpConfig(secret, digits=6, period=30, algorithm='SHA1', issuer=None, account=None)[source]¶

Bases: object

TOTP configuration parsed from an otpauth:// URI.

Parameters:

secret (bytes)
digits (int)
period (int)
algorithm (Literal['SHA1', 'SHA256', 'SHA512'])
issuer (str | None)
account (str | None)

secret¶

Base32-encoded secret key (decoded to bytes internally)

Type:: bytes

digits¶

Number of digits in the code (default: 6)

Type:: int

period¶

Time step in seconds (default: 30)

Type:: int

algorithm¶

Hash algorithm (SHA1, SHA256, or SHA512)

Type:: Literal[‘SHA1’, ‘SHA256’, ‘SHA512’]

issuer¶

Optional issuer name

Type:: str | None

account¶

Optional account name/label

Type:: str | None

secret: bytes¶

digits: int = 6¶

period: int = 30¶

algorithm: Literal['SHA1', 'SHA256', 'SHA512'] = 'SHA1'¶

issuer: str | None = None¶

account: str | None = None¶

__init__(secret, digits=6, period=30, algorithm='SHA1', issuer=None, account=None)¶

Parameters:

secret (bytes)
digits (int)
period (int)
algorithm (Literal['SHA1', 'SHA256', 'SHA512'])
issuer (str | None)
account (str | None)

Return type:

None

kdbxtool.security.totp.parse_otpauth_uri(uri)[source]¶

Parse an otpauth:// URI into a TotpConfig.

Supports the standard otpauth:// URI format:: otpauth://totp/LABEL?secret=BASE32SECRET&issuer=ISSUER&…

Parameters:: uri (str) – The otpauth:// URI string
Returns:: TotpConfig with parsed parameters
Raises:: ValueError – If the URI is invalid or missing required parameters
Return type:: TotpConfig

kdbxtool.security.totp.parse_keepassxc_legacy(seed, settings=None)[source]¶

Parse KeePassXC legacy TOTP fields.

KeePassXC historically stored TOTP in separate custom fields: - “TOTP Seed”: Base32 secret - “TOTP Settings”: “period;digits” (e.g., “30;6”)

Parameters:

seed (str) – The TOTP seed (base32 encoded secret)
settings (str | None) – Optional settings string in “period;digits” format

Returns:

TotpConfig with parsed parameters

Return type:

TotpConfig

kdbxtool.security.totp.generate_totp(config, timestamp=None)[source]¶

Generate a TOTP code.

Parameters:

config (TotpConfig) – TOTP configuration
timestamp (float | None) – Unix timestamp (defaults to current time)

Returns:

TotpCode with code string and expiration info

Return type:

TotpCode