an exception if all attempts to authenticate fail.

All exceptions are subclasses of AuthenticationFailure so, in practice,
callers should catch the types of authentication failure that they care
about, then have a :class:`~stem.connection.AuthenticationFailure` catch-all
at the end.

This can authenticate to either a :class:`~stem.control.BaseController` or
:class:`~stem.socket.ControlSocket`.

:param controller: tor controller or socket to be authenticated
:param str password: passphrase to present to the socket if it uses password
  authentication (skips password auth if **None**)
:param str chroot_path: path prefix if in a chroot environment
:param stem.response.protocolinfo.ProtocolInfoResponse protocolinfo_response:
  tor protocolinfo response, this is retrieved on our own if **None**

:raises: If all attempts to authenticate fails then this will raise a
  :class:`~stem.connection.AuthenticationFailure` subclass. Since this may
  try multiple authentication methods it may encounter multiple exceptions.
  If so then the exception this raises is prioritized as follows...

  * :class:`stem.connection.IncorrectSocketType`

    The controller does not speak the tor control protocol. Most often this
    happened because the user confused the SocksPort or ORPort with the
    ControlPort.

  * :class:`stem.connection.UnrecognizedAuthMethods`

    All of the authentication methods tor will accept are new and
    unrecognized. Please upgrade stem and, if that doesn't work, file a
    ticket on 'trac.torproject.org' and I'd be happy to add support.

  * :class:`stem.connection.MissingPassword`

    We were unable to authenticate but didn't attempt password authentication
    because none was provided. You should prompt the user for a password and
    try again via 'authenticate_password'.

  * :class:`stem.connection.IncorrectPassword`

    We were provided with a password but it was incorrect.

  * :class:`stem.connection.IncorrectCookieSize`

    Tor allows for authentication by reading it a cookie file, but that file
    is the wrong size to be an authentication cookie.

  * :class:`stem.connection.UnreadableCookieFile`

    Tor allows for authentication by reading it a cookie file, but we can't
    read that file (probably due to permissions).

  * **\***:class:`stem.connection.IncorrectCookieValue`

    Tor allows for authentication by reading it a cookie file, but rejected
    the contents of that file.

  * **\***:class:`stem.connection.AuthChallengeUnsupported`

    Tor doesn't recognize the AUTHCHALLENGE command. This is probably a Tor
    version prior to SAFECOOKIE being implement, but this exception shouldn't
    arise because we won't attempt SAFECOOKIE auth unless Tor claims to
    support it.

  * **\***:class:`stem.connection.UnrecognizedAuthChallengeMethod`

    Tor couldn't recognize the AUTHCHALLENGE method Stem sent to it. This
    shouldn't happen at all.

  * **\***:class:`stem.connection.InvalidClientNonce`

    Tor says that the client nonce provided by Stem during the AUTHCHALLENGE
    process is invalid.

  * **\***:class:`stem.connection.AuthSecurityFailure`

    Nonce value provided by the server was invalid.

  * **\***:class:`stem.connection.OpenAuthRejected`

    Tor says that it allows for authentication without any credentials, but
    then rejected our authentication attempt.

  * **\***:class:`stem.connection.MissingAuthInfo`

    Tor provided us with a PROTOCOLINFO reply that is technically valid, but
    missing the information we need to authenticate.

  * **\***:class:`stem.connection.AuthenticationFailure`

    There are numerous other ways that authentication could have failed
    including socket failures, malformed controller responses, etc. These
    mostly constitute transient failures or bugs.

  **\*** In practice it is highly unusual for this to occur, being more of a
  theoretical possibility rather than something you should expect. It's fine
  to treat these as errors. If you have a use case where this commonly
  happens, please file a ticket on 'trac.torproject.org'.

  In the future new :class:`~stem.connection.AuthenticationFailure`
  subclasses may be added to allow for better error handling.
z unable to use the control socketz