Authentication Systems for Tor Hidden Services

The foundation of .onion service authentication is password-based login without email recovery dependency. Email recovery requires users to provide an email address (potentially de-anonymizing) and requires the server to make outbound SMTP connections. Replace email recovery with: (1) Backup codes - generate 10-20 one-time recovery codes during registration, displayed once and stored by the user. If the user loses their password, they use a backup code to regain access. Invalidate each code after use. (2) Passphrase-based key derivation - derive an account key from a master passphrase (distinct from the login password), allowing account recovery without server-side secrets. (3) Manual recovery - admin resets password after out-of-band identity verification (suitable for closed communities). Password hashing: use argon2id (the current best practice) with appropriate memory, time, and parallelism parameters. Libraries: argon2-cffi for Python, node-argon2 for Node.js, argon2 crate for Rust. bcrypt is acceptable but argon2id is preferred for new systems.

Time-based One-Time Passwords (TOTP) work without clearnet dependency - the shared secret is established during setup (stored on server and in authenticator app), and subsequent verification is purely local computation. TOTP algorithm (RFC 6238) computes a 6-digit code from the shared secret and current Unix timestamp. Setup flow: server generates a random 160-bit TOTP secret, encodes as Base32, generates a QR code containing the otpauth:// URI, displays to user during 2FA setup, user scans with authenticator app (Google Authenticator, Aegis, FreeOTP - all work offline). Verification: server receives 6-digit code, computes expected code for current time window (+/- 1 window for clock drift tolerance), compares. TOTP requires accurate server time (ntpd or chrony). Implement TOTP with time window tolerance but limit to +/- 1 window (30 seconds) to minimize replay window. Store TOTP secrets encrypted in the database (using the user's password-derived key if possible). Rate limit TOTP verification attempts (3-5 attempts before temporary lockout).

Tor's Onion Authentication (also called Client Authorization) is a built-in mechanism that restricts hidden service access to clients with specific cryptographic keys. It works at the Tor protocol level, below the application layer. Setup: generate client keypairs (Curve25519) using tor --keygen or the stem library. Add the client's public key to the hidden service's authorized_clients/ directory (in the HiddenServiceDir). Tor will only allow connections from clients presenting the corresponding private key. Client configuration: the client adds the private key to their Tor configuration (ClientOnionAuthDir). Connections to the .onion address only succeed with the private key loaded. This is application-independent authentication - any application behind the hidden service is automatically restricted to authorized clients. Use case: restrict admin interfaces, development servers, or sensitive services to specific authorized users at the Tor layer without any application-level authentication code.

For API services on .onion, mutual TLS (mTLS) with client certificates provides strong authentication without passwords. Setup: create a private CA (Certificate Authority) for the hidden service. Issue client certificates signed by this CA. Configure nginx with ssl_client_certificate (CA certificate) and ssl_verify_client on. Clients present their certificate when connecting. Nginx passes the verified client certificate details as HTTP headers to the backend application. The application reads these headers (CN, subject, serial number) to identify the authenticated client. Client certificate management: issue per-user certificates with serial numbers. Revoke certificates via CRL (Certificate Revocation List) or OCSP (note: OCSP requires external connectivity - use CRL instead for .onion services). Certificate rotation: issue new certificates before expiry, revoke old ones. This authentication scheme is particularly strong for machine-to-machine API access where each API consumer has its own certificate.

Some .onion services benefit from allowing truly anonymous accounts - no password, no registration, just a temporary identity derived from a cryptographic key. The client generates an Ed25519 keypair locally. The public key is the account identifier. Authentication: the client signs a challenge from the server with the private key. The server verifies the signature against the stored public key. The private key never leaves the client, and the public key reveals nothing about the user's identity. This is similar to how Bitcoin addresses work - the address (public key) is the identity, and the private key proves ownership. Libraries: libsodium (nacl/tweetnacl for JS, PyNaCl for Python) provides Ed25519 sign/verify. User experience challenge: users must securely back up their private key (if lost, the account is permanently inaccessible). For anonymous account recovery, the only option is admin-initiated key replacement after out-of-band identity verification. This scheme is appropriate for high-security contexts where the account owner wants no password-based access method.