pub enum AuthError {
NoMethods,
IncorrectPassword,
CookieUnreadable(String),
IncorrectCookie,
IncorrectCookieSize,
ChallengeFailed,
ChallengeUnsupported,
SecurityFailure,
MissingPassword,
UnrecognizedMethods(Vec<String>),
IncorrectSocketType,
}Expand description
Authentication-specific errors.
These errors provide detailed information about why authentication with Tor’s control port failed.
§Authentication Methods
Tor supports several authentication methods:
- NONE: No authentication required (open control port)
- PASSWORD: Password-based authentication (HashedControlPassword)
- COOKIE: Cookie file authentication (CookieAuthentication)
- SAFECOOKIE: Challenge-response cookie authentication (recommended)
§Recovery Guide
| Error | Recovery Action |
|---|---|
NoMethods | Configure authentication in torrc |
IncorrectPassword | Verify password matches HashedControlPassword |
CookieUnreadable | Check file permissions and path |
IncorrectCookie | Cookie file may be stale; restart Tor |
ChallengeFailed | SAFECOOKIE protocol error; try COOKIE |
MissingPassword | Provide password for PASSWORD auth |
§Example
use stem_rs::AuthError;
fn handle_auth_error(err: AuthError) {
match err {
AuthError::IncorrectPassword => {
eprintln!("Wrong password - check your torrc HashedControlPassword");
}
AuthError::CookieUnreadable(path) => {
eprintln!("Cannot read cookie file: {}", path);
eprintln!("Check file permissions and that Tor is running");
}
AuthError::NoMethods => {
eprintln!("No compatible auth methods - configure torrc");
}
_ => eprintln!("Authentication error: {}", err),
}
}Variants§
NoMethods
No compatible authentication methods are available.
Tor’s PROTOCOLINFO response didn’t include any authentication methods that this library supports.
§Recovery
Configure at least one of: CookieAuthentication, HashedControlPassword, or disable authentication entirely in torrc.
IncorrectPassword
The provided password was incorrect.
PASSWORD authentication failed because the password doesn’t match the HashedControlPassword in torrc.
§Recovery
Verify the password matches what was used to generate HashedControlPassword.
Use tor --hash-password to generate a new hash if needed.
CookieUnreadable(String)
The cookie file could not be read.
COOKIE or SAFECOOKIE authentication requires reading a cookie file, but the file couldn’t be accessed.
§Recovery
- Verify the cookie file path is correct
- Check file permissions (must be readable by your process)
- Ensure Tor is running (cookie file is created on startup)
IncorrectCookie
The cookie value was incorrect.
The cookie file was read successfully, but Tor rejected the value. This can happen if the cookie file is stale (from a previous Tor run).
§Recovery
Restart Tor to generate a fresh cookie file, then retry authentication.
IncorrectCookieSize
The cookie file has an incorrect size.
Tor’s cookie file should be exactly 32 bytes. A different size indicates file corruption or an incorrect file.
§Recovery
Verify you’re reading the correct cookie file. Restart Tor if needed.
ChallengeFailed
SAFECOOKIE challenge-response failed.
The SAFECOOKIE authentication protocol failed during the challenge-response exchange.
§Recovery
- Fall back to COOKIE authentication if available
- Verify the cookie file is current
- Check for network issues between client and Tor
ChallengeUnsupported
SAFECOOKIE authentication is not supported.
The Tor version doesn’t support SAFECOOKIE, or it’s disabled.
§Recovery
Use COOKIE or PASSWORD authentication instead.
SecurityFailure
A security check failed during authentication.
This indicates a potential security issue, such as a mismatch in expected vs. received authentication data.
§Recovery
This may indicate a man-in-the-middle attack. Verify your connection to Tor is secure.
MissingPassword
PASSWORD authentication was requested but no password provided.
The authenticate method was called without a password, but PASSWORD is the only available authentication method.
§Recovery
Provide a password to the authenticate method.
UnrecognizedMethods(Vec<String>)
Tor advertised unrecognized authentication methods.
PROTOCOLINFO returned authentication methods this library doesn’t recognize. This may indicate a newer Tor version.
§Recovery
Update stem-rs to a newer version that supports these methods.
IncorrectSocketType
Wrong socket type for the requested authentication.
Some authentication methods are only valid for certain socket types (e.g., Unix domain sockets vs. TCP sockets).
§Recovery
Use a different authentication method appropriate for your socket type.