A field guide to time-based authentication

The code changes every thirty seconds.
Here's exactly how, and why it holds.

A complete, implementation-ready guide to Time-Based One-Time Passwords — the formula, the code, the failure modes, and the production checklist — in one booklet.

Get the booklet → See what's inside
30
seconds left
0
0
0
0
0
0

A real TOTP code, generated live in your browser with HMAC-SHA1, on the same 30-second clock the booklet walks through step by step.

Chapter 4 — Security Considerations

What a rotating code actually stops

TOTP doesn't replace your password. It changes what a stolen one is worth.

A leaked password

A password sitting in a breach dump is useless on its own — the attacker still needs a code that expires before they can use it.

A phishing page

Captured credentials go stale fast. A code copied from a fake login screen is often dead by the time it's replayed.

A hijacked session

Starting a new session still requires the current code, so a stolen password alone can't open a fresh one.

Table of contents

Inside the booklet

Ten chapters and three appendices, in the order you'd actually need them — from the core formula to a production testing checklist.

01
Introduction to TOTP
What it is, and what it protects that a password alone can't.
FOUNDATIONS
02
How TOTP Works
The HOTP(K,T) formula, HMAC generation, and dynamic truncation, step by step.
ALGORITHM
03
Implementation Guide
Secret generation, QR provisioning URIs, and verification code you can ship.
BUILD
04
Security Considerations
Threat model, key storage, clock drift, and brute-force defenses.
HARDEN
05
User Experience and Adoption
Onboarding flows, error states, and recovering a locked-out account.
PRODUCT
06
Popular Authenticator Applications
Google Authenticator, Authy, 1Password, and Bitwarden, compared.
TOOLING
07
Advanced Topics
TOTP against SMS and push, parameter tuning, and enterprise rollout.
DEPTH
08
Testing and Validation
RFC 6238 test vectors and a checklist to run before you ship.
VERIFY
09
Future Developments and Trends
WebAuthn, passkeys, and where TOTP still fits.
OUTLOOK
10
Conclusion
What to take away, and where to go from here.
CLOSE
A
Quick Reference Guide
Every default parameter, on one page.
APPENDIX
B
Troubleshooting Guide
Fixes for invalid codes, setup failures, and intermittent errors.
APPENDIX
C
Resources and Further Reading
RFCs, libraries, and standards worth bookmarking.
APPENDIX

A page from Chapter 2 and 3

The formula, and the code behind it

Every worked example in the booklet ends in something you can paste into a terminal.

The core formula

TOTP = HOTP(K, T)

  • K The shared secret, 160 bits, Base32-encoded for the QR code.
  • T The current time step — Unix time divided by 30 seconds.
  • 01 Hash K and T together with HMAC-SHA1.
  • 02 Take a 4-bit offset from the last byte of the hash.
  • 03 Read 4 bytes from that offset, mask to 31 bits.
  • 04 Modulo 10⁶, zero-pad — that's your six-digit code.
verify_totp() — with clock-drift tolerance
def verify_totp(secret, user_code, window=1):
    # window: ±1 step = 3 codes checked
    key = base64.b32decode(secret)

    for offset in range(-window, window + 1):
        step = int(time.time() / 30) + offset
        code = generate_totp_code(key, step)

        if code == user_code:
            return True

    return False

Who it's written for

Built for the people who have to make it work

Developers

Adding 2FA to a product and need working code for setup, QR provisioning, and verification — not just the theory.

Security engineers

Reviewing an existing TOTP flow for key storage, rate limiting, and clock-drift handling before an audit.

Product & support teams

Writing the onboarding screens, error copy, and recovery flow that most 2FA rollouts get wrong.

Standardized in RFC 6238

Everything above, in one booklet.

Ten chapters, three appendices, and the code to go with them — explained in plain English.

Get the booklet →Get the Android Authenticator