# Stem Docs

## 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.