Module auth 

Authentication methods for Tor control protocol.

This module provides functions for authenticating to Tor’s control interface. All control connections must authenticate before they can be used, even if Tor hasn’t been configured to require any authentication.

Overview

Tor supports four authentication methods, tried in this order by authenticate:

1. NONE - No authentication required (open control port)
2. SAFECOOKIE - Challenge-response authentication with HMAC (preferred for local connections)
3. COOKIE - Cookie file authentication (fallback for older Tor versions)
4. PASSWORD - Password authentication using HashedControlPassword

Conceptual Role

The authentication module handles the security handshake between a client and Tor’s control interface. It queries Tor for supported authentication methods via get_protocol_info, then attempts authentication using the most secure available method.

Security Considerations

• SAFECOOKIE is preferred over COOKIE because it uses HMAC challenge-response, preventing replay attacks where an attacker captures and reuses the cookie value.
• Cookie files should have restrictive permissions (readable only by the Tor user).
• Passwords are hex-encoded before transmission but are not encrypted on the wire.
• The module uses constant-time comparison for cryptographic values to prevent timing attacks.

Example

use stem_rs::auth::{authenticate, get_protocol_info};
use stem_rs::ControlSocket;

let mut socket = ControlSocket::connect_port("127.0.0.1:9051".parse()?).await?;

// Query available authentication methods
let protocol_info = get_protocol_info(&mut socket).await?;
println!("Tor version: {}", protocol_info.tor_version);
println!("Auth methods: {:?}", protocol_info.auth_methods);

// Authenticate (auto-detects best method)
authenticate(&mut socket, None).await?;

This Compiles But Is Wrong

use stem_rs::auth::authenticate;
use stem_rs::ControlSocket;

let mut socket = ControlSocket::connect_port("127.0.0.1:9051".parse()?).await?;

// WRONG: Don't call authenticate twice on the same connection!
// Tor may reject or disconnect after the first successful authentication.
authenticate(&mut socket, None).await?;
// authenticate(&mut socket, None).await?; // This would fail!

See Also

• socket: Low-level control socket communication
• controller: High-level Controller API (handles auth automatically)

Structs

ProtocolInfo

Information about Tor’s control protocol and authentication requirements.

Enums

AuthMethod

Authentication methods supported by Tor’s control protocol.

Functions

authenticate

Authenticates to Tor using the best available method.

authenticate_cookie

Authenticates using a cookie file.

authenticate_none

Authenticates to an open control socket (no credentials required).

authenticate_password

Authenticates using a password.

authenticate_safecookie

Authenticates using the SAFECOOKIE challenge-response protocol.

get_protocol_info

Queries Tor for protocol and authentication information.