Module hs_ntor 

Implements the HS ntor key exchange, as used in v3 onion services.

The Ntor protocol of this section is specified in section [NTOR-WITH-EXTRA-DATA] of rend-spec-v3.txt.

The main difference between this HS Ntor handshake and the regular Ntor handshake in ./ntor.rs is that this one allows each party to encrypt data (without forward secrecy) after it sends the first message. This opportunistic encryption property is used by clients in the onion service protocol to encrypt introduction data in the INTRODUCE1 cell, and by services to encrypt data in the RENDEZVOUS1 cell.

Status

This module is available only when the hs-common feature is enabled. The specific handshakes are enabled by hs-client and hs-service.

Structs

HsNtorClientState

Client state for an ntor handshake.

HsNtorHkdfKeyGenerator

The key generator used by the HS ntor handshake. Implements the simple key expansion protocol specified in section “Key expansion” of rend-spec-v3.txt .

HsNtorServiceInfo

Information about an onion service that is needed for a client to perform an hs_ntor handshake with it.

Constants

INTRO1_TARGET_LEN 🔒

Default target length for our generated Introduce1 messages.

Functions

encrypt_and_mac 🔒

Encrypt the ‘plaintext’ using ‘enc_key’. Then compute the intro cell MAC using ‘mac_key’ over the text (other_text, public_key, plaintext) and return (ciphertext, mac_tag).

get_introduce_key_material 🔒

Helper function: Compute the part of the HS ntor handshake that generates key material for creating and handling INTRODUCE1 cells. Function used by both client and service. Specifically, calculate the following:

get_rendezvous_key_material 🔒

Helper function: Compute the last part of the HS ntor handshake which derives key material necessary to create and handle RENDEZVOUS1 cells. Function used by both client and service. The actual calculations is as follows:

server_receive_intro

Conduct the HS Ntor handshake as the service.

server_receive_intro_no_keygen 🔒

Helper: Like server_receive_intro, but take an ephemeral key rather than a RNG.

Type Aliases

AuthInputMac 🔒

The AUTH_INPUT_MAC from the HS Ntor protocol

EncKey 🔒

The ENC_KEY from the HS Ntor protocol

MacKey 🔒

The MAC_KEY from the HS Ntor protocol

MacTag 🔒

A generic 256-bit MAC tag