[tor-commits] [tor/master] hs_cell.[ch]: repair doxygen.

commit 3430b487d68a8af131e23fa417f7635e1cbaf3c8 Author: Nick Mathewson nickm@torproject.org Date: Wed Oct 16 12:08:38 2019 -0400

hs_cell.[ch]: repair doxygen. --- src/feature/hs/hs_cell.c | 50 ++++++++++++++++++++++++------------------------ src/feature/hs/hs_cell.h | 45 +++++++++++++++++++++---------------------- 2 files changed, 47 insertions(+), 48 deletions(-)

diff --git a/src/feature/hs/hs_cell.c b/src/feature/hs/hs_cell.c index d691a1b00..2d4a761eb 100644 --- a/src/feature/hs/hs_cell.c +++ b/src/feature/hs/hs_cell.c @@ -24,7 +24,7 @@ #include "trunnel/hs/cell_introduce1.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 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 @@ -67,7 +67,7 @@ compute_introduce_mac(const uint8_t *encoded_cell, size_t encoded_cell_len, 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. * Finally, the client public key is copied in client_pk. On error, return * NULL. */ @@ -101,7 +101,7 @@ get_introduce2_key_material(const ed25519_public_key_t *auth_key, 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 * buffer containing the decrypted data. On decryption failure, NULL is * returned. */ @@ -136,7 +136,7 @@ decrypt_introduce2(const uint8_t *enc_key, const uint8_t *encrypted_section, 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 * content. Return a newly allocated cell structure or NULL on error. The * circuit and service object are only used for logging purposes. */ @@ -188,7 +188,7 @@ parse_introduce2_encrypted(const uint8_t *decrypted_data, 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 * of the size of RELAY_PAYLOAD_SIZE. Return the encoded cell length on * 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; }

-/* 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 * parsed cell is put in cell_ptr_out. * @@ -249,7 +249,7 @@ parse_introduce2_cell(const hs_service_t *service, 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. */ static void 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)); }

-/* 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. */ static void 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)); }

-/* 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. */ static void 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. * * 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); }

-/* 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. */ static void 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); }

-/* 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 introduce1_set_auth_key(trn_cell_introduce1_t *cell, 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)); }

-/* 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 introduce1_set_legacy_id(trn_cell_introduce1_t *cell, 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. */ static void 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. */ }

-/* 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 * possible if there is a bug.) */ static int @@ -563,7 +563,7 @@ build_establish_intro_dos_extension(const hs_service_config_t *service_config, /* 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. */ STATIC trn_cell_extension_t * 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; }

-/* 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 * 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 @@ -720,7 +720,7 @@ hs_cell_build_establish_intro(const char *circ_nonce, 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 * negative value on error. */ ssize_t @@ -742,7 +742,7 @@ hs_cell_parse_intro_established(const uint8_t *payload, size_t payload_len) 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 * compute from the cell. Return 0 on success else a negative value. The * 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; }

-/* 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 * returned. This can't fail. */ ssize_t @@ -937,7 +937,7 @@ hs_cell_build_rendezvous1(const uint8_t *rendezvous_cookie, 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 * encoded length is returned else a negative value and the content of * cell_out should be ignored. */ @@ -978,7 +978,7 @@ hs_cell_build_introduce1(const hs_cell_introduce1_data_t *data, 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 * RELAY_PAYLOAD_SIZE. On success, the encoded length is returned and the * 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; }

-/* 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 * decodable. */ int @@ -1030,7 +1030,7 @@ hs_cell_parse_introduce_ack(const uint8_t *payload, size_t payload_len) 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 * 0 is returned. On error, a negative value is returned. */ int @@ -1062,7 +1062,7 @@ hs_cell_parse_rendezvous2(const uint8_t *payload, size_t payload_len, return ret; }

-/* Clear the given INTRODUCE1 data structure data. */ +/** Clear the given INTRODUCE1 data structure data. */ void hs_cell_introduce1_data_clear(hs_cell_introduce1_data_t *data) { diff --git a/src/feature/hs/hs_cell.h b/src/feature/hs/hs_cell.h index 864b6fda5..5ee434794 100644 --- a/src/feature/hs/hs_cell.h +++ b/src/feature/hs/hs_cell.h @@ -12,35 +12,35 @@ #include "core/or/or.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. */ #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. */ typedef struct hs_cell_introduce1_data_t { - /* Is this a legacy introduction point? */ + /** Is this a legacy introduction point? */ 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. */ const crypto_pk_t *legacy_key; - /* Introduction point authentication public key. */ + /** Introduction point authentication public key. */ const ed25519_public_key_t *auth_pk; - /* Introduction point encryption public key. */ + /** Introduction point encryption public key. */ const curve25519_public_key_t *enc_pk; - /* Subcredentials of the service. */ + /** Subcredentials of the service. */ 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; - /* Rendezvous cookie. */ + /** 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; - /* Rendezvous point link specifiers. */ + /** Rendezvous point link specifiers. */ smartlist_t *link_specifiers; } 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 * 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 @@ -48,32 +48,32 @@ typedef struct hs_cell_introduce1_data_t { typedef struct hs_cell_introduce2_data_t { /*** 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. */ 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 INTRO2 cell*/ 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. */ const uint8_t *subcredential; - /* Payload of the received encoded cell. */ + /** Payload of the received encoded cell. */ 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;

/*** 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; - /* Rendezvous cookie taken from the INTRODUCE2 encrypted section. */ + /** Rendezvous cookie taken from the INTRODUCE2 encrypted section. */ 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; - /* Link specifiers of the rendezvous point. Contains link_specifier_t. */ + /** Link specifiers of the rendezvous point. Contains link_specifier_t. */ smartlist_t *link_specifiers; - /* Replay cache of the introduction point. */ + /** Replay cache of the introduction point. */ replaycache_t *replay_cache; } 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_HS_CELL_H) */ -