nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-30 23:53:32 +01:00
Code Issues Packages Projects Releases Wiki Activity

hs_cell.[ch]: repair doxygen.

Browse Source
This commit is contained in:
Nick Mathewson 2019-10-16 12:08:38 -04:00
parent 6a2057a9f2
commit 3430b487d6
2 changed files with 47 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
src/feature/hs/hs_cell.c
View File

@ -24,7 +24,7 @@
#include "trunnel/hs/cell_introduce1.h" #include "trunnel/hs/cell_introduce1.h"
#include "trunnel/hs/cell_rendezvous.h" #include "trunnel/hs/cell_rendezvous.h"
/* Compute the MAC of an INTRODUCE cell in mac_out. The encoded_cell param is /** Compute the MAC of an INTRODUCE cell in mac_out. The encoded_cell param is
* the cell content up to the ENCRYPTED section of length encoded_cell_len. * the cell content up to the ENCRYPTED section of length encoded_cell_len.
* The encrypted param is the start of the ENCRYPTED section of length * The encrypted param is the start of the ENCRYPTED section of length
* encrypted_len. The mac_key is the key needed for the computation of the MAC * encrypted_len. The mac_key is the key needed for the computation of the MAC
@ -67,7 +67,7 @@ compute_introduce_mac(const uint8_t *encoded_cell, size_t encoded_cell_len,
memwipe(mac_msg, 0, sizeof(mac_msg)); memwipe(mac_msg, 0, sizeof(mac_msg));
} }
/* From a set of keys, subcredential and the ENCRYPTED section of an /** From a set of keys, subcredential and the ENCRYPTED section of an
* INTRODUCE2 cell, return a newly allocated intro cell keys structure. * INTRODUCE2 cell, return a newly allocated intro cell keys structure.
* Finally, the client public key is copied in client_pk. On error, return * Finally, the client public key is copied in client_pk. On error, return
* NULL. */ * NULL. */
@ -101,7 +101,7 @@ get_introduce2_key_material(const ed25519_public_key_t *auth_key,
return keys; return keys;
} }
/* Using the given encryption key, decrypt the encrypted_section of length /** Using the given encryption key, decrypt the encrypted_section of length
* encrypted_section_len of an INTRODUCE2 cell and return a newly allocated * encrypted_section_len of an INTRODUCE2 cell and return a newly allocated
* buffer containing the decrypted data. On decryption failure, NULL is * buffer containing the decrypted data. On decryption failure, NULL is
* returned. */ * returned. */
@ -136,7 +136,7 @@ decrypt_introduce2(const uint8_t *enc_key, const uint8_t *encrypted_section,
return decrypted; return decrypted;
} }
/* Given a pointer to the decrypted data of the ENCRYPTED section of an /** Given a pointer to the decrypted data of the ENCRYPTED section of an
* INTRODUCE2 cell of length decrypted_len, parse and validate the cell * INTRODUCE2 cell of length decrypted_len, parse and validate the cell
* content. Return a newly allocated cell structure or NULL on error. The * content. Return a newly allocated cell structure or NULL on error. The
* circuit and service object are only used for logging purposes. */ * circuit and service object are only used for logging purposes. */
@ -188,7 +188,7 @@ parse_introduce2_encrypted(const uint8_t *decrypted_data,
return NULL; return NULL;
} }
/* Build a legacy ESTABLISH_INTRO cell with the given circuit nonce and RSA /** Build a legacy ESTABLISH_INTRO cell with the given circuit nonce and RSA
* encryption key. The encoded cell is put in cell_out that MUST at least be * encryption key. The encoded cell is put in cell_out that MUST at least be
* of the size of RELAY_PAYLOAD_SIZE. Return the encoded cell length on * of the size of RELAY_PAYLOAD_SIZE. Return the encoded cell length on
* success else a negative value and cell_out is untouched. */ * success else a negative value and cell_out is untouched. */
@ -210,7 +210,7 @@ build_legacy_establish_intro(const char *circ_nonce, crypto_pk_t *enc_key,
return cell_len; return cell_len;
} }
/* Parse an INTRODUCE2 cell from payload of size payload_len for the given /** Parse an INTRODUCE2 cell from payload of size payload_len for the given
* service and circuit which are used only for logging purposes. The resulting * service and circuit which are used only for logging purposes. The resulting
* parsed cell is put in cell_ptr_out. * parsed cell is put in cell_ptr_out.
* *
@ -249,7 +249,7 @@ parse_introduce2_cell(const hs_service_t *service,
return -1; return -1;
} }
/* Set the onion public key onion_pk in cell, the encrypted section of an /** Set the onion public key onion_pk in cell, the encrypted section of an
* INTRODUCE1 cell. */ * INTRODUCE1 cell. */
static void static void
introduce1_set_encrypted_onion_key(trn_cell_introduce_encrypted_t *cell, introduce1_set_encrypted_onion_key(trn_cell_introduce_encrypted_t *cell,
@ -266,7 +266,7 @@ introduce1_set_encrypted_onion_key(trn_cell_introduce_encrypted_t *cell,
trn_cell_introduce_encrypted_getlen_onion_key(cell)); trn_cell_introduce_encrypted_getlen_onion_key(cell));
} }
/* Set the link specifiers in lspecs in cell, the encrypted section of an /** Set the link specifiers in lspecs in cell, the encrypted section of an
* INTRODUCE1 cell. */ * INTRODUCE1 cell. */
static void static void
introduce1_set_encrypted_link_spec(trn_cell_introduce_encrypted_t *cell, introduce1_set_encrypted_link_spec(trn_cell_introduce_encrypted_t *cell,
@ -286,7 +286,7 @@ introduce1_set_encrypted_link_spec(trn_cell_introduce_encrypted_t *cell,
trn_cell_introduce_encrypted_add_nspecs(cell, ls)); trn_cell_introduce_encrypted_add_nspecs(cell, ls));
} }
/* Set padding in the enc_cell only if needed that is the total length of both /** Set padding in the enc_cell only if needed that is the total length of both
* sections are below the mininum required for an INTRODUCE1 cell. */ * sections are below the mininum required for an INTRODUCE1 cell. */
static void static void
introduce1_set_encrypted_padding(const trn_cell_introduce1_t *cell, introduce1_set_encrypted_padding(const trn_cell_introduce1_t *cell,
@ -306,7 +306,7 @@ introduce1_set_encrypted_padding(const trn_cell_introduce1_t *cell,
} }
} }
/* Encrypt the ENCRYPTED payload and encode it in the cell using the enc_cell /** Encrypt the ENCRYPTED payload and encode it in the cell using the enc_cell
* and the INTRODUCE1 data. * and the INTRODUCE1 data.
* *
* This can't fail but it is very important that the caller sets every field * This can't fail but it is very important that the caller sets every field
@ -394,7 +394,7 @@ introduce1_encrypt_and_encode(trn_cell_introduce1_t *cell,
tor_free(encrypted); tor_free(encrypted);
} }
/* Using the INTRODUCE1 data, setup the ENCRYPTED section in cell. This means /** Using the INTRODUCE1 data, setup the ENCRYPTED section in cell. This means
* set it, encrypt it and encode it. */ * set it, encrypt it and encode it. */
static void static void
introduce1_set_encrypted(trn_cell_introduce1_t *cell, introduce1_set_encrypted(trn_cell_introduce1_t *cell,
@ -435,7 +435,7 @@ introduce1_set_encrypted(trn_cell_introduce1_t *cell,
trn_cell_introduce_encrypted_free(enc_cell); trn_cell_introduce_encrypted_free(enc_cell);
} }
/* Set the authentication key in the INTRODUCE1 cell from the given data. */ /** Set the authentication key in the INTRODUCE1 cell from the given data. */
static void static void
introduce1_set_auth_key(trn_cell_introduce1_t *cell, introduce1_set_auth_key(trn_cell_introduce1_t *cell,
const hs_cell_introduce1_data_t *data) const hs_cell_introduce1_data_t *data)
@ -451,7 +451,7 @@ introduce1_set_auth_key(trn_cell_introduce1_t *cell,
data->auth_pk->pubkey, trn_cell_introduce1_getlen_auth_key(cell)); data->auth_pk->pubkey, trn_cell_introduce1_getlen_auth_key(cell));
} }
/* Set the legacy ID field in the INTRODUCE1 cell from the given data. */ /** Set the legacy ID field in the INTRODUCE1 cell from the given data. */
static void static void
introduce1_set_legacy_id(trn_cell_introduce1_t *cell, introduce1_set_legacy_id(trn_cell_introduce1_t *cell,
const hs_cell_introduce1_data_t *data) const hs_cell_introduce1_data_t *data)
@ -473,7 +473,7 @@ introduce1_set_legacy_id(trn_cell_introduce1_t *cell,
} }
} }
/* Build and add to the given DoS cell extension the given parameter type and /** Build and add to the given DoS cell extension the given parameter type and
* value. */ * value. */
static void static void
build_establish_intro_dos_param(trn_cell_extension_dos_t *dos_ext, build_establish_intro_dos_param(trn_cell_extension_dos_t *dos_ext,
@ -493,7 +493,7 @@ build_establish_intro_dos_param(trn_cell_extension_dos_t *dos_ext,
/* Not freeing the trunnel object because it is now owned by dos_ext. */ /* Not freeing the trunnel object because it is now owned by dos_ext. */
} }
/* Build the DoS defense cell extension and put it in the given extensions /** Build the DoS defense cell extension and put it in the given extensions
* object. Return 0 on success, -1 on failure. (Right now, failure is only * object. Return 0 on success, -1 on failure. (Right now, failure is only
* possible if there is a bug.) */ * possible if there is a bug.) */
static int static int
@ -563,7 +563,7 @@ build_establish_intro_dos_extension(const hs_service_config_t *service_config,
/* Public API */ /* Public API */
/* ========== */ /* ========== */
/* Allocate and build all the ESTABLISH_INTRO cell extension. The given /** Allocate and build all the ESTABLISH_INTRO cell extension. The given
* extensions pointer is always set to a valid cell extension object. */ * extensions pointer is always set to a valid cell extension object. */
STATIC trn_cell_extension_t * STATIC trn_cell_extension_t *
build_establish_intro_extensions(const hs_service_config_t *service_config, build_establish_intro_extensions(const hs_service_config_t *service_config,
@ -594,7 +594,7 @@ build_establish_intro_extensions(const hs_service_config_t *service_config,
return extensions; return extensions;
} }
/* Build an ESTABLISH_INTRO cell with the given circuit nonce and intro point /** Build an ESTABLISH_INTRO cell with the given circuit nonce and intro point
* object. The encoded cell is put in cell_out that MUST at least be of the * object. The encoded cell is put in cell_out that MUST at least be of the
* size of RELAY_PAYLOAD_SIZE. Return the encoded cell length on success else * size of RELAY_PAYLOAD_SIZE. Return the encoded cell length on success else
* a negative value and cell_out is untouched. This function also supports * a negative value and cell_out is untouched. This function also supports
@ -720,7 +720,7 @@ hs_cell_build_establish_intro(const char *circ_nonce,
return cell_len; return cell_len;
} }
/* Parse the INTRO_ESTABLISHED cell in the payload of size payload_len. If we /** Parse the INTRO_ESTABLISHED cell in the payload of size payload_len. If we
* are successful at parsing it, return the length of the parsed cell else a * are successful at parsing it, return the length of the parsed cell else a
* negative value on error. */ * negative value on error. */
ssize_t ssize_t
@ -742,7 +742,7 @@ hs_cell_parse_intro_established(const uint8_t *payload, size_t payload_len)
return ret; return ret;
} }
/* Parse the INTRODUCE2 cell using data which contains everything we need to /** Parse the INTRODUCE2 cell using data which contains everything we need to
* do so and contains the destination buffers of information we extract and * do so and contains the destination buffers of information we extract and
* compute from the cell. Return 0 on success else a negative value. The * compute from the cell. Return 0 on success else a negative value. The
* service and circ are only used for logging purposes. */ * service and circ are only used for logging purposes. */
@ -903,7 +903,7 @@ hs_cell_parse_introduce2(hs_cell_introduce2_data_t *data,
return ret; return ret;
} }
/* Build a RENDEZVOUS1 cell with the given rendezvous cookie and handshake /** Build a RENDEZVOUS1 cell with the given rendezvous cookie and handshake
* info. The encoded cell is put in cell_out and the length of the data is * info. The encoded cell is put in cell_out and the length of the data is
* returned. This can't fail. */ * returned. This can't fail. */
ssize_t ssize_t
@ -937,7 +937,7 @@ hs_cell_build_rendezvous1(const uint8_t *rendezvous_cookie,
return cell_len; return cell_len;
} }
/* Build an INTRODUCE1 cell from the given data. The encoded cell is put in /** Build an INTRODUCE1 cell from the given data. The encoded cell is put in
* cell_out which must be of at least size RELAY_PAYLOAD_SIZE. On success, the * cell_out which must be of at least size RELAY_PAYLOAD_SIZE. On success, the
* encoded length is returned else a negative value and the content of * encoded length is returned else a negative value and the content of
* cell_out should be ignored. */ * cell_out should be ignored. */
@ -978,7 +978,7 @@ hs_cell_build_introduce1(const hs_cell_introduce1_data_t *data,
return cell_len; return cell_len;
} }
/* Build an ESTABLISH_RENDEZVOUS cell from the given rendezvous_cookie. The /** Build an ESTABLISH_RENDEZVOUS cell from the given rendezvous_cookie. The
* encoded cell is put in cell_out which must be of at least * encoded cell is put in cell_out which must be of at least
* RELAY_PAYLOAD_SIZE. On success, the encoded length is returned and the * RELAY_PAYLOAD_SIZE. On success, the encoded length is returned and the
* caller should clear up the content of the cell. * caller should clear up the content of the cell.
@ -995,7 +995,7 @@ hs_cell_build_establish_rendezvous(const uint8_t *rendezvous_cookie,
return HS_REND_COOKIE_LEN; return HS_REND_COOKIE_LEN;
} }
/* Handle an INTRODUCE_ACK cell encoded in payload of length payload_len. /** Handle an INTRODUCE_ACK cell encoded in payload of length payload_len.
* Return the status code on success else a negative value if the cell as not * Return the status code on success else a negative value if the cell as not
* decodable. */ * decodable. */
int int
@ -1030,7 +1030,7 @@ hs_cell_parse_introduce_ack(const uint8_t *payload, size_t payload_len)
return ret; return ret;
} }
/* Handle a RENDEZVOUS2 cell encoded in payload of length payload_len. On /** Handle a RENDEZVOUS2 cell encoded in payload of length payload_len. On
* success, handshake_info contains the data in the HANDSHAKE_INFO field, and * success, handshake_info contains the data in the HANDSHAKE_INFO field, and
* 0 is returned. On error, a negative value is returned. */ * 0 is returned. On error, a negative value is returned. */
int int
@ -1062,7 +1062,7 @@ hs_cell_parse_rendezvous2(const uint8_t *payload, size_t payload_len,
return ret; return ret;
} }
/* Clear the given INTRODUCE1 data structure data. */ /** Clear the given INTRODUCE1 data structure data. */
void void
hs_cell_introduce1_data_clear(hs_cell_introduce1_data_t *data) hs_cell_introduce1_data_clear(hs_cell_introduce1_data_t *data)
{ {

45
src/feature/hs/hs_cell.h
View File

@ -12,35 +12,35 @@
#include "core/or/or.h" #include "core/or/or.h"
#include "feature/hs/hs_service.h" #include "feature/hs/hs_service.h"
/* An INTRODUCE1 cell requires at least this amount of bytes (see section /** An INTRODUCE1 cell requires at least this amount of bytes (see section
* 3.2.2 of the specification). Below this value, the cell must be padded. */ * 3.2.2 of the specification). Below this value, the cell must be padded. */
#define HS_CELL_INTRODUCE1_MIN_SIZE 246 #define HS_CELL_INTRODUCE1_MIN_SIZE 246
/* This data structure contains data that we need to build an INTRODUCE1 cell /** This data structure contains data that we need to build an INTRODUCE1 cell
* used by the INTRODUCE1 build function. */ * used by the INTRODUCE1 build function. */
typedef struct hs_cell_introduce1_data_t { typedef struct hs_cell_introduce1_data_t {
/* Is this a legacy introduction point? */ /** Is this a legacy introduction point? */
unsigned int is_legacy : 1; unsigned int is_legacy : 1;
/* (Legacy only) The encryption key for a legacy intro point. Only set if /** (Legacy only) The encryption key for a legacy intro point. Only set if
* is_legacy is true. */ * is_legacy is true. */
const crypto_pk_t *legacy_key; const crypto_pk_t *legacy_key;
/* Introduction point authentication public key. */ /** Introduction point authentication public key. */
const ed25519_public_key_t *auth_pk; const ed25519_public_key_t *auth_pk;
/* Introduction point encryption public key. */ /** Introduction point encryption public key. */
const curve25519_public_key_t *enc_pk; const curve25519_public_key_t *enc_pk;
/* Subcredentials of the service. */ /** Subcredentials of the service. */
const uint8_t *subcredential; const uint8_t *subcredential;
/* Onion public key for the ntor handshake. */ /** Onion public key for the ntor handshake. */
const curve25519_public_key_t *onion_pk; const curve25519_public_key_t *onion_pk;
/* Rendezvous cookie. */ /** Rendezvous cookie. */
const uint8_t *rendezvous_cookie; const uint8_t *rendezvous_cookie;
/* Public key put before the encrypted data (CLIENT_PK). */ /** Public key put before the encrypted data (CLIENT_PK). */
const curve25519_keypair_t *client_kp; const curve25519_keypair_t *client_kp;
/* Rendezvous point link specifiers. */ /** Rendezvous point link specifiers. */
smartlist_t *link_specifiers; smartlist_t *link_specifiers;
} hs_cell_introduce1_data_t; } hs_cell_introduce1_data_t;
/* This data structure contains data that we need to parse an INTRODUCE2 cell /** This data structure contains data that we need to parse an INTRODUCE2 cell
* which is used by the INTRODUCE2 cell parsing function. On a successful * which is used by the INTRODUCE2 cell parsing function. On a successful
* parsing, the onion_pk and rendezvous_cookie will be populated with the * parsing, the onion_pk and rendezvous_cookie will be populated with the
* computed key material from the cell data. This structure is only used during * computed key material from the cell data. This structure is only used during
@ -48,32 +48,32 @@ typedef struct hs_cell_introduce1_data_t {
typedef struct hs_cell_introduce2_data_t { typedef struct hs_cell_introduce2_data_t {
/*** Immutable Section: Set on structure init. ***/ /*** Immutable Section: Set on structure init. ***/
/* Introduction point authentication public key. Pointer owned by the /** Introduction point authentication public key. Pointer owned by the
introduction point object through which we received the INTRO2 cell. */ introduction point object through which we received the INTRO2 cell. */
const ed25519_public_key_t *auth_pk; const ed25519_public_key_t *auth_pk;
/* Introduction point encryption keypair for the ntor handshake. Pointer /** Introduction point encryption keypair for the ntor handshake. Pointer
owned by the introduction point object through which we received the owned by the introduction point object through which we received the
INTRO2 cell*/ INTRO2 cell*/
const curve25519_keypair_t *enc_kp; const curve25519_keypair_t *enc_kp;
/* Subcredentials of the service. Pointer owned by the descriptor that owns /** Subcredentials of the service. Pointer owned by the descriptor that owns
the introduction point through which we received the INTRO2 cell. */ the introduction point through which we received the INTRO2 cell. */
const uint8_t *subcredential; const uint8_t *subcredential;
/* Payload of the received encoded cell. */ /** Payload of the received encoded cell. */
const uint8_t *payload; const uint8_t *payload;
/* Size of the payload of the received encoded cell. */ /** Size of the payload of the received encoded cell. */
size_t payload_len; size_t payload_len;
/*** Mutable Section: Set upon parsing INTRODUCE2 cell. ***/ /*** Mutable Section: Set upon parsing INTRODUCE2 cell. ***/
/* Onion public key computed using the INTRODUCE2 encrypted section. */ /** Onion public key computed using the INTRODUCE2 encrypted section. */
curve25519_public_key_t onion_pk; curve25519_public_key_t onion_pk;
/* Rendezvous cookie taken from the INTRODUCE2 encrypted section. */ /** Rendezvous cookie taken from the INTRODUCE2 encrypted section. */
uint8_t rendezvous_cookie[REND_COOKIE_LEN]; uint8_t rendezvous_cookie[REND_COOKIE_LEN];
/* Client public key from the INTRODUCE2 encrypted section. */ /** Client public key from the INTRODUCE2 encrypted section. */
curve25519_public_key_t client_pk; curve25519_public_key_t client_pk;
/* Link specifiers of the rendezvous point. Contains link_specifier_t. */ /** Link specifiers of the rendezvous point. Contains link_specifier_t. */
smartlist_t *link_specifiers; smartlist_t *link_specifiers;
/* Replay cache of the introduction point. */ /** Replay cache of the introduction point. */
replaycache_t *replay_cache; replaycache_t *replay_cache;
} hs_cell_introduce2_data_t; } hs_cell_introduce2_data_t;
@ -117,4 +117,3 @@ build_establish_intro_extensions(const hs_service_config_t *service_config,
#endif /* defined(TOR_UNIT_TESTS) */ #endif /* defined(TOR_UNIT_TESTS) */
#endif /* !defined(TOR_HS_CELL_H) */ #endif /* !defined(TOR_HS_CELL_H) */