Functions to handle different kinds of circuit extension crypto. More...

#include "core/or/or.h"
#include "core/or/extendinfo.h"
#include "core/crypto/onion_crypto.h"
#include "core/crypto/onion_fast.h"
#include "core/crypto/onion_ntor.h"
#include "core/crypto/onion_tap.h"
#include "feature/relay/router.h"
#include "lib/crypt_ops/crypto_dh.h"
#include "lib/crypt_ops/crypto_util.h"
#include "core/or/crypt_path_st.h"
#include "core/or/extend_info_st.h"

Macros
#define	MAX_KEYS_TMP_LEN 128

Functions
server_onion_keys_t *	server_onion_keys_new (void)

void	server_onion_keys_free_ (server_onion_keys_t *keys)

void	onion_handshake_state_release (onion_handshake_state_t *state)

int	onion_skin_create (int type, const extend_info_t node, onion_handshake_state_t state_out, uint8_t *onion_skin_out)

int	onion_skin_server_handshake (int type, const uint8_t onion_skin, size_t onionskin_len, const server_onion_keys_t keys, uint8_t reply_out, uint8_t keys_out, size_t keys_out_len, uint8_t *rend_nonce_out)

int	onion_skin_client_handshake (int type, const onion_handshake_state_t handshake_state, const uint8_t reply, size_t reply_len, uint8_t keys_out, size_t keys_out_len, uint8_t rend_authenticator_out, const char **msg_out)

Detailed Description

Functions to handle different kinds of circuit extension crypto.

In this module, we provide a set of abstractions to create a uniform interface over the three circuit extension handshakes that Tor has used over the years (TAP, CREATE_FAST, and ntor). These handshakes are implemented in onion_tap.c, onion_fast.c, and onion_ntor.c respectively.

All[*] of these handshakes follow a similar pattern: a client, knowing some key from the relay it wants to extend through, generates the first part of a handshake. A relay receives that handshake, and sends a reply. Once the client handles the reply, it knows that it is talking to the right relay, and it shares some freshly negotiated key material with that relay.

We sometimes call the client's part of the handshake an "onionskin". We do this because historically, Onion Routing used a multi-layer structure called an "onion" to construct circuits. Each layer of the onion contained key material chosen by the client, the identity of the next relay in the circuit, and a smaller onion, encrypted with the key of the next relay. When we changed Tor to use a telescoping circuit extension design, it corresponded to sending each layer of the onion separately – as a series of onionskins.

Definition in file onion_crypto.c.

Function Documentation

◆ onion_handshake_state_release()

void onion_handshake_state_release ( onion_handshake_state_t * state )

Release whatever storage is held in state, depending on its type, and clear its pointer.

Definition at line 79 of file onion_crypto.c.

Referenced by cpath_free().

◆ onion_skin_client_handshake()

int onion_skin_client_handshake	(	int	type,
		const onion_handshake_state_t *	handshake_state,
		const uint8_t *	reply,
		size_t	reply_len,
		uint8_t *	keys_out,
		size_t	keys_out_len,
		uint8_t *	rend_authenticator_out,
		const char **	msg_out
	)

Perform the final (client-side) step of a circuit-creation handshake of type type, using our state in handshake_state and the server's response in reply. On success, generate keys_out_len bytes worth of key material in keys_out_len, set rend_authenticator_out to the "KH" field that can be used to establish introduction points at this hop, and return 0. On failure, return -1, and set *msg_out to an error message if this is worth complaining to the user about.

Definition at line 247 of file onion_crypto.c.

◆ onion_skin_create()

int onion_skin_create	(	int	type,
		const extend_info_t *	node,
		onion_handshake_state_t *	state_out,
		uint8_t *	onion_skin_out
	)

Perform the first step of a circuit-creation handshake of type type (one of ONION_HANDSHAKE_TYPE_*): generate the initial "onion skin" in onion_skin_out, and store any state information in state_out. Return -1 on failure, and the length of the onionskin on acceptance.

Definition at line 110 of file onion_crypto.c.

◆ onion_skin_server_handshake()

int onion_skin_server_handshake	(	int	type,
		const uint8_t *	onion_skin,
		size_t	onionskin_len,
		const server_onion_keys_t *	keys,
		uint8_t *	reply_out,
		uint8_t *	keys_out,
		size_t	keys_out_len,
		uint8_t *	rend_nonce_out
	)

Perform the second (server-side) step of a circuit-creation handshake of type type, responding to the client request in onion_skin using the keys in keys. On success, write our response into reply_out, generate keys_out_len bytes worth of key material in keys_out_len, a hidden service nonce to rend_nonce_out, and return the length of the reply. On failure, return -1.

Definition at line 174 of file onion_crypto.c.

Referenced by cpuworker_onion_handshake_threadfn().

◆ server_onion_keys_free_()

void server_onion_keys_free_ ( server_onion_keys_t * keys )

Release all storage held in keys.

Definition at line 63 of file onion_crypto.c.

◆ server_onion_keys_new()

server_onion_keys_t* server_onion_keys_new ( void )

Return a new server_onion_keys_t object with all of the keys and other info we might need to do onion handshakes. (We make a copy of our keys for each cpuworker to avoid race conditions with the main thread, and to avoid locking)

Definition at line 51 of file onion_crypto.c.

Macros

Functions