Function authenticate 

pub async fn authenticate(
    socket: &mut ControlSocket,
    password: Option<&str>,
) -> Result<(), Error>

Authenticates to Tor using the best available method.

This function queries Tor for supported authentication methods via get_protocol_info, then attempts authentication using the most secure available method in this order:

1. NONE - If no authentication is required
2. SAFECOOKIE - HMAC challenge-response (most secure)
3. COOKIE - Cookie file contents
4. PASSWORD - If a password is provided

Preconditions

• The socket must be connected but not yet authenticated
• For password authentication, password must be Some

Postconditions

• On success: The socket is authenticated and ready for commands
• On failure: The socket state is undefined; reconnection is recommended

Arguments

• socket - A connected control socket
• password - Optional password for PASSWORD authentication

Errors

Returns Error::Authentication with specific AuthError variants:

• AuthError::NoMethods: No compatible auth methods available
• AuthError::MissingPassword: PASSWORD auth required but no password provided
• AuthError::IncorrectPassword: PASSWORD auth failed
• AuthError::CookieUnreadable: Cannot read cookie file
• AuthError::IncorrectCookie: COOKIE auth failed
• AuthError::ChallengeFailed: SAFECOOKIE challenge failed

Example

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

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

// Auto-detect authentication method (no password)
authenticate(&mut socket, None).await?;

// Or with a password
// authenticate(&mut socket, Some("my_password")).await?;

Security

• Passwords are hex-encoded before transmission but not encrypted
• Cookie comparison uses constant-time algorithm to prevent timing attacks
• SAFECOOKIE nonces are cryptographically random (32 bytes)