leekspin.ntor

Functionality for creating and working with NTOR keys.

For a description of the NTOR handshake protocol, as well as its requisite keys, see §5.1.4 of tor-spec.txt, as well as the NTOR handshake proposal.

exception NTORKeyCreationError

Bases: exceptions.Exception

Raised when there was an error creating an NTOR key.

exception NTORPublicKeyError

Bases: exceptions.Exception

Raised when there is an error deriving the public Curve25519 key.

createNTORSecretKey()

Create a base64-encoded Curve25519 Salsa20-Poly1305 key.

See §5.1.4 of tor-spec.txt, as well as torspec.git/proposals/216-ntor-handshake.txt (specifically the “Integrating with the rest of Tor” section towards the end). For a full description of the Curve25519 keypair, see “Curve25519: new Diffie-Hellman speed records” by D.J. Bernstein.

Important

The subkey used in the NTOR handshake protocol should be generated via HKDF-SHA256 as defined in RFC 5869.

Raises:NTORKeyCreationError, if pynacl is not available or not installed, or if there was any other error while creating the key (such as an error due to having a different Python NaCl wrapper installed). Returns:The base64-encoded value of NTORKey, if available. The trailing newline of the base64 value is stripped (though not the padding, despite what proposals/216-ntor-handshake.txt says). Otherwise, returns None.

getNTORPublicKey(ntorSecretKey=None, base64=True)

Get the public key from the secret portion of a Curve25519 keypair.

The base64 version of the public Curve25519 key return from this function is suitable for use in a @type [bridge-]server-descriptor.

Todo

Remember to tell nickm to fix the description in his proposal about the ntor-onion-key padding removal.

Parameters:

• ntorSecretKey (nacl.public.PrivateKey) – A key created with createNTORSecretKey(). If not given, a new one will be created automatically.
• base64 (bool) – If True, return the base64-encoded NTOR public key (with trailing newline removed).

Raises:

NTORPublicKeyError if there was an error retrieving the public key.

Return type:

str or nacl.public.PublicKey or None

Returns:

The base64-encoded string version of the public portion of a Curve25519 keypair, if base64 is True, otherwise, returns the nacl.public.PublicKey. Returns None, if no ntorSecretKey was given and one could not be created.