TOTP Generator

TOTP Generator: The Complete Guide to Time-Based One-Time Passwords and Two-Factor Authentication

Time-Based One-Time Passwords (TOTP) are the most widely deployed standard for software-based two-factor authentication (2FA). When you open Google Authenticator, Authy, 1Password, or Microsoft Authenticator and see a six-digit code that changes every 30 seconds, you're using TOTP. This same mechanism protects millions of accounts across every major platform — Google, GitHub, AWS, Cloudflare, Stripe, Twitter, Coinbase, and thousands more. Understanding how TOTP works, what makes it secure, and where its limitations lie is essential for anyone building secure authentication systems or managing organizational security.

TOTP is defined in RFC 6238 (published 2011) as an extension of HOTP (HMAC-based One-Time Password, RFC 4226 from 2005). It generates temporary codes using a shared secret and the current Unix timestamp, making each code valid only for a short time window. Unlike SMS-based 2FA, TOTP codes are generated entirely offline — no network connection required, no SMS carrier vulnerability, and no real-time server communication needed at code generation time.

How TOTP Works: The Algorithm

Understanding the TOTP algorithm demystifies what seems like magic. The process is actually quite straightforward once you understand each step.

Step 1: The Shared Secret

When you set up TOTP authentication on a service, that service generates a cryptographically random secret — typically 160 bits (20 bytes) of random data. This secret is shared between the server and your authenticator app, usually via a QR code scan. The secret is displayed in Base32 encoding (A–Z plus 2–7) because Base32 is case-insensitive and avoids characters that look similar (0 vs O, 1 vs I vs l).

A typical Base32-encoded TOTP secret looks like: JBSWY3DPEHPK3PXP. This encodes 10 bytes (80 bits) — though RFC 6238 recommends at least 128 bits, and implementations like Google Authenticator use 80-bit secrets by default while better implementations use 160 bits.

The shared secret must be kept confidential on both ends. If an attacker obtains the secret, they can generate all future TOTP codes. Services that have suffered database breaches where TOTP secrets were stored in plaintext have effectively invalidated their 2FA protection for all affected accounts.

Step 2: Time Counter (T)

TOTP uses time to create unique codes. The current Unix timestamp (seconds since January 1, 1970, UTC) is divided by the time step (typically 30 seconds) and the floor is taken:

T = floor(Unix_timestamp / time_step)

For example, at Unix timestamp 1714000200 (April 25, 2024, 10:10:00 UTC): T = floor(1714000200 / 30) = floor(57133340) = 57133340

This means all Unix timestamps within the same 30-second window produce the same T value, and therefore the same TOTP code. T increments by 1 every 30 seconds, making each 30-second window unique.

Step 3: HMAC-SHA1 Computation

The time counter T is converted to an 8-byte big-endian unsigned integer. Then HMAC-SHA1 is computed using the shared secret as the key and the 8-byte T value as the message:

hash = HMAC-SHA1(secret, T_bytes)

HMAC-SHA1 produces a 20-byte (160-bit) output. SHA-1 is considered cryptographically weak for some purposes (collision resistance) but remains secure for HMAC usage — HMAC security depends on the PRF properties of the hash, not its collision resistance.

Some TOTP implementations use HMAC-SHA256 or HMAC-SHA512 instead. The choice of hash algorithm is configured in the TOTP parameters (the "algorithm" field in the otpauth:// URI), though most authenticator apps only support SHA1 despite the spec allowing SHA256 and SHA512.

Step 4: Dynamic Truncation

The 20-byte HMAC output must be reduced to a short numeric code. Dynamic truncation extracts a 4-byte (32-bit) integer from the HMAC output:

1. Take the last byte of the HMAC (byte 19)
2. Use its lower 4 bits as an offset value (0–15)
3. Extract 4 bytes starting at that offset position
4. Set the most significant bit of the first byte to 0 (avoid signed integer issues)
5. Interpret the 4 bytes as a 31-bit unsigned integer

This dynamic truncation is deterministic and produces the same result for the same HMAC input. The offset-based selection adds entropy from the entire HMAC rather than always taking the first 4 bytes.

Step 5: Code Generation

The final TOTP code is computed by taking the truncated integer modulo 10^digits:

TOTP = truncated_integer mod 10^6 (for 6-digit codes)

The result is zero-padded to the specified number of digits. If the modulo result is 34891, the 6-digit code is "034891". Zero-padding is critical — without it, codes starting with 0 would appear to have fewer digits, breaking authentication.

Most TOTP implementations use 6-digit codes (digits=6, mod 1,000,000). Some high-security implementations use 8-digit codes for a 100× larger code space, reducing brute-force attack viability.

The otpauth:// URI Format

TOTP configuration is typically shared via a QR code containing an otpauth:// URI. Understanding this format is important for building TOTP enrollment flows, debugging authentication issues, and migrating between authenticator apps.

The otpauth URI format: otpauth://totp/LABEL?PARAMETERS

Full example:

otpauth://totp/Example%3Auser@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA1&digits=6&period=30

Parameters explained:

• type: totp (time-based) or hotp (counter-based)
• label: Displayed in the authenticator app. Format: issuer:account (URL-encoded)
• secret: Base32-encoded shared secret (no padding required by most implementations)
• issuer: The service name displayed in the authenticator. Should match the issuer in the label.
• algorithm: SHA1 (default), SHA256, or SHA512
• digits: 6 (default) or 8
• period: 30 seconds (default). The time step in seconds. Some systems use 60.
• counter: For HOTP only, the initial counter value

TOTP Security Analysis

TOTP provides significantly stronger authentication than passwords alone, but understanding its security properties and attack vectors is essential for properly evaluating and implementing it.

What TOTP Protects Against

• Password theft/database breach: An attacker with your password still cannot log in without the current TOTP code, which they don't have.
• Password reuse attacks: Even if the same password is used across sites, TOTP prevents the second site's credentials from being used on the first.
• Brute-force password attacks: A successful brute-force yields only the password, not the TOTP secret.
• Credential stuffing: Leaked username/password pairs from other breaches don't enable login when TOTP is required.

Attacks Against TOTP

Real-time phishing (adversary-in-the-middle): The most significant practical attack. A phishing site relays credentials and the TOTP code in real-time to the real site, logging in before the 30-second window expires. Tools like Evilginx2 and Modlishka automate this. TOTP does NOT protect against sophisticated real-time phishing. Hardware security keys (FIDO2/WebAuthn) do protect against this attack, as they bind authentication to the origin URL.

Secret theft: If the server-side TOTP secret database is breached and secrets are stored in plaintext, all accounts' TOTP protection is broken. Secrets should be stored encrypted at rest, ideally using hardware security modules (HSMs).

Brute force in real time: With 6 digits and a 30-second window, an attacker has at most 2 tries per window (most implementations rate-limit to 1–3 attempts before locking). The code space of 1,000,000 values means brute-forcing a single window has only 1-in-1,000,000 chance without rate limiting. With rate limiting, brute force is effectively impossible.

Time manipulation: TOTP codes depend on synchronized clocks. If an attacker can manipulate the victim's system clock, they might reuse codes from past or future windows. Well-implemented TOTP validation includes a clock skew tolerance (typically ±1 window = ±30 seconds) to accommodate slight clock drift.

SIM swapping: This attack targets SMS-based 2FA, not TOTP. TOTP is immune to SIM swapping because it doesn't use SMS.

Malware: If the victim's device is compromised by malware, the attacker can read the TOTP code from the authenticator app (on the same device) or intercept it as it's typed. This is a device compromise problem, not a TOTP problem.

TOTP vs. SMS 2FA vs. FIDO2

Not all 2FA is equally secure. Here's a comparative analysis:

• SMS 2FA: Convenient but weakest — vulnerable to SIM swapping, SS7 attacks, SMS interception, and carrier social engineering. NIST SP 800-63B has deprecated SMS as a primary authentication method.
• TOTP: Good security — immune to SIM swapping and SS7 attacks, works offline, widely supported. Vulnerable to real-time phishing and secret theft. Much better than SMS.
• FIDO2/WebAuthn (hardware keys): Best security — immune to phishing (origin-bound), immune to replay attacks, no shared secret on server, phishing-resistant even in real-time relay scenarios. The gold standard for high-security accounts.
• Push notifications (Duo, Microsoft Authenticator): Convenient but vulnerable to MFA fatigue attacks where attackers spam push requests until the user accidentally approves one.

Implementing TOTP: Server-Side Code

Generating a TOTP Secret

// Node.js
import * as crypto from 'crypto';

function generateTotpSecret(bytes = 20): string {
  const buffer = crypto.randomBytes(bytes);
  return base32Encode(buffer); // Use a base32 library
}

// Python
import secrets
import base64

def generate_totp_secret(byte_length=20):
    random_bytes = secrets.token_bytes(byte_length)
    return base64.b32encode(random_bytes).decode('utf-8')

Validating a TOTP Code

// Node.js — TOTP validation with clock skew tolerance
import * as crypto from 'crypto';

function validateTotp(
  secret: string,  // Base32-encoded
  code: string,    // 6-digit code from user
  window = 1,      // Allow ±window time steps
  digits = 6,
  period = 30
): boolean {
  const secretBytes = base32Decode(secret);
  const now = Math.floor(Date.now() / 1000);
  const T = Math.floor(now / period);

  for (let i = -window; i <= window; i++) {
    const expectedCode = generateHotp(secretBytes, T + i, digits);
    if (timingSafeEqual(code, expectedCode)) return true;
  }
  return false;
}

function generateHotp(secretBytes: Buffer, counter: number, digits: number): string {
  const counterBytes = Buffer.allocUnsafe(8);
  counterBytes.writeBigUInt64BE(BigInt(counter));
  const hmac = crypto.createHmac('sha1', secretBytes).update(counterBytes).digest();
  const offset = hmac[19] & 0xf;
  const code = (((hmac[offset] & 0x7f) << 24) |
                ((hmac[offset + 1] & 0xff) << 16) |
                ((hmac[offset + 2] & 0xff) << 8) |
                (hmac[offset + 3] & 0xff)) % Math.pow(10, digits);
  return code.toString().padStart(digits, '0');
}

Libraries for TOTP Implementation

• Node.js: otplib, speakeasy, @otplib/preset-default
• Python: pyotp, onetimepass
• Go: github.com/pquerna/otp
• Ruby: rotp
• Java: GoogleAuth, aerogear-otp-java
• PHP: spomky-labs/otphp, google-authenticator-php

Always use a well-maintained library rather than implementing TOTP from scratch. Libraries handle edge cases like Base32 padding, clock skew, timing-safe comparison, and HMAC implementation correctly.

Timing-Safe Comparison

TOTP code comparison must use timing-safe string comparison to prevent timing side-channel attacks. A naive code === expected comparison in some languages returns faster when the strings differ at an earlier position, leaking information about how many digits are correct:

// Node.js — timing-safe comparison
import * as crypto from 'crypto';
function timingSafeEqual(a: string, b: string): boolean {
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
}

# Python — timing-safe comparison
import hmac
def timing_safe_equal(a: str, b: str) -> bool:
    return hmac.compare_digest(a, b)

TOTP Enrollment Flow Best Practices

The TOTP setup experience matters as much as the cryptography. A poorly designed enrollment flow leads to support tickets, lockouts, and security gaps.

Secret Generation and QR Code Display

Generate the secret on the server using a CSPRNG (cryptographically secure pseudo-random number generator). Never generate TOTP secrets on the client side. Display the QR code and the raw secret key simultaneously — users may need the raw key to configure authenticators that don't have a camera, or to set up TOTP in a password manager.

Verification Before Enabling

Always require the user to enter a valid TOTP code before saving the secret and enabling TOTP on their account. This confirms they have successfully scanned the QR code and can generate valid codes. Without this verification step, users who fail to scan correctly are locked out.

Backup Codes

Generate a set of single-use backup codes when the user enables TOTP. These codes allow account recovery if the user loses their authenticator device. Standard practice is 8–10 codes of 8–12 characters each. Store them hashed (bcrypt or similar) — treat them as passwords, not secrets. Display them once, warn users to save them securely, and provide a way to regenerate them (which should invalidate all previous backup codes).

Clock Synchronization

TOTP validation must tolerate clock skew. A ±30 second tolerance (allowing the previous and next code window) is standard. Some implementations allow ±90 seconds (3 windows) to accommodate devices with significant clock drift. Track the acceptable clock drift per user if you support very large windows.

Rate Limiting and Account Lockout

Limit TOTP validation attempts to prevent brute force. A common policy: 5 failed attempts within 5 minutes triggers a 15-minute lockout. Send an alert to the account's email when TOTP fails repeatedly. Log all TOTP failures with IP address and user agent for security monitoring.

Recovery Flow

Plan for TOTP recovery before deployment. Common approaches: backup codes, email/SMS verification to disable TOTP temporarily (with a cool-off period), identity verification with customer support, and emergency access codes generated at enrollment. Each approach has security tradeoffs — weaker recovery mechanisms can be exploited for account takeover.

Common TOTP Authenticator Apps

Google Authenticator

The most widely used TOTP app. Simple, reliable, and available on iOS and Android. Key limitation: no cloud backup in the original design (recently added optional Google Account sync). Losing a device without backup codes means manual account recovery for each service. Doesn't support TOTP over USB hardware key.

Authy

Twilio's authenticator with encrypted cloud backup and multi-device sync. More user-friendly for account recovery but introduces Twilio as a trust dependency. Your TOTP secrets are stored (encrypted) on Twilio's servers, adding a cloud attack surface compared to purely local apps.

Microsoft Authenticator

Microsoft's app supports both TOTP and Microsoft-specific push notification 2FA. Includes cloud backup via Microsoft account. Provides passwordless phone sign-in for Microsoft services. Works for all standard otpauth:// TOTP setups.

1Password, Bitwarden, and Password Managers

Many password managers now include TOTP support. This has the convenience advantage of autofilling both password and TOTP code, but concentrates two authentication factors in one application — defeating the "something you have is separate from something you know" principle if the password manager is also your password. Use a separate app if you want true second-factor isolation.

Aegis (Android) and Raivo (iOS)

Open-source authenticators with encrypted local backup, import/export capabilities, and no cloud dependency. Aegis (Android) is widely recommended by security professionals for its transparency and features. Raivo (iOS) provides similar capabilities. Both support standard otpauth:// format.

TOTP in Cloud Platforms and DevOps

AWS IAM TOTP

AWS IAM supports virtual MFA devices (TOTP) for console login. Configure via IAM console > Security credentials > Assign MFA device. Use aws iam enable-mfa-device CLI command. For IAM users requiring MFA, add a condition key: aws:MultiFactorAuthPresent: "true" to IAM policies. For the root account, MFA is critically important — compromise of the AWS root account is catastrophic.

GitHub TOTP

GitHub now requires 2FA for all accounts that contribute to code. TOTP is the recommended method over SMS. GitHub Enterprise supports enforcing TOTP at the organization level. GitHub's device authorization flow (OAuth) doesn't bypass TOTP — each new device authorization still requires TOTP verification.

SSH TOTP with PAM

Adding TOTP to SSH authentication uses the Google Authenticator PAM module:

# Install
apt-get install libpam-google-authenticator

# Configure PAM (/etc/pam.d/sshd)
auth required pam_google_authenticator.so

# Configure SSH (/etc/ssh/sshd_config)
ChallengeResponseAuthentication yes
UsePAM yes
AuthenticationMethods publickey,keyboard-interactive

HOTP: The Counter-Based Predecessor

TOTP is built on HOTP (HMAC-based OTP, RFC 4226). The difference: HOTP uses a counter instead of a timestamp. The counter is stored on both the server and the authenticator, incrementing each time a code is used or requested. TOTP replaced HOTP's counter with the time counter T to avoid the counter synchronization problem — if the user generates codes without authenticating, the counter diverges between client and server. TOTP eliminates this synchronization requirement at the cost of requiring synchronized clocks.

TOTP Alternatives and Future of Authentication

The industry is moving toward phishing-resistant authentication. TOTP, while a major improvement over passwords alone, is vulnerable to real-time phishing. The future is FIDO2/WebAuthn, which binds authentication to the site origin, making phishing attacks impossible even when the attacker runs a real-time relay.

Passkeys — a consumer-friendly implementation of FIDO2 — are now supported by Google, Apple, Microsoft, and most major services. Passkeys replace both passwords and TOTP with a single phishing-resistant credential stored in the device's secure enclave and synchronized through the cloud (iCloud Keychain, Google Password Manager). As passkey adoption grows, TOTP will eventually be positioned as a legacy fallback rather than a primary 2FA mechanism.

For now, TOTP remains the best widely-available 2FA mechanism for most services and users. It is dramatically more secure than no 2FA or SMS-based 2FA, is standardized and interoperable, and requires no special hardware.