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

hs_descriptor.[ch]: repair doxygen comments.

Browse Source 
These are yet more that were not made with "/**"
This commit is contained in:
Nick Mathewson 2019-10-16 11:33:03 -04:00
parent ca26ea03fc
commit 2127d797e9
2 changed files with 123 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
src/feature/hs/hs_descriptor.c
View File

@ -102,7 +102,7 @@
#define str_desc_auth_client "auth-client"
#define str_encrypted "encrypted"
/* Authentication supported types. */
/** Authentication supported types. */
static const struct {
hs_desc_auth_type_t type;
const char *identifier;
@ -112,7 +112,7 @@ static const struct {
{ 0, NULL }
};
/* Descriptor ruleset. */
/** Descriptor ruleset. */
static token_rule_t hs_desc_v3_token_table[] = {
T1_START(str_hs_desc, R_HS_DESCRIPTOR, EQ(1), NO_OBJ),
T1(str_lifetime, R3_DESC_LIFETIME, EQ(1), NO_OBJ),
@ -123,7 +123,7 @@ static token_rule_t hs_desc_v3_token_table[] = {
END_OF_TABLE
};
/* Descriptor ruleset for the superencrypted section. */
/** Descriptor ruleset for the superencrypted section. */
static token_rule_t hs_desc_superencrypted_v3_token_table[] = {
T1_START(str_desc_auth_type, R3_DESC_AUTH_TYPE, GE(1), NO_OBJ),
T1(str_desc_auth_key, R3_DESC_AUTH_KEY, GE(1), NO_OBJ),
@ -132,7 +132,7 @@ static token_rule_t hs_desc_superencrypted_v3_token_table[] = {
END_OF_TABLE
};
/* Descriptor ruleset for the encrypted section. */
/** Descriptor ruleset for the encrypted section. */
static token_rule_t hs_desc_encrypted_v3_token_table[] = {
T1_START(str_create2_formats, R3_CREATE2_FORMATS, CONCAT_ARGS, NO_OBJ),
T01(str_intro_auth_required, R3_INTRO_AUTH_REQUIRED, ARGS, NO_OBJ),
@ -140,7 +140,7 @@ static token_rule_t hs_desc_encrypted_v3_token_table[] = {
END_OF_TABLE
};
/* Descriptor ruleset for the introduction points section. */
/** Descriptor ruleset for the introduction points section. */
static token_rule_t hs_desc_intro_point_v3_token_table[] = {
T1_START(str_intro_point, R3_INTRODUCTION_POINT, EQ(1), NO_OBJ),
T1N(str_ip_onion_key, R3_INTRO_ONION_KEY, GE(2), OBJ_OK),
@ -152,7 +152,7 @@ static token_rule_t hs_desc_intro_point_v3_token_table[] = {
END_OF_TABLE
};
/* Using a key, salt and encrypted payload, build a MAC and put it in mac_out.
/** Using a key, salt and encrypted payload, build a MAC and put it in mac_out.
* We use SHA3-256 for the MAC computation.
* This function can't fail. */
static void
@ -184,7 +184,7 @@ build_mac(const uint8_t *mac_key, size_t mac_key_len,
crypto_digest_free(digest);
}
/* Using a secret data and a given decriptor object, build the secret
/** Using a secret data and a given decriptor object, build the secret
* input needed for the KDF.
*
* secret_input = SECRET_DATA | subcredential | INT_8(revision_counter)
@ -224,7 +224,7 @@ build_secret_input(const hs_descriptor_t *desc,
return secret_input_len;
}
/* Do the KDF construction and put the resulting data in key_out which is of
/** Do the KDF construction and put the resulting data in key_out which is of
* key_out_len length. It uses SHAKE-256 as specified in the spec. */
static void
build_kdf_key(const hs_descriptor_t *desc,
@ -269,7 +269,7 @@ build_kdf_key(const hs_descriptor_t *desc,
tor_free(secret_input);
}
/* Using the given descriptor, secret data, and salt, run it through our
/** Using the given descriptor, secret data, and salt, run it through our
* KDF function and then extract a secret key in key_out, the IV in iv_out
* and MAC in mac_out. This function can't fail. */
static void
@ -308,7 +308,7 @@ build_secret_key_iv_mac(const hs_descriptor_t *desc,
/* === ENCODING === */
/* Encode the given link specifier objects into a newly allocated string.
/** Encode the given link specifier objects into a newly allocated string.
* This can't fail so caller can always assume a valid string being
* returned. */
STATIC char *
@ -355,7 +355,7 @@ encode_link_specifiers(const smartlist_t *specs)
return encoded_b64;
}
/* Encode an introduction point legacy key and certificate. Return a newly
/** Encode an introduction point legacy key and certificate. Return a newly
* allocated string with it. On failure, return NULL. */
static char *
encode_legacy_key(const hs_desc_intro_point_t *ip)
@ -392,7 +392,7 @@ encode_legacy_key(const hs_desc_intro_point_t *ip)
return encoded;
}
/* Encode an introduction point encryption key and certificate. Return a newly
/** Encode an introduction point encryption key and certificate. Return a newly
* allocated string with it. On failure, return NULL. */
static char *
encode_enc_key(const hs_desc_intro_point_t *ip)
@ -418,7 +418,7 @@ encode_enc_key(const hs_desc_intro_point_t *ip)
return encoded;
}
/* Encode an introduction point onion key. Return a newly allocated string
/** Encode an introduction point onion key. Return a newly allocated string
* with it. Can not fail. */
static char *
encode_onion_key(const hs_desc_intro_point_t *ip)
@ -435,7 +435,7 @@ encode_onion_key(const hs_desc_intro_point_t *ip)
return encoded;
}
/* Encode an introduction point object and return a newly allocated string
/** Encode an introduction point object and return a newly allocated string
* with it. On failure, return NULL. */
static char *
encode_intro_point(const ed25519_public_key_t *sig_key,
@ -505,7 +505,7 @@ encode_intro_point(const ed25519_public_key_t *sig_key,
return encoded_ip;
}
/* Given a source length, return the new size including padding for the
/** Given a source length, return the new size including padding for the
* plaintext encryption. */
static size_t
compute_padded_plaintext_length(size_t plaintext_len)
@ -525,7 +525,7 @@ compute_padded_plaintext_length(size_t plaintext_len)
return plaintext_padded_len;
}
/* Given a buffer, pad it up to the encrypted section padding requirement. Set
/** Given a buffer, pad it up to the encrypted section padding requirement. Set
* the newly allocated string in padded_out and return the length of the
* padded buffer. */
STATIC size_t
@ -548,7 +548,7 @@ build_plaintext_padding(const char *plaintext, size_t plaintext_len,
return padded_len;
}
/* Using a key, IV and plaintext data of length plaintext_len, create the
/** Using a key, IV and plaintext data of length plaintext_len, create the
* encrypted section by encrypting it and setting encrypted_out with the
* data. Return size of the encrypted data buffer. */
static size_t
@ -593,7 +593,7 @@ build_encrypted(const uint8_t *key, const uint8_t *iv, const char *plaintext,
return encrypted_len;
}
/* Encrypt the given <b>plaintext</b> buffer using <b>desc</b> and
/** Encrypt the given <b>plaintext</b> buffer using <b>desc</b> and
* <b>secret_data</b> to get the keys. Set encrypted_out with the encrypted
* data and return the length of it. <b>is_superencrypted_layer</b> is set
* if this is the outer encrypted layer of the descriptor. */
@ -663,7 +663,7 @@ encrypt_descriptor_data(const hs_descriptor_t *desc,
return final_blob_len;
}
/* Create and return a string containing a client-auth entry. It's the
/** Create and return a string containing a client-auth entry. It's the
* responsibility of the caller to free the returned string. This function
* will never fail. */
static char *
@ -733,7 +733,7 @@ get_all_auth_client_lines(const hs_descriptor_t *desc)
return auth_client_lines_str;
}
/* Create the inner layer of the descriptor (which includes the intro points,
/** Create the inner layer of the descriptor (which includes the intro points,
* etc.). Return a newly-allocated string with the layer plaintext, or NULL if
* an error occurred. It's the responsibility of the caller to free the
* returned string. */
@ -789,7 +789,7 @@ get_inner_encrypted_layer_plaintext(const hs_descriptor_t *desc)
return encoded_str;
}
/* Create the middle layer of the descriptor, which includes the client auth
/** Create the middle layer of the descriptor, which includes the client auth
* data and the encrypted inner layer (provided as a base64 string at
* <b>layer2_b64_ciphertext</b>). Return a newly-allocated string with the
* layer plaintext. It's the responsibility of the caller to free the returned
@ -845,7 +845,7 @@ get_outer_encrypted_layer_plaintext(const hs_descriptor_t *desc,
return layer1_str;
}
/* Encrypt <b>encoded_str</b> into an encrypted blob and then base64 it before
/** Encrypt <b>encoded_str</b> into an encrypted blob and then base64 it before
* returning it. <b>desc</b> is provided to derive the encryption
* keys. <b>secret_data</b> is also proved to derive the encryption keys.
* <b>is_superencrypted_layer</b> is set if <b>encoded_str</b> is the
@ -878,7 +878,7 @@ encrypt_desc_data_and_base64(const hs_descriptor_t *desc,
return enc_b64;
}
/* Generate the secret data which is used to encrypt/decrypt the descriptor.
/** Generate the secret data which is used to encrypt/decrypt the descriptor.
*
* SECRET_DATA = blinded-public-key
* SECRET_DATA = blinded-public-key | descriptor_cookie
@ -925,7 +925,7 @@ build_secret_data(const ed25519_public_key_t *blinded_pubkey,
return secret_data_len;
}
/* Generate and encode the superencrypted portion of <b>desc</b>. This also
/** Generate and encode the superencrypted portion of <b>desc</b>. This also
* involves generating the encrypted portion of the descriptor, and performing
* the superencryption. A newly allocated NUL-terminated string pointer
* containing the encrypted encoded blob is put in encrypted_blob_out. Return 0
@ -999,7 +999,7 @@ encode_superencrypted_data(const hs_descriptor_t *desc,
return ret;
}
/* Encode a v3 HS descriptor. Return 0 on success and set encoded_out to the
/** Encode a v3 HS descriptor. Return 0 on success and set encoded_out to the
* newly allocated string of the encoded descriptor. On error, -1 is returned
* and encoded_out is untouched. */
static int
@ -1111,7 +1111,7 @@ desc_encode_v3(const hs_descriptor_t *desc,
/* === DECODING === */
/* Given the token tok for an auth client, decode it as
/** Given the token tok for an auth client, decode it as
* hs_desc_authorized_client_t. tok->args MUST contain at least 3 elements
* Return 0 on success else -1 on failure. */
static int
@ -1147,7 +1147,7 @@ decode_auth_client(const directory_token_t *tok,
return ret;
}
/* Given an encoded string of the link specifiers, return a newly allocated
/** Given an encoded string of the link specifiers, return a newly allocated
* list of decoded link specifiers. Return NULL on error. */
STATIC smartlist_t *
decode_link_specifiers(const char *encoded)
@ -1201,7 +1201,7 @@ decode_link_specifiers(const char *encoded)
return results;
}
/* Given a list of authentication types, decode it and put it in the encrypted
/** Given a list of authentication types, decode it and put it in the encrypted
* data section. Return 1 if we at least know one of the type or 0 if we know
* none of them. */
static int
@ -1229,7 +1229,7 @@ decode_auth_type(hs_desc_encrypted_data_t *desc, const char *list)
return match;
}
/* Parse a space-delimited list of integers representing CREATE2 formats into
/** Parse a space-delimited list of integers representing CREATE2 formats into
* the bitfield in hs_desc_encrypted_data_t. Ignore unrecognized values. */
static void
decode_create2_list(hs_desc_encrypted_data_t *desc, const char *list)
@ -1263,7 +1263,7 @@ decode_create2_list(hs_desc_encrypted_data_t *desc, const char *list)
smartlist_free(tokens);
}
/* Given a certificate, validate the certificate for certain conditions which
/** Given a certificate, validate the certificate for certain conditions which
* are if the given type matches the cert's one, if the signing key is
* included and if the that key was actually used to sign the certificate.
*
@ -1300,7 +1300,7 @@ cert_is_valid(tor_cert_t *cert, uint8_t type, const char *log_obj_type)
return 0;
}
/* Given some binary data, try to parse it to get a certificate object. If we
/** Given some binary data, try to parse it to get a certificate object. If we
* have a valid cert, validate it using the given wanted type. On error, print
* a log using the err_msg has the certificate identifier adding semantic to
* the log and cert_out is set to NULL. On success, 0 is returned and cert_out
@ -1337,7 +1337,7 @@ cert_parse_and_validate(tor_cert_t **cert_out, const char *data,
return -1;
}
/* Return true iff the given length of the encrypted data of a descriptor
/** Return true iff the given length of the encrypted data of a descriptor
* passes validation. */
STATIC int
encrypted_data_length_is_valid(size_t len)
@ -1356,7 +1356,7 @@ encrypted_data_length_is_valid(size_t len)
return 0;
}
/* Build the KEYS component for the authorized client computation. The format
/** Build the KEYS component for the authorized client computation. The format
* of the construction is:
*
* SECRET_SEED = x25519(sk, pk)
@ -1400,7 +1400,7 @@ build_descriptor_cookie_keys(const uint8_t *subcredential,
return keystream_len;
}
/* Decrypt the descriptor cookie given the descriptor, the auth client,
/** Decrypt the descriptor cookie given the descriptor, the auth client,
* and the client secret key. On sucess, return 0 and a newly allocated
* descriptor cookie descriptor_cookie_out. On error or if the client id
* is invalid, return -1 and descriptor_cookie_out is set to
@ -1592,7 +1592,7 @@ decrypt_desc_layer,(const hs_descriptor_t *desc,
return result_len;
}
/* Decrypt the superencrypted section of the descriptor using the given
/** Decrypt the superencrypted section of the descriptor using the given
* descriptor object <b>desc</b>. A newly allocated NUL terminated string is
* put in decrypted_out which contains the superencrypted layer of the
* descriptor. Return the length of decrypted_out on success else 0 is
@ -1624,7 +1624,7 @@ desc_decrypt_superencrypted(const hs_descriptor_t *desc, char **decrypted_out)
return superencrypted_len;
}
/* Decrypt the encrypted section of the descriptor using the given descriptor
/** Decrypt the encrypted section of the descriptor using the given descriptor
* object <b>desc</b>. A newly allocated NUL terminated string is put in
* decrypted_out which contains the encrypted layer of the descriptor.
* Return the length of decrypted_out on success else 0 is returned and
@ -1677,7 +1677,7 @@ desc_decrypt_encrypted(const hs_descriptor_t *desc,
return encrypted_len;
}
/* Given the token tok for an intro point legacy key, the list of tokens, the
/** Given the token tok for an intro point legacy key, the list of tokens, the
* introduction point ip being decoded and the descriptor desc from which it
* comes from, decode the legacy key and set the intro point object. Return 0
* on success else -1 on failure. */
@ -1735,7 +1735,7 @@ decode_intro_legacy_key(const directory_token_t *tok,
return -1;
}
/* Dig into the descriptor <b>tokens</b> to find the onion key we should use
/** Dig into the descriptor <b>tokens</b> to find the onion key we should use
* for this intro point, and set it into <b>onion_key_out</b>. Return 0 if it
* was found and well-formed, otherwise return -1 in case of errors. */
static int
@ -1779,7 +1779,7 @@ set_intro_point_onion_key(curve25519_public_key_t *onion_key_out,
return retval;
}
/* Given the start of a section and the end of it, decode a single
/** Given the start of a section and the end of it, decode a single
* introduction point from that section. Return a newly allocated introduction
* point object containing the decoded data. Return NULL if the section can't
* be decoded. */
@ -1908,7 +1908,7 @@ decode_introduction_point(const hs_descriptor_t *desc, const char *start)
return ip;
}
/* Given a descriptor string at <b>data</b>, decode all possible introduction
/** Given a descriptor string at <b>data</b>, decode all possible introduction
* points that we can find. Add the introduction point object to desc_enc as we
* find them. This function can't fail and it is possible that zero
* introduction points can be decoded. */
@ -1972,7 +1972,7 @@ decode_intro_points(const hs_descriptor_t *desc,
smartlist_free(intro_points);
}
/* Return 1 iff the given base64 encoded signature in b64_sig from the encoded
/** Return 1 iff the given base64 encoded signature in b64_sig from the encoded
* descriptor in encoded_desc validates the descriptor content. */
STATIC int
desc_sig_is_valid(const char *b64_sig,
@ -2031,7 +2031,7 @@ desc_sig_is_valid(const char *b64_sig,
return ret;
}
/* Decode descriptor plaintext data for version 3. Given a list of tokens, an
/** Decode descriptor plaintext data for version 3. Given a list of tokens, an
* allocated plaintext object that will be populated and the encoded
* descriptor with its length. The last one is needed for signature
* verification. Unknown tokens are simply ignored so this won't error on
@ -2134,7 +2134,7 @@ desc_decode_plaintext_v3(smartlist_t *tokens,
return -1;
}
/* Decode the version 3 superencrypted section of the given descriptor desc.
/** Decode the version 3 superencrypted section of the given descriptor desc.
* The desc_superencrypted_out will be populated with the decoded data.
* Return 0 on success else -1. */
static int
@ -2249,7 +2249,7 @@ desc_decode_superencrypted_v3(const hs_descriptor_t *desc,
return ret;
}
/* Decode the version 3 encrypted section of the given descriptor desc. The
/** Decode the version 3 encrypted section of the given descriptor desc. The
* desc_encrypted_out will be populated with the decoded data. Return 0 on
* success else -1. */
static int
@ -2364,7 +2364,7 @@ desc_decode_encrypted_v3(const hs_descriptor_t *desc,
return ret;
}
/* Table of encrypted decode function version specific. The function are
/** Table of encrypted decode function version specific. The function are
* indexed by the version number so v3 callback is at index 3 in the array. */
static int
(*decode_encrypted_handlers[])(
@ -2376,7 +2376,7 @@ static int
desc_decode_encrypted_v3,
};
/* Decode the encrypted data section of the given descriptor and store the
/** Decode the encrypted data section of the given descriptor and store the
* data in the given encrypted data object. Return 0 on success else a
* negative value on error. */
int
@ -2417,7 +2417,7 @@ hs_desc_decode_encrypted(const hs_descriptor_t *desc,
return ret;
}
/* Table of superencrypted decode function version specific. The function are
/** Table of superencrypted decode function version specific. The function are
* indexed by the version number so v3 callback is at index 3 in the array. */
static int
(*decode_superencrypted_handlers[])(
@ -2428,9 +2428,9 @@ static int
desc_decode_superencrypted_v3,
};
/* Decode the superencrypted data section of the given descriptor and store the
* data in the given superencrypted data object. Return 0 on success else a
* negative value on error. */
/** Decode the superencrypted data section of the given descriptor and store
* the data in the given superencrypted data object. Return 0 on success else
* a negative value on error. */
int
hs_desc_decode_superencrypted(const hs_descriptor_t *desc,
hs_desc_superencrypted_data_t *
@ -2468,7 +2468,7 @@ hs_desc_decode_superencrypted(const hs_descriptor_t *desc,
return ret;
}
/* Table of plaintext decode function version specific. The function are
/** Table of plaintext decode function version specific. The function are
* indexed by the version number so v3 callback is at index 3 in the array. */
static int
(*decode_plaintext_handlers[])(
@ -2481,7 +2481,7 @@ static int
desc_decode_plaintext_v3,
};
/* Fully decode the given descriptor plaintext and store the data in the
/** Fully decode the given descriptor plaintext and store the data in the
* plaintext data object. Returns 0 on success else a negative value. */
int
hs_desc_decode_plaintext(const char *encoded,
@ -2554,7 +2554,7 @@ hs_desc_decode_plaintext(const char *encoded,
return ret;
}
/* Fully decode an encoded descriptor and set a newly allocated descriptor
/** Fully decode an encoded descriptor and set a newly allocated descriptor
* object in desc_out. Client secret key is used to decrypt the "encrypted"
* section if not NULL else it's ignored.
*
@ -2614,7 +2614,7 @@ hs_desc_decode_descriptor(const char *encoded,
return ret;
}
/* Table of encode function version specific. The functions are indexed by the
/** Table of encode function version specific. The functions are indexed by the
* version number so v3 callback is at index 3 in the array. */
static int
(*encode_handlers[])(
@ -2627,7 +2627,7 @@ static int
desc_encode_v3,
};
/* Encode the given descriptor desc including signing with the given key pair
/** Encode the given descriptor desc including signing with the given key pair
* signing_kp and encrypting with the given descriptor cookie.
*
* If the client authorization is enabled, descriptor_cookie must be the same
@ -2684,7 +2684,7 @@ hs_desc_encode_descriptor,(const hs_descriptor_t *desc,
return ret;
}
/* Free the content of the plaintext section of a descriptor. */
/** Free the content of the plaintext section of a descriptor. */
void
hs_desc_plaintext_data_free_contents(hs_desc_plaintext_data_t *desc)
{
@ -2700,7 +2700,7 @@ hs_desc_plaintext_data_free_contents(hs_desc_plaintext_data_t *desc)
memwipe(desc, 0, sizeof(*desc));
}
/* Free the content of the superencrypted section of a descriptor. */
/** Free the content of the superencrypted section of a descriptor. */
void
hs_desc_superencrypted_data_free_contents(hs_desc_superencrypted_data_t *desc)
{
@ -2720,7 +2720,7 @@ hs_desc_superencrypted_data_free_contents(hs_desc_superencrypted_data_t *desc)
memwipe(desc, 0, sizeof(*desc));
}
/* Free the content of the encrypted section of a descriptor. */
/** Free the content of the encrypted section of a descriptor. */
void
hs_desc_encrypted_data_free_contents(hs_desc_encrypted_data_t *desc)
{
@ -2740,7 +2740,7 @@ hs_desc_encrypted_data_free_contents(hs_desc_encrypted_data_t *desc)
memwipe(desc, 0, sizeof(*desc));
}
/* Free the descriptor plaintext data object. */
/** Free the descriptor plaintext data object. */
void
hs_desc_plaintext_data_free_(hs_desc_plaintext_data_t *desc)
{
@ -2748,7 +2748,7 @@ hs_desc_plaintext_data_free_(hs_desc_plaintext_data_t *desc)
tor_free(desc);
}
/* Free the descriptor plaintext data object. */
/** Free the descriptor plaintext data object. */
void
hs_desc_superencrypted_data_free_(hs_desc_superencrypted_data_t *desc)
{
@ -2756,7 +2756,7 @@ hs_desc_superencrypted_data_free_(hs_desc_superencrypted_data_t *desc)
tor_free(desc);
}
/* Free the descriptor encrypted data object. */
/** Free the descriptor encrypted data object. */
void
hs_desc_encrypted_data_free_(hs_desc_encrypted_data_t *desc)
{
@ -2764,7 +2764,7 @@ hs_desc_encrypted_data_free_(hs_desc_encrypted_data_t *desc)
tor_free(desc);
}
/* Free the given descriptor object. */
/** Free the given descriptor object. */
void
hs_descriptor_free_(hs_descriptor_t *desc)
{
@ -2778,7 +2778,7 @@ hs_descriptor_free_(hs_descriptor_t *desc)
tor_free(desc);
}
/* Return the size in bytes of the given plaintext data object. A sizeof() is
/** Return the size in bytes of the given plaintext data object. A sizeof() is
* not enough because the object contains pointers and the encrypted blob.
* This is particularly useful for our OOM subsystem that tracks the HSDir
* cache size for instance. */
@ -2790,7 +2790,7 @@ hs_desc_plaintext_obj_size(const hs_desc_plaintext_data_t *data)
data->superencrypted_blob_size);
}
/* Return the size in bytes of the given encrypted data object. Used by OOM
/** Return the size in bytes of the given encrypted data object. Used by OOM
* subsystem. */
static size_t
hs_desc_encrypted_obj_size(const hs_desc_encrypted_data_t *data)
@ -2810,7 +2810,7 @@ hs_desc_encrypted_obj_size(const hs_desc_encrypted_data_t *data)
return sizeof(*data) + intro_size;
}
/* Return the size in bytes of the given descriptor object. Used by OOM
/** Return the size in bytes of the given descriptor object. Used by OOM
* subsystem. */
size_t
hs_desc_obj_size(const hs_descriptor_t *data)
@ -2821,7 +2821,7 @@ hs_desc_obj_size(const hs_descriptor_t *data)
sizeof(data->subcredential));
}
/* Return a newly allocated descriptor intro point. */
/** Return a newly allocated descriptor intro point. */
hs_desc_intro_point_t *
hs_desc_intro_point_new(void)
{
@ -2830,7 +2830,7 @@ hs_desc_intro_point_new(void)
return ip;
}
/* Free a descriptor intro point object. */
/** Free a descriptor intro point object. */
void
hs_desc_intro_point_free_(hs_desc_intro_point_t *ip)
{
@ -2849,7 +2849,7 @@ hs_desc_intro_point_free_(hs_desc_intro_point_t *ip)
tor_free(ip);
}
/* Allocate and build a new fake client info for the descriptor. Return a
/** Allocate and build a new fake client info for the descriptor. Return a
* newly allocated object. This can't fail. */
hs_desc_authorized_client_t *
hs_desc_build_fake_authorized_client(void)
@ -2867,7 +2867,7 @@ hs_desc_build_fake_authorized_client(void)
return client_auth;
}
/* Using the service's subcredential, client public key, auth ephemeral secret
/** Using the service's subcredential, client public key, auth ephemeral secret
* key, and descriptor cookie, build the auth client so we can then encode the
* descriptor for publication. client_out must be already allocated. */
void
@ -2925,14 +2925,14 @@ hs_desc_build_authorized_client(const uint8_t *subcredential,
crypto_cipher_free(cipher);
}
/* Free an authoriezd client object. */
/** Free an authoriezd client object. */
void
hs_desc_authorized_client_free_(hs_desc_authorized_client_t *client)
{
tor_free(client);
}
/* From the given descriptor, remove and free every introduction point. */
/** From the given descriptor, remove and free every introduction point. */
void
hs_descriptor_clear_intro_points(hs_descriptor_t *desc)
{

104
src/feature/hs/hs_descriptor.h
View File

@ -18,88 +18,88 @@
/* Trunnel */
struct link_specifier_t;
/* The earliest descriptor format version we support. */
/** The earliest descriptor format version we support. */
#define HS_DESC_SUPPORTED_FORMAT_VERSION_MIN 3
/* The latest descriptor format version we support. */
/** The latest descriptor format version we support. */
#define HS_DESC_SUPPORTED_FORMAT_VERSION_MAX 3
/* Default lifetime of a descriptor in seconds. The valus is set at 3 hours
/** Default lifetime of a descriptor in seconds. The valus is set at 3 hours
* which is 180 minutes or 10800 seconds. */
#define HS_DESC_DEFAULT_LIFETIME (3 * 60 * 60)
/* Maximum lifetime of a descriptor in seconds. The value is set at 12 hours
/** Maximum lifetime of a descriptor in seconds. The value is set at 12 hours
* which is 720 minutes or 43200 seconds. */
#define HS_DESC_MAX_LIFETIME (12 * 60 * 60)
/* Lifetime of certificate in the descriptor. This defines the lifetime of the
/** Lifetime of certificate in the descriptor. This defines the lifetime of the
* descriptor signing key and the cross certification cert of that key. It is
* set to 54 hours because a descriptor can be around for 48 hours and because
* consensuses are used after the hour, add an extra 6 hours to give some time
* for the service to stop using it. */
#define HS_DESC_CERT_LIFETIME (54 * 60 * 60)
/* Length of the salt needed for the encrypted section of a descriptor. */
/** Length of the salt needed for the encrypted section of a descriptor. */
#define HS_DESC_ENCRYPTED_SALT_LEN 16
/* Length of the KDF output value which is the length of the secret key,
/** Length of the KDF output value which is the length of the secret key,
* the secret IV and MAC key length which is the length of H() output. */
#define HS_DESC_ENCRYPTED_KDF_OUTPUT_LEN \
CIPHER256_KEY_LEN + CIPHER_IV_LEN + DIGEST256_LEN
/* Pad plaintext of superencrypted data section before encryption so that its
/** Pad plaintext of superencrypted data section before encryption so that its
* length is a multiple of this value. */
#define HS_DESC_SUPERENC_PLAINTEXT_PAD_MULTIPLE 10000
/* Maximum length in bytes of a full hidden service descriptor. */
/** Maximum length in bytes of a full hidden service descriptor. */
#define HS_DESC_MAX_LEN 50000 /* 50kb max size */
/* Key length for the descriptor symmetric encryption. As specified in the
/** Key length for the descriptor symmetric encryption. As specified in the
* protocol, we use AES-256 for the encrypted section of the descriptor. The
* following is the length in bytes and the bit size. */
#define HS_DESC_ENCRYPTED_KEY_LEN CIPHER256_KEY_LEN
#define HS_DESC_ENCRYPTED_BIT_SIZE (HS_DESC_ENCRYPTED_KEY_LEN * 8)
/* Length of each components in the auth client section in the descriptor. */
/** Length of each components in the auth client section in the descriptor. */
#define HS_DESC_CLIENT_ID_LEN 8
#define HS_DESC_DESCRIPTOR_COOKIE_LEN 16
#define HS_DESC_COOKIE_KEY_LEN 32
#define HS_DESC_COOKIE_KEY_BIT_SIZE (HS_DESC_COOKIE_KEY_LEN * 8)
#define HS_DESC_ENCRYPED_COOKIE_LEN HS_DESC_DESCRIPTOR_COOKIE_LEN
/* The number of auth client entries in the descriptor must be the multiple
/** The number of auth client entries in the descriptor must be the multiple
* of this constant. */
#define HS_DESC_AUTH_CLIENT_MULTIPLE 16
/* Type of authentication in the descriptor. */
/** Type of authentication in the descriptor. */
typedef enum {
HS_DESC_AUTH_ED25519 = 1
} hs_desc_auth_type_t;
/* Introduction point information located in a descriptor. */
/** Introduction point information located in a descriptor. */
typedef struct hs_desc_intro_point_t {
/* Link specifier(s) which details how to extend to the relay. This list
/** Link specifier(s) which details how to extend to the relay. This list
* contains link_specifier_t objects. It MUST have at least one. */
smartlist_t *link_specifiers;
/* Onion key of the introduction point used to extend to it for the ntor
/** Onion key of the introduction point used to extend to it for the ntor
* handshake. */
curve25519_public_key_t onion_key;
/* Authentication key used to establish the introduction point circuit and
/** Authentication key used to establish the introduction point circuit and
* cross-certifies the blinded public key for the replica thus signed by
* the blinded key and in turn signs it. */
tor_cert_t *auth_key_cert;
/* Encryption key for the "ntor" type. */
/** Encryption key for the "ntor" type. */
curve25519_public_key_t enc_key;
/* Certificate cross certifying the descriptor signing key by the encryption
/** Certificate cross certifying the descriptor signing key by the encryption
* curve25519 key. This certificate contains the signing key and is of type
* CERT_TYPE_CROSS_HS_IP_KEYS [0B]. */
tor_cert_t *enc_key_cert;
/* (Optional): If this introduction point is a legacy one that is version <=
/** (Optional): If this introduction point is a legacy one that is version <=
* 0.2.9.x (HSIntro=3), we use this extra key for the intro point to be able
* to relay the cells to the service correctly. */
struct {
/* RSA public key. */
/** RSA public key. */
crypto_pk_t *key;
/* Cross certified cert with the descriptor signing key (RSA->Ed). Because
/** Cross certified cert with the descriptor signing key (RSA->Ed). Because
* of the cross certification API, we need to keep the certificate binary
* blob and its length in order to properly encode it after. */
struct {
@ -108,115 +108,115 @@ typedef struct hs_desc_intro_point_t {
} cert;
} legacy;
/* True iff the introduction point has passed the cross certification. Upon
/** True iff the introduction point has passed the cross certification. Upon
* decoding an intro point, this must be true. */
unsigned int cross_certified : 1;
} hs_desc_intro_point_t;
/* Authorized client information located in a descriptor. */
/** Authorized client information located in a descriptor. */
typedef struct hs_desc_authorized_client_t {
/* An identifier that the client will use to identify which auth client
/** An identifier that the client will use to identify which auth client
* entry it needs to use. */
uint8_t client_id[HS_DESC_CLIENT_ID_LEN];
/* An IV that is used to decrypt the encrypted descriptor cookie. */
/** An IV that is used to decrypt the encrypted descriptor cookie. */
uint8_t iv[CIPHER_IV_LEN];
/* An encrypted descriptor cookie that the client needs to decrypt to use
/** An encrypted descriptor cookie that the client needs to decrypt to use
* it to decrypt the descriptor. */
uint8_t encrypted_cookie[HS_DESC_ENCRYPED_COOKIE_LEN];
} hs_desc_authorized_client_t;
/* The encrypted data section of a descriptor. Obviously the data in this is
/** The encrypted data section of a descriptor. Obviously the data in this is
* in plaintext but encrypted once encoded. */
typedef struct hs_desc_encrypted_data_t {
/* Bitfield of CREATE2 cell supported formats. The only currently supported
/** Bitfield of CREATE2 cell supported formats. The only currently supported
* format is ntor. */
unsigned int create2_ntor : 1;
/* A list of authentication types that a client must at least support one
/** A list of authentication types that a client must at least support one
* in order to contact the service. Contains NULL terminated strings. */
smartlist_t *intro_auth_types;
/* Is this descriptor a single onion service? */
/** Is this descriptor a single onion service? */
unsigned int single_onion_service : 1;
/* A list of intro points. Contains hs_desc_intro_point_t objects. */
/** A list of intro points. Contains hs_desc_intro_point_t objects. */
smartlist_t *intro_points;
} hs_desc_encrypted_data_t;
/* The superencrypted data section of a descriptor. Obviously the data in
/** The superencrypted data section of a descriptor. Obviously the data in
* this is in plaintext but encrypted once encoded. */
typedef struct hs_desc_superencrypted_data_t {
/* This field contains ephemeral x25519 public key which is used by
/** This field contains ephemeral x25519 public key which is used by
* the encryption scheme in the client authorization. */
curve25519_public_key_t auth_ephemeral_pubkey;
/* A list of authorized clients. Contains hs_desc_authorized_client_t
/** A list of authorized clients. Contains hs_desc_authorized_client_t
* objects. */
smartlist_t *clients;
/* Decoding only: The b64-decoded encrypted blob from the descriptor */
/** Decoding only: The b64-decoded encrypted blob from the descriptor */
uint8_t *encrypted_blob;
/* Decoding only: Size of the encrypted_blob */
/** Decoding only: Size of the encrypted_blob */
size_t encrypted_blob_size;
} hs_desc_superencrypted_data_t;
/* Plaintext data that is unencrypted information of the descriptor. */
/** Plaintext data that is unencrypted information of the descriptor. */
typedef struct hs_desc_plaintext_data_t {
/* Version of the descriptor format. Spec specifies this field as a
/** Version of the descriptor format. Spec specifies this field as a
* positive integer. */
uint32_t version;
/* The lifetime of the descriptor in seconds. */
/** The lifetime of the descriptor in seconds. */
uint32_t lifetime_sec;
/* Certificate with the short-term ed22519 descriptor signing key for the
/** Certificate with the short-term ed22519 descriptor signing key for the
* replica which is signed by the blinded public key for that replica. */
tor_cert_t *signing_key_cert;
/* Signing public key which is used to sign the descriptor. Same public key
/** Signing public key which is used to sign the descriptor. Same public key
* as in the signing key certificate. */
ed25519_public_key_t signing_pubkey;
/* Blinded public key used for this descriptor derived from the master
/** Blinded public key used for this descriptor derived from the master
* identity key and generated for a specific replica number. */
ed25519_public_key_t blinded_pubkey;
/* Revision counter is incremented at each upload, regardless of whether
/** Revision counter is incremented at each upload, regardless of whether
* the descriptor has changed. This avoids leaking whether the descriptor
* has changed. Spec specifies this as a 8 bytes positive integer. */
uint64_t revision_counter;
/* Decoding only: The b64-decoded superencrypted blob from the descriptor */
/** Decoding only: The b64-decoded superencrypted blob from the descriptor */
uint8_t *superencrypted_blob;
/* Decoding only: Size of the superencrypted_blob */
/** Decoding only: Size of the superencrypted_blob */
size_t superencrypted_blob_size;
} hs_desc_plaintext_data_t;
/* Service descriptor in its decoded form. */
/** Service descriptor in its decoded form. */
typedef struct hs_descriptor_t {
/* Contains the plaintext part of the descriptor. */
/** Contains the plaintext part of the descriptor. */
hs_desc_plaintext_data_t plaintext_data;
/* The following contains what's in the superencrypted part of the
/** The following contains what's in the superencrypted part of the
* descriptor. It's only encrypted in the encoded version of the descriptor
* thus the data contained in that object is in plaintext. */
hs_desc_superencrypted_data_t superencrypted_data;
/* The following contains what's in the encrypted part of the descriptor.
/** The following contains what's in the encrypted part of the descriptor.
* It's only encrypted in the encoded version of the descriptor thus the
* data contained in that object is in plaintext. */
hs_desc_encrypted_data_t encrypted_data;
/* Subcredentials of a service, used by the client and service to decrypt
/** Subcredentials of a service, used by the client and service to decrypt
* the encrypted data. */
uint8_t subcredential[DIGEST256_LEN];
} hs_descriptor_t;
/* Return true iff the given descriptor format version is supported. */
/** Return true iff the given descriptor format version is supported. */
static inline int
hs_desc_is_supported_version(uint32_t version)
{