TOTP

How TOTP works

TOTP is built on HOTP. RFC 4226 defines HOTP(K,C) as a truncated HMAC-SHA-1 of a shared secret K and an 8-byte counter C. It requires codes of at least six digits and a shared secret of at least 128 bits, and recommends 160 bits. RFC 6238 replaces the counter with time: TOTP = HOTP(K, T), where T = (current Unix time - T0) / X, rounded down. The defaults are a time step X of 30 seconds and T0 of 0, the Unix epoch, and HMAC-SHA-256 or HMAC-SHA-512 may replace SHA-1.

Both sides hold the same secret, usually copied once from a QR code, and each computes the code on its own. Nothing is sent to your phone at login. The server compares what you type with its own result and tolerates small clock drift: RFC 6238 recommends allowing at most one time step for network delay. It also says a verifier must not accept a second attempt of an OTP that has already been validated.

Setting up TOTP for SSH through PAM

On Debian and Ubuntu the libpam-google-authenticator package provides pam_google_authenticator.so. Each user creates a secret once. According to the module documentation, it is saved in ~/.google_authenticator:

google-authenticator -t -d -r 3 -R 30 -e 10

These flags choose time-based codes, disallow reuse of a code, allow at most 3 logins per 30 seconds and generate 10 emergency codes (the maximum). Then wire it into PAM and sshd:

# /etc/pam.d/sshd
auth required pam_google_authenticator.so

# /etc/ssh/sshd_config
UsePAM yes
KbdInteractiveAuthentication yes
AuthenticationMethods publickey,keyboard-interactive

The nullok option lets users without a secret log in with no code, which helps during rollout but must be removed afterwards. Validate with sudo sshd -t, check that timedatectl shows a synchronised clock, and test in a new session while an old one stays open. The full order of steps is in the SSH two-factor guide linked below.

Limits, drift and common mistakes

• Phishing. NIST SP 800-63B-4 states that OTP authentication is not phishing-resistant: a manually typed code is not bound to the session, so a fake site can relay it to the real one while it is still valid.
• Reuse. The -d option implements the one-use rule. It limits logins to about one per 30 seconds but makes man-in-the-middle attempts easier to notice.
• Clock drift. The module's default window is 3 codes (one before, current, one after), so about 30 seconds of skew is tolerated. A wider window, warns RFC 6238, widens the attack window too. Without noskewadj the module can learn your skew from three consecutive logins.
• Guessing. A short numeric code needs a rate limit, which is what -r and -R set.
• Secret on the server. The first line of ~/.google_authenticator is the base32 secret, and the module insists on mode 0600 by default. Anyone who can read it can generate valid codes, so TOTP does not protect a compromised account on the server.
• Emergency codes. They are single-use eight-digit codes. Store them offline.

Where TOTP fits in hardening

TOTP adds something you have to the key you already use for SSH, so a copied private key alone no longer opens the server. It is a sensible second factor for administrator accounts and costs nothing, but it is the weaker option: CISA describes FIDO/WebAuthn as the widely available phishing-resistant method, so choose a hardware key where you can, as covered under FIDO2 and WebAuthn.

Roll it out in this order:

1. Finish SSH hardening and key-based login first.
2. Follow the SSH two-factor authentication guide for the PAM and sshd changes.
3. Enrol administrators first and give automation its own restricted keys, since a job cannot type a code.
4. Keep emergency codes offline and a provider console available, and know the steps in the SSH lockout recovery guide.

The PAM entry explains the module stack that carries the code check.

Related terms: Two-factor authentication, PAM, FIDO2 and WebAuthn, Key-based authentication, SSH.