Controller Connection¶

Functions for connecting and authenticating to the tor process.

The connect() function give an easy, one line method for getting an authenticated control connection. This is handy for CLI applications and the python interactive interpreter, but does several things that makes it undesirable for applications (uses stdin/stdout, suppresses exceptions, etc).

import sys

from stem.connection import connect

if __name__ == '__main__':
  controller = connect()

  if not controller:
    sys.exit(1)  # unable to get a connection

  print 'Tor is running version %s' % controller.get_version()
  controller.close()

% python example.py
Tor is running version 0.2.4.10-alpha-dev (git-8be6058d8f31e578)

… or if Tor isn’t running…

% python example.py
[Errno 111] Connection refused

The authenticate() function, however, gives easy but fine-grained control over the authentication process. For instance…

import sys
import getpass
import stem.connection
import stem.socket

try:
  control_socket = stem.socket.ControlPort(port = 9051)
except stem.SocketError as exc:
  print 'Unable to connect to port 9051 (%s)' % exc
  sys.exit(1)

try:
  stem.connection.authenticate(control_socket)
except stem.connection.IncorrectSocketType:
  print 'Please check in your torrc that 9051 is the ControlPort.'
  print 'Maybe you configured it to be the ORPort or SocksPort instead?'
  sys.exit(1)
except stem.connection.MissingPassword:
  controller_password = getpass.getpass('Controller password: ')

  try:
    stem.connection.authenticate_password(control_socket, controller_password)
  except stem.connection.PasswordAuthFailed:
    print 'Unable to authenticate, password is incorrect'
    sys.exit(1)
except stem.connection.AuthenticationFailure as exc:
  print 'Unable to authenticate: %s' % exc
  sys.exit(1)

Module Overview:

connect - Simple method for getting authenticated control connection

authenticate - Main method for authenticating to a control socket
authenticate_none - Authenticates to an open control socket
authenticate_password - Authenticates to a socket supporting password auth
authenticate_cookie - Authenticates to a socket supporting cookie auth
authenticate_safecookie - Authenticates to a socket supporting safecookie auth

get_protocolinfo - Issues a PROTOCOLINFO query

AuthenticationFailure - Base exception raised for authentication failures
  |- UnrecognizedAuthMethods - Authentication methods are unsupported
  |- IncorrectSocketType - Socket does not speak the tor control protocol
  |
  |- OpenAuthFailed - Failure when authenticating by an open socket
  |  +- OpenAuthRejected - Tor rejected this method of authentication
  |
  |- PasswordAuthFailed - Failure when authenticating by a password
  |  |- PasswordAuthRejected - Tor rejected this method of authentication
  |  |- IncorrectPassword - Password was rejected
  |  +- MissingPassword - Socket supports password auth but wasn't attempted
  |
  |- CookieAuthFailed - Failure when authenticating by a cookie
  |  |- CookieAuthRejected - Tor rejected this method of authentication
  |  |- IncorrectCookieValue - Authentication cookie was rejected
  |  |- IncorrectCookieSize - Size of the cookie file is incorrect
  |  |- UnreadableCookieFile - Unable to read the contents of the auth cookie
  |  +- AuthChallengeFailed - Failure completing the authchallenge request
  |     |- AuthChallengeUnsupported - Tor doesn't recognize the AUTHCHALLENGE command
  |     |- AuthSecurityFailure - Server provided the wrong nonce credentials
  |     |- InvalidClientNonce - The client nonce is invalid
  |     +- UnrecognizedAuthChallengeMethod - AUTHCHALLENGE does not support the given methods.
  |
  +- MissingAuthInfo - Unexpected PROTOCOLINFO response, missing auth info
     |- NoAuthMethods - Missing any methods for authenticating
     +- NoAuthCookie - Supports cookie auth but doesn't have its path

stem.connection.AuthMethod(enum)¶

Enumeration of PROTOCOLINFO responses for supported authentication methods.

AuthMethod	Description
NONE	No authentication required.
PASSWORD	Password required, see tor’s HashedControlPassword option.
COOKIE	Contents of the cookie file required, see tor’s CookieAuthentication option.
SAFECOOKIE	Need to reply to a hmac challenge using the contents of the cookie file.
UNKNOWN	Tor provided one or more authentication methods that we don’t recognize, probably something new.

Stem Docs

Controller Connection

Controller Connection¶