Instance Method

authenticate(password:)

Perform the AUTHENTICATE handshake (control-spec.txt §3.5).

func authenticate(password: String? = nil) async throws

Parameters

password: Optional cleartext password, used only for method (2). Ignored when cookie auth succeeds.

Mentioned In

Using the Tor Control Protocol

Discussion

Tries up to three authentication methods, in order:

Cookie — if dataDirectory was provided and <dataDir>/control_auth_cookie exists, the 32-byte cookie is hex-encoded and sent as AUTHENTICATE <hex>.
Password — if a password argument is supplied, sent as AUTHENTICATE "<quoted password>". Requires Tor to be configured with matching HashedControlPassword.
Null — as a last resort, sends bare AUTHENTICATE. Works on sockets configured for no-auth (rare; also used by some test harnesses).

A no-op when isAuthenticated is already true.

Throws

TorError.controlAuthFailed(_:) if every method exhausted returns a non-success reply (Tor reply 515).

Important

For embedded-mode control sockets constructed via init(fileDescriptor:preAuthenticated:dataDirectory:) with preAuthenticated: true, this method is a no-op and never sends AUTHENTICATE on the wire.