Macros | Typedefs | Functions
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.


#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)


typedef struct ntor3_handshake_state_t ntor3_handshake_state_t
typedef struct ntor3_server_handshake_state_t ntor3_server_handshake_state_t


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)
struct ntor3_server_handshake_state_t ntor3_server_handshake_state_t
Definition: onion_ntor_v3.h:31
void ntor3_server_handshake_state_free_(ntor3_server_handshake_state_t *st)

Definition at line 37 of file onion_ntor_v3.h.

Typedef Documentation

◆ 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

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.