hs_ntor.c File Reference

Implements the ntor variant used in Tor hidden services. More...

#include "or.h"
#include "crypto_util.h"
#include "hs_ntor.h"

Include dependency graph for hs_ntor.c:

Macros
#define	PROTOID   "tor-hs-ntor-curve25519-sha3-256-1"
#define	PROTOID_LEN   (sizeof(PROTOID) - 1)
#define	SERVER_STR   "Server"
#define	SERVER_STR_LEN   (sizeof(SERVER_STR) - 1)
#define	T_HSENC   PROTOID ":hs_key_extract"
#define	T_HSENC_LEN   (sizeof(T_HSENC) - 1)
#define	T_HSVERIFY   PROTOID ":hs_verify"
#define	T_HSMAC   PROTOID ":hs_mac"
#define	M_HSEXPAND   PROTOID ":hs_key_expand"
#define	M_HSEXPAND_LEN   (sizeof(M_HSEXPAND) - 1)
#define	APPEND(ptr, inp, len)
#define	REND_SECRET_HS_INPUT_LEN
#define	REND_AUTH_INPUT_LEN
#define	INTRO_SECRET_HS_INPUT_LEN
#define	INFO_BLOB_LEN   (M_HSEXPAND_LEN + DIGEST256_LEN)
#define	KDF_INPUT_LEN   (INTRO_SECRET_HS_INPUT_LEN + T_HSENC_LEN + INFO_BLOB_LEN)
#define	NTOR_KEY_EXPANSION_KDF_INPUT_LEN   (DIGEST256_LEN + M_HSEXPAND_LEN)

Functions
int	hs_ntor_client_get_introduce1_keys (const ed25519_public_key_t *intro_auth_pubkey, const curve25519_public_key_t *intro_enc_pubkey, const curve25519_keypair_t *client_ephemeral_enc_keypair, const uint8_t *subcredential, hs_ntor_intro_cell_keys_t *hs_ntor_intro_cell_keys_out)
int	hs_ntor_client_get_rendezvous1_keys (const ed25519_public_key_t *intro_auth_pubkey, const curve25519_keypair_t *client_ephemeral_enc_keypair, const curve25519_public_key_t *intro_enc_pubkey, const curve25519_public_key_t *service_ephemeral_rend_pubkey, hs_ntor_rend_cell_keys_t *hs_ntor_rend_cell_keys_out)
int	hs_ntor_service_get_introduce1_keys (const ed25519_public_key_t *intro_auth_pubkey, const curve25519_keypair_t *intro_enc_keypair, const curve25519_public_key_t *client_ephemeral_enc_pubkey, const uint8_t *subcredential, hs_ntor_intro_cell_keys_t *hs_ntor_intro_cell_keys_out)
int	hs_ntor_service_get_rendezvous1_keys (const ed25519_public_key_t *intro_auth_pubkey, const curve25519_keypair_t *intro_enc_keypair, const curve25519_keypair_t *service_ephemeral_rend_keypair, const curve25519_public_key_t *client_ephemeral_enc_pubkey, hs_ntor_rend_cell_keys_t *hs_ntor_rend_cell_keys_out)
int	hs_ntor_client_rendezvous2_mac_is_good (const hs_ntor_rend_cell_keys_t *hs_ntor_rend_cell_keys, const uint8_t *rcvd_mac)
int	hs_ntor_circuit_key_expansion (const uint8_t *ntor_key_seed, size_t seed_len, uint8_t *keys_out, size_t keys_out_len)

Detailed Description

Implements the ntor variant used in Tor hidden services.

This module handles the variant of the ntor handshake that is documented in section [NTOR-WITH-EXTRA-DATA] of rend-spec-ng.txt .

The functions in this file provide an API that should be used when sending or receiving INTRODUCE1/RENDEZVOUS1 cells to generate the various key material required to create and handle those cells.

In the case of INTRODUCE1 it provides encryption and MAC keys to encode/decode the encrypted blob (see hs_ntor_intro_cell_keys_t). The relevant pub functions are hs_ntor_{client,service}_get_introduce1_keys().

In the case of RENDEZVOUS1 it calculates the MAC required to authenticate the cell, and also provides the key seed that is used to derive the crypto material for rendezvous encryption (see hs_ntor_rend_cell_keys_t). The relevant pub functions are hs_ntor_{client,service}_get_rendezvous1_keys(). It also provides a function (hs_ntor_circuit_key_expansion()) that does the rendezvous key expansion to setup end-to-end rend circuit keys.

Macro Definition Documentation

APPEND

#define APPEND	(		ptr,
			inp,
			len
	)

Value:

STMT_BEGIN {                                  \
    memcpy(ptr, (inp), (len));                  \
    ptr += len;                                 \
  } STMT_END

Helper macro: copy len bytes from inp to ptr and advance ptr by the number of bytes copied. Stolen from onion_ntor.c

INTRO_SECRET_HS_INPUT_LEN

#define INTRO_SECRET_HS_INPUT_LEN

Value:

(CURVE25519_OUTPUT_LEN +ED25519_PUBKEY_LEN +\
  CURVE25519_PUBKEY_LEN + CURVE25519_PUBKEY_LEN + PROTOID_LEN)

Length of secret_input = EXP(B,x) | AUTH_KEY | X | B | PROTOID

REND_AUTH_INPUT_LEN

#define REND_AUTH_INPUT_LEN

Value:

(DIGEST256_LEN + ED25519_PUBKEY_LEN + \
  CURVE25519_PUBKEY_LEN * 3 + PROTOID_LEN + SERVER_STR_LEN)

REND_SECRET_HS_INPUT_LEN

#define REND_SECRET_HS_INPUT_LEN

Value:

(CURVE25519_OUTPUT_LEN * 2 + \
  ED25519_PUBKEY_LEN + CURVE25519_PUBKEY_LEN * 3 + PROTOID_LEN)

Function Documentation

hs_ntor_circuit_key_expansion()

int hs_ntor_circuit_key_expansion	(	const uint8_t *	ntor_key_seed,
		size_t	seed_len,
		uint8_t *	keys_out,
		size_t	keys_out_len
	)

Given the rendezvous key seed in ntor_key_seed (of size DIGEST256_LEN), do the circuit key expansion as specified by section '4.2.1. Key expansion' and place the keys in keys_out (which must be of size HS_NTOR_KEY_EXPANSION_KDF_OUT_LEN).

Return 0 if things went well, else return -1.

hs_ntor_client_rendezvous2_mac_is_good()

int hs_ntor_client_rendezvous2_mac_is_good	(	const hs_ntor_rend_cell_keys_t *	hs_ntor_rend_cell_keys,
		const uint8_t *	rcvd_mac
	)

Given a received RENDEZVOUS2 MAC in mac (of length DIGEST256_LEN), and the RENDEZVOUS1 key material in hs_ntor_rend_cell_keys, return 1 if the MAC is good, otherwise return 0.

Here is the call graph for this function: