Building a Simple TOTP Generator with macOS Keychain

As someone who frequently authenticates with AWS CLI and other services from the terminal, I needed a lightweight way to generate TOTP (Time-Based One-Time Password) codes without relying on third-party apps. While totp-cli is a great tool, I wanted to understand the inner workings of OTP generation. This led me to create totp-keychain, a minimal Python script that retrieves secrets from the macOS Keychain and generates TOTP codes on demand.

What This Script Does #

totp-keychain is a simple script that:

• Retrieves a stored TOTP secret from macOS Keychain.
• Uses Python’s built-in cryptographic libraries to generate a 6-digit TOTP code.
• Prints the OTP to the terminal for quick use in authentication.

This makes it especially useful for AWS CLI authentication, logging into web apps, or any service requiring TOTP-based 2FA.

How TOTP Works #

TOTP is a time-based variant of the HMAC-Based One-Time Password (HOTP). It works as follows:

1. A secret key (usually Base32-encoded) is shared between the client and server.
2. The current time (in 30-second intervals) is used as a counter.
3. An HMAC-SHA1 hash is computed using the secret key and counter.
4. A subset of the hash is extracted using dynamic truncation.
5. The result is converted into a 6-digit numeric code.

This code remains valid for a short period, making it resistant to replay attacks.

Diving Into the Code #

The script consists of a few key functions:

1. Retrieving the Secret from macOS Keychain #

def get_secret_from_keychain(service: str, account: str) -> str:
    """Retrieve the secret from macOS Keychain using the `security` command."""
    try:
        result = subprocess.run(
            ["security", "find-generic-password", "-s", service, "-a", account, "-w"],
            capture_output=True,
            text=True,
            check=True
        )
        return result.stdout.strip()
    except subprocess.CalledProcessError as e:
        print(f"Error retrieving secret from Keychain: {e.stderr.strip()}", file=sys.stderr)
        sys.exit(1)

2. Generating HOTP (Hash-Based One-Time Password) #

def generate_hotp(secret: str, counter: int) -> str:
    """Generate an HOTP token based on the given secret and counter."""
    try:
        key = base64.b32decode(secret, casefold=True)
    except base64.binascii.Error:
        print("Invalid base32-encoded secret.", file=sys.stderr)
        sys.exit(1)
    
    msg = struct.pack(">Q", counter)
    hmac_digest = hmac.new(key, msg, hashlib.sha1).digest()
    offset = hmac_digest[19] & 0xF
    code = (struct.unpack(">I", hmac_digest[offset:offset + 4])[0] & 0x7FFFFFFF) % 1000000
    return f"{code:06d}"

3. Generating TOTP (Time-Based One-Time Password) #

def generate_totp(secret: str) -> str:
    """Generate a TOTP token based on the current time."""
    return generate_hotp(secret, counter=int(time.time()) // 30)

Using the Script #

1. Store Your Secret in macOS Keychain #

security add-generic-password -s "okta_totp" -a "okta" -w "MYSECRETKEY" -U

2. Generate an OTP #

python totp-keychain.py --service okta_totp --account okta

This prints a 6-digit OTP to use in authentication.

That’s it! #

This was initially a rough draft to mimic totp-cli, but it turned out to be a great learning experience in understanding the mechanics of OTP.

Please Check out totp-keychain. 🚀