TwoFactor.Totp 1.0.0

TwoFactor.Totp

A production-grade, dependency-free TOTP / HOTP two-factor authentication library for .NET 10.

• Implements RFC 6238 (TOTP) on top of RFC 4226 (HOTP).
• Verified against the official RFC 6238 Appendix B test vectors for SHA-1, SHA-256, and SHA-512.
• Secrets are generated with a cryptographically secure RNG (RandomNumberGenerator).
• Code verification uses constant-time comparison and evaluates every candidate step to resist timing attacks.
• Compatible with Google Authenticator, Microsoft Authenticator, Authy, 1Password, etc. (Base32 secrets and otpauth:// URIs).
• No third-party dependencies.

Projects

Quick start

using TwoFactor.Totp;

// 1. Enrolment: create a secret for the user and show it (or a QR code) once.
string secret = TotpSecret.GenerateBase32();
string qrUri = OtpAuthUri.Build(secret, accountName: "alice@example.com", issuer: "Contoso");

// 2. Retrieve the current code (e.g. to show in your own authenticator UI).
Totp totp = Totp.FromBase32(secret);
(string code, int secondsRemaining) = totp.GetCodeWithExpiry();

// 3. Verify a code entered by the user (tolerates +/- 1 time step of clock drift).
bool isValid = totp.VerifyCode(userEnteredCode);

API surface

TotpSecret

• Generate(int byteLength = 20) — random secret bytes via CSPRNG.
• GenerateBase32(int byteLength = 20) — random secret as a Base32 string.

Totp

• new Totp(ReadOnlySpan<byte> secret, TotpOptions? options = null)
• Totp.FromBase32(string base32Secret, TotpOptions? options = null)
• GetCode(DateTimeOffset? timestamp = null) — the current code.
• GetCodeWithExpiry(...) — the code plus seconds until it expires.
• GetSecondsRemaining(...) — seconds left in the current step.
• VerifyCode(string? code, DateTimeOffset? timestamp = null, int verificationWindow = 1)

TotpOptions

• Digits (6–8, default 6), PeriodSeconds (default 30), Algorithm (SHA-1/256/512, default SHA-1).

Base32

• Encode(ReadOnlySpan<byte>) / Decode(string) — RFC 4648, tolerant of padding, whitespace, and casing.

OtpAuthUri

• Build(base32Secret, accountName, issuer, options?) — otpauth://totp/... provisioning URI for QR codes.

Security notes

• Store the shared secret encrypted at rest (e.g. with a KMS/HSM or a data-protection key). Never log it.
• Enforce rate limiting / lockout on verification attempts to prevent brute force.
• Keep the default verificationWindow small; each extra step widens the acceptance window.
• To prevent replay within a step, record the last accepted step per user and reject reuse.
• HMAC-SHA1 is the authenticator default and is safe in the HMAC construction; SHA-256/512 are available via TotpOptions.

Build & test

dotnet build -c Release
dotnet test  -c Release
dotnet run --project samples/TwoFactor.Demo -c Release