onion_fast.c File Reference

Functions implement the CREATE_FAST circuit handshake. More...

#include "core/or/or.h"
#include "core/crypto/onion_fast.h"
#include "lib/crypt_ops/crypto_hkdf.h"
#include "lib/crypt_ops/crypto_rand.h"
#include "lib/crypt_ops/crypto_util.h"

Go to the source code of this file.

Functions
void	fast_handshake_state_free_ (fast_handshake_state_t *victim)
int	fast_onionskin_create (fast_handshake_state_t **handshake_state_out, uint8_t *handshake_out)
int	fast_server_handshake (const uint8_t *key_in, uint8_t *handshake_reply_out, uint8_t *key_out, size_t key_out_len)
int	fast_client_handshake (const fast_handshake_state_t *handshake_state, const uint8_t *handshake_reply_out, uint8_t *key_out, size_t key_out_len, const char **msg_out)

Detailed Description

Functions implement the CREATE_FAST circuit handshake.

The "CREATE_FAST" handshake is an unauthenticated, non-forward-secure key derivation mechanism based on SHA1. We used to use it for the first hop of each circuit, since the TAP handshake provided no additional security beyond the security already provided by the TLS handshake [*].

When we switched to ntor, we deprecated CREATE_FAST, since ntor is stronger than our TLS handshake was, and fast enough to not be worrisome.

This handshake, like the other circuit-extension handshakes, is invoked from onion.c.

[*]Actually, it's possible that TAP was a little better than TLS with RSA1024 certificates and EDH1024 for forward secrecy, if you hypothesize an adversary who can compute discrete logarithms on a small number of targeted DH1024 fields, but who can't break all that many RSA1024 keys.

Definition in file onion_fast.c.

Function Documentation

fast_client_handshake()

int fast_client_handshake	(	const fast_handshake_state_t *	handshake_state,
		const uint8_t *	handshake_reply_out,
		uint8_t *	key_out,
		size_t	key_out_len,
		const char **	msg_out
	)

Implement the second half of the client side of the CREATE_FAST handshake. We sent the server handshake_state ("x") already, and the server told us handshake_reply_out (y|H(x|y)). Make sure that the hash is correct, and generate key material in key_out. Return 0 on success, true on failure.

NOTE: The "CREATE_FAST" handshake path is distinguishable from regular "onionskin" handshakes, and is not secure if an adversary can see or modify the messages. Therefore, it should only be used by clients, and only as the first hop of a circuit (since the first hop is already authenticated and protected by TLS).

Definition at line 109 of file onion_fast.c.

fast_handshake_state_free_()

void fast_handshake_state_free_

(

fast_handshake_state_t *

victim

)

Release all state held in victim.

Definition at line 38 of file onion_fast.c.

fast_onionskin_create()

int fast_onionskin_create	(	fast_handshake_state_t **	handshake_state_out,
		uint8_t *	handshake_out
	)

Create the state needed to perform a CREATE_FAST handshake. Return 0 on success, -1 on failure.

Definition at line 49 of file onion_fast.c.

fast_server_handshake()

int fast_server_handshake	(	const uint8_t *	key_in,
		uint8_t *	handshake_reply_out,
		uint8_t *	key_out,
		size_t	key_out_len
	)

Implement the server side of the CREATE_FAST abbreviated handshake. The client has provided DIGEST_LEN key bytes in key_in ("x"). We generate a reply of DIGEST_LEN*2 bytes in key_out, consisting of a new random "y", followed by H(x|y) to check for correctness. We set key_out_len bytes of key material in key_out. Return 0 on success, <0 on failure.

Definition at line 67 of file onion_fast.c.