02. Authentication

First off, there are roughly three commands you can use without being authenticated. You can either authenticate(), protocol_info() or quit().

Authentication methods

Controller.protocol_info(), when successful provides a ReplyProtocolInfo, which contains important authentication information, such as the list of authorized authentication methods and the path to the cookie file used in most of these authentication methods.

Configuration for authentication methods is quite out of our scope here, but feel free to take a look at the torrc manpage, especially options HashedControlPassword and CookieAuthentication. Password hash can be generated with the following command:

$ tor --hash-password aiostem
16:431FE41EE9A6D2D8600C0F92F71A03D0A8C4E40EC1BBCC84716C95F022

The following code can be used to list available authentication methods for the target Tor daemon, and the cookie file used for COOKIE and SAFECOOKIE. It uses Controller.protocol_info() to get this information.

The full list of known authentication methods is documented on AuthMethod.

examples/authentication_listing.py

#!/usr/bin/env python

import asyncio
import os
from aiostem import Controller

async def main():
    host = os.environ.get('AIOSTEM_HOST', 'localhost')
    port = os.environ.get('AIOSTEM_PORT', 9051)

    print(f'[>] Connecting to {host} on port {port}')
    async with Controller.from_port(host, int(port)) as ctrl:
        reply = await ctrl.protocol_info()
        reply.raise_for_status()

        print('[+] List of allowed authentication methods:')
        for method in reply.data.auth_methods:
            print(f' * {method}')
        if reply.data.auth_cookie_file is not None:
            print(f'[+] Path to the cookie file: {reply.data.auth_cookie_file}')

if __name__ == '__main__':
    asyncio.run(main())

Note here that we use raise_for_status() here to ensure that the command was successful before we go on with ReplyProtocolInfo.data.

This code, when executed provides an output such as follows:

$ python examples/authentication_listing.py
[>] Connecting to localhost on port 9051
[+] List of allowed authentication methods:
 * COOKIE
 * SAFECOOKIE
 * HASHEDPASSWORD
[+] Path to the cookie file: /run/tor/control.authcookie

Password authentication

This method covers AuthMethod.HASHEDPASSWORD and is the one related to HashedControlPassword from the configuration file. This is the only secure available method when dealing with Tor running on a remote host.

The following code authenticates with a password using Controller.authenticate():

examples/authenticate_with_password.py

#!/usr/bin/env python

import asyncio
import os
from aiostem import Controller

async def main():
    password = os.environ.get('AIOSTEM_PASS', 'password')
    host = os.environ.get('AIOSTEM_HOST', 'localhost')
    port = os.environ.get('AIOSTEM_PORT', 9051)

    print(f'[>] Connecting to {host} on port {port}')
    async with Controller.from_port(host, int(port)) as ctrl:
        reply = await ctrl.authenticate(password)
        reply.raise_for_status()

        print('[+] Authentication successful!')

if __name__ == '__main__':
    asyncio.run(main())

You can set the password directly from the environment:

$ AIOSTEM_PASS=aiostem python examples/authenticate_with_password.py
[>] Connecting to localhost on port 9051
[+] Authentication successful!

You can also check that when a wrong password is supplied, raise_for_status() raises a ReplyStatusError error with a meaningful message (provided by Tor).

Cookie file authentication

Controller.authenticate() does more under the hood. First it calls Controller.protocol_info() and get the list of available authentication methods.

Then, depending on the available methods, its behavior changes:

• When NULL is available, it does the authentication by itself.

• When a password is supplied and HASHEDPASSWORD is available, a password authentication is performed and the password is transmitted in clear-text.

• Otherwise, it first tries SAFECOOKIE if available, or COOKIE.

COOKIE is a simple proof that we can read the file located at ReplyDataProtocolInfo.auth_cookie_file, by transmitting its content.

SAFECOOKIE uses a HMAC so we can provide a proof that we have read the file content without transmitting the content itself. For this to work, authenticate() calls auth_challenge() under the hood with a random nonce generated using secrets.token_bytes(). The server hash is then checked using ReplyDataAuthChallenge.raise_for_server_hash_error and eventually client authentication is performed.

In the end, any password-less authentication can be performed with the following code:

examples/authenticate_without_password.py

#!/usr/bin/env python

import asyncio
import os
from aiostem import Controller

async def main():
    host = os.environ.get('AIOSTEM_HOST', 'localhost')
    port = os.environ.get('AIOSTEM_PORT', 9051)

    print(f'[>] Connecting to {host} on port {port}')
    async with Controller.from_port(host, int(port)) as ctrl:
        reply = await ctrl.authenticate()
        reply.raise_for_status()

        print('[+] Authentication successful!')

if __name__ == '__main__':
    asyncio.run(main())

Note that your user obviously requires the proper permissions to read the cookie file. You can use a group-readable cookie file using CookieAuthFileGroupReadable in torrc.