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