onion_ntor_v3.h File Reference

Header for core/crypto/onion_ntor_v3.c. More...

#include "lib/cc/torint.h"
#include "lib/testsupport/testsupport.h"
#include "lib/crypt_ops/crypto_cipher.h"
#include "lib/crypt_ops/crypto_curve25519.h"
#include "lib/crypt_ops/crypto_ed25519.h"
#include "lib/malloc/malloc.h"

Go to the source code of this file.

Macros
#define	ntor3_handshake_state_free(ptr)    FREE_AND_NULL(ntor3_handshake_state_t, ntor3_handshake_state_free_, (ptr))
#define	ntor3_server_handshake_state_free(ptr)

Typedefs
typedef struct ntor3_handshake_state_t	ntor3_handshake_state_t
typedef struct ntor3_server_handshake_state_t	ntor3_server_handshake_state_t

Functions
void	ntor3_handshake_state_free_ (ntor3_handshake_state_t *st)
void	ntor3_server_handshake_state_free_ (ntor3_server_handshake_state_t *st)
int	onion_skin_ntor3_create (const ed25519_public_key_t *relay_id, const curve25519_public_key_t *relay_key, const uint8_t *verification, const size_t verification_len, const uint8_t *message, const size_t message_len, ntor3_handshake_state_t **handshake_state_out, uint8_t **onion_skin_out, size_t *onion_skin_len_out)
int	onion_ntor3_client_handshake (const ntor3_handshake_state_t *handshake_state, const uint8_t *handshake_reply, size_t reply_len, const uint8_t *verification, size_t verification_len, uint8_t *keys_out, size_t keys_out_len, uint8_t **message_out, size_t *message_len_out)
int	onion_skin_ntor3_server_handshake_part1 (const struct di_digest256_map_t *private_keys, const curve25519_keypair_t *junk_key, const ed25519_public_key_t *my_id, const uint8_t *client_handshake, size_t client_handshake_len, const uint8_t *verification, size_t verification_len, uint8_t **client_message_out, size_t *client_message_len_out, ntor3_server_handshake_state_t **state_out)
int	onion_skin_ntor3_server_handshake_part2 (const ntor3_server_handshake_state_t *state, const uint8_t *verification, size_t verification_len, const uint8_t *server_message, size_t server_message_len, uint8_t **handshake_out, size_t *handshake_len_out, uint8_t *keys_out, size_t keys_out_len)

Detailed Description

Header for core/crypto/onion_ntor_v3.c.

Definition in file onion_ntor_v3.h.

Macro Definition Documentation

ntor3_handshake_state_free

#define ntor3_handshake_state_free

(

ptr

)

FREE_AND_NULL(ntor3_handshake_state_t, ntor3_handshake_state_free_, (ptr))

Definition at line 34 of file onion_ntor_v3.h.

ntor3_server_handshake_state_free

#define ntor3_server_handshake_state_free

(

ptr

)

Value:

  FREE_AND_NULL(ntor3_server_handshake_state_t, \
                ntor3_server_handshake_state_free_, (ptr))

Definition at line 37 of file onion_ntor_v3.h.

Typedef Documentation

ntor3_handshake_state_t

typedef struct ntor3_handshake_state_t ntor3_handshake_state_t

Client-side state held while an ntor v3 handshake is in progress.

Definition at line 25 of file onion_ntor_v3.h.

ntor3_server_handshake_state_t

typedef struct ntor3_server_handshake_state_t ntor3_server_handshake_state_t

Server-side state held while the relay is handling a client's encapsulated message, before replying to the v3 handshake.

Definition at line 31 of file onion_ntor_v3.h.

Function Documentation

ntor3_handshake_state_free_()

void ntor3_handshake_state_free_

(

ntor3_handshake_state_t *

state

)

Helper: Drop storage held by state, after wiping it.

Definition at line 118 of file onion_ntor_v3.c.

ntor3_server_handshake_state_free_()

void ntor3_server_handshake_state_free_

(

ntor3_server_handshake_state_t *

state

)

Wipe a server handshake state, and release the storage it holds.

Definition at line 434 of file onion_ntor_v3.c.

onion_ntor3_client_handshake()

int onion_ntor3_client_handshake	(	const ntor3_handshake_state_t *	handshake_state,
		const uint8_t *	handshake_reply,
		size_t	reply_len,
		const uint8_t *	verification,
		size_t	verification_len,
		uint8_t *	keys_out,
		size_t	keys_out_len,
		uint8_t **	message_out,
		size_t *	message_len_out
	)

Complete a client-side v3 ntor handshake.

Takes a handshake_state returned earlier by onion_skin_ntor3_create(), and the relay's reply to that handshake (reply_len bytes at handshake_reply). Also takes a verification string (verification_len bytes at verification).

Returns 0 on success and -1 on failure. On success, generates key_len bytes of key material into the provided keys_out buffer, and sets message_out to the message that the relay sent in reply to our message (and sets message_out_len to that message's length).

Definition at line 298 of file onion_ntor_v3.c.

onion_skin_ntor3_create()

int onion_skin_ntor3_create	(	const ed25519_public_key_t *	relay_id,
		const curve25519_public_key_t *	relay_key,
		const uint8_t *	verification,
		const size_t	verification_len,
		const uint8_t *	message,
		const size_t	message_len,
		ntor3_handshake_state_t **	handshake_state_out,
		uint8_t **	onion_skin_out,
		size_t *	onion_skin_len_out
	)

Perform a client-side v3 ntor handshake with a given relay.

As inputs this function takes the relay's Ed25519 identity (relay_id), the relay's current ntor onion key (relay_key), a verification string (verification_len bytes at verification), and a message to send as part of the handshake (message_len bytes at message).

The message will be encrypted and authenticated to the relay, but will not receive the same forward secrecy as the rest of the handshake. We should not put any super-confidential data in it.

The handshake will only succeed if the relay uses the same verification string as we are using.

As outputs, this function returns 0 on success and -1 on failure. On success, it sets onion_skin_out and onion_skin_len_out to a newly allocated handshake message that the client can send as part of its CREATE2 or EXTEND2 cell. It also sets it sets handshake_state_out to a newly allocated handshake state object; the client needs to use this object to process the relay's eventual reply.

Definition at line 150 of file onion_ntor_v3.c.

onion_skin_ntor3_server_handshake_part2()

int onion_skin_ntor3_server_handshake_part2	(	const ntor3_server_handshake_state_t *	state,
		const uint8_t *	verification,
		size_t	verification_len,
		const uint8_t *	server_message,
		size_t	server_message_len,
		uint8_t **	handshake_out,
		size_t *	handshake_len_out,
		uint8_t *	keys_out,
		size_t	keys_out_len
	)

Finish the relay side of an ntor v3 handshake.

The relay calls this function after it has decided to respond to the client's original encrypted message. This function receives the relay's message in server_message and its length in server_message_len, and completes the handshake.

Returns 0 on success and -1 on failure. On success, stores the newly allocated handshake for the relay to send in handshake_out, and its length in handshake_len_out. Stores keys_out_len bytes of generated keys in the provided buffer at keys_out.

Definition at line 612 of file onion_ntor_v3.c.