Data Structures | Macros | Enumerations | Functions
hs_descriptor.h File Reference

Header file for hs_descriptor.c. More...

#include <stdint.h>
#include "core/or/or.h"
#include "trunnel/ed25519_cert.h"
#include "feature/nodelist/torcert.h"
#include "core/crypto/hs_ntor.h"
#include "feature/hs/hs_pow.h"

Go to the source code of this file.

Data Structures

struct  hs_desc_intro_point_t
struct  hs_desc_authorized_client_t
struct  hs_desc_encrypted_data_t
struct  hs_desc_superencrypted_data_t
struct  hs_desc_plaintext_data_t
struct  hs_descriptor_t


#define HS_DESC_DEFAULT_LIFETIME   (3 * 60 * 60)
#define HS_DESC_MAX_LIFETIME   (12 * 60 * 60)
#define HS_DESC_CERT_LIFETIME   (54 * 60 * 60)
#define HS_DESC_MAX_LEN   50000 /* 50kb max size */
#define hs_descriptor_free(desc)    FREE_AND_NULL(hs_descriptor_t, hs_descriptor_free_, (desc))
#define hs_desc_plaintext_data_free(desc)    FREE_AND_NULL(hs_desc_plaintext_data_t, hs_desc_plaintext_data_free_, (desc))
#define hs_desc_superencrypted_data_free(desc)
#define hs_desc_encrypted_data_free(desc)    FREE_AND_NULL(hs_desc_encrypted_data_t, hs_desc_encrypted_data_free_, (desc))
#define hs_desc_intro_point_free(ip)    FREE_AND_NULL(hs_desc_intro_point_t, hs_desc_intro_point_free_, (ip))
#define hs_desc_authorized_client_free(client)


enum  hs_desc_auth_type_t { HS_DESC_AUTH_ED25519 = 1 }
enum  hs_desc_decode_status_t {


static int hs_desc_is_supported_version (uint32_t version)
void hs_descriptor_free_ (hs_descriptor_t *desc)
void hs_desc_plaintext_data_free_ (hs_desc_plaintext_data_t *desc)
void hs_desc_superencrypted_data_free_ (hs_desc_superencrypted_data_t *desc)
void hs_desc_encrypted_data_free_ (hs_desc_encrypted_data_t *desc)
void hs_descriptor_clear_intro_points (hs_descriptor_t *desc)
int hs_desc_encode_descriptor (const hs_descriptor_t *desc, const ed25519_keypair_t *signing_kp, const uint8_t *descriptor_cookie, char **encoded_out)
hs_desc_decode_status_t hs_desc_decode_descriptor (const char *encoded, const hs_subcredential_t *subcredential, const curve25519_secret_key_t *client_auth_sk, hs_descriptor_t **desc_out)
hs_desc_decode_status_t hs_desc_decode_plaintext (const char *encoded, hs_desc_plaintext_data_t *plaintext)
hs_desc_decode_status_t hs_desc_decode_superencrypted (const hs_descriptor_t *desc, hs_desc_superencrypted_data_t *desc_out)
hs_desc_decode_status_t hs_desc_decode_encrypted (const hs_descriptor_t *desc, const curve25519_secret_key_t *client_auth_sk, hs_desc_encrypted_data_t *desc_out)
size_t hs_desc_obj_size (const hs_descriptor_t *data)
size_t hs_desc_plaintext_obj_size (const hs_desc_plaintext_data_t *data)
hs_desc_intro_point_ths_desc_intro_point_new (void)
void hs_desc_intro_point_free_ (hs_desc_intro_point_t *ip)
void hs_desc_authorized_client_free_ (hs_desc_authorized_client_t *client)
hs_desc_authorized_client_ths_desc_build_fake_authorized_client (void)
void hs_desc_build_authorized_client (const hs_subcredential_t *subcredential, const curve25519_public_key_t *client_auth_pk, const curve25519_secret_key_t *auth_ephemeral_sk, const uint8_t *descriptor_cookie, hs_desc_authorized_client_t *client_out)
void hs_desc_plaintext_data_free_contents (hs_desc_plaintext_data_t *desc)
void hs_desc_superencrypted_data_free_contents (hs_desc_superencrypted_data_t *desc)
void hs_desc_encrypted_data_free_contents (hs_desc_encrypted_data_t *desc)
bool hs_desc_supports_congestion_control (const hs_descriptor_t *desc)

Detailed Description

Header file for hs_descriptor.c.

Definition in file hs_descriptor.h.

Macro Definition Documentation



The number of auth client entries in the descriptor must be the multiple of this constant.

Definition at line 67 of file hs_descriptor.h.

◆ hs_desc_authorized_client_free

#define hs_desc_authorized_client_free (   client)
FREE_AND_NULL(hs_desc_authorized_client_t, \
void hs_desc_authorized_client_free_(hs_desc_authorized_client_t *client)

Definition at line 316 of file hs_descriptor.h.


#define HS_DESC_CERT_LIFETIME   (54 * 60 * 60)

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.

Definition at line 39 of file hs_descriptor.h.



Length of each components in the auth client section in the descriptor.

Definition at line 59 of file hs_descriptor.h.



Definition at line 62 of file hs_descriptor.h.



Definition at line 61 of file hs_descriptor.h.


#define HS_DESC_DEFAULT_LIFETIME   (3 * 60 * 60)

Default lifetime of a descriptor in seconds. The valus is set at 3 hours which is 180 minutes or 10800 seconds.

Definition at line 30 of file hs_descriptor.h.



Definition at line 60 of file hs_descriptor.h.



Definition at line 63 of file hs_descriptor.h.



Definition at line 56 of file hs_descriptor.h.

◆ hs_desc_encrypted_data_free

#define hs_desc_encrypted_data_free (   desc)     FREE_AND_NULL(hs_desc_encrypted_data_t, hs_desc_encrypted_data_free_, (desc))

Definition at line 284 of file hs_descriptor.h.



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.

Definition at line 44 of file hs_descriptor.h.



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.

Definition at line 55 of file hs_descriptor.h.



Length of the salt needed for the encrypted section of a descriptor.

Definition at line 41 of file hs_descriptor.h.

◆ hs_desc_intro_point_free

#define hs_desc_intro_point_free (   ip)     FREE_AND_NULL(hs_desc_intro_point_t, hs_desc_intro_point_free_, (ip))

Definition at line 313 of file hs_descriptor.h.


#define HS_DESC_MAX_LEN   50000 /* 50kb max size */

Maximum length in bytes of a full hidden service descriptor.

Definition at line 50 of file hs_descriptor.h.


#define HS_DESC_MAX_LIFETIME   (12 * 60 * 60)

Maximum lifetime of a descriptor in seconds. The value is set at 12 hours which is 720 minutes or 43200 seconds.

Definition at line 33 of file hs_descriptor.h.

◆ hs_desc_plaintext_data_free

#define hs_desc_plaintext_data_free (   desc)     FREE_AND_NULL(hs_desc_plaintext_data_t, hs_desc_plaintext_data_free_, (desc))

Definition at line 277 of file hs_descriptor.h.



Pad plaintext of superencrypted data section before encryption so that its length is a multiple of this value.

Definition at line 48 of file hs_descriptor.h.

◆ hs_desc_superencrypted_data_free

#define hs_desc_superencrypted_data_free (   desc)
void hs_desc_superencrypted_data_free_(hs_desc_superencrypted_data_t *desc)

Definition at line 280 of file hs_descriptor.h.



The latest descriptor format version we support.

Definition at line 26 of file hs_descriptor.h.



The earliest descriptor format version we support.

Definition at line 24 of file hs_descriptor.h.

◆ hs_descriptor_free

#define hs_descriptor_free (   desc)     FREE_AND_NULL(hs_descriptor_t, hs_descriptor_free_, (desc))

Definition at line 274 of file hs_descriptor.h.

Enumeration Type Documentation

◆ hs_desc_auth_type_t

Type of authentication in the descriptor.

Definition at line 70 of file hs_descriptor.h.

◆ hs_desc_decode_status_t

Error code when decoding a descriptor.

Definition at line 75 of file hs_descriptor.h.

Function Documentation

◆ hs_desc_authorized_client_free_()

void hs_desc_authorized_client_free_ ( hs_desc_authorized_client_t client)

Free an authoriezd client object.

Definition at line 3099 of file hs_descriptor.c.

◆ hs_desc_build_authorized_client()

void hs_desc_build_authorized_client ( const hs_subcredential_t subcredential,
const curve25519_public_key_t client_auth_pk,
const curve25519_secret_key_t auth_ephemeral_sk,
const uint8_t *  descriptor_cookie,
hs_desc_authorized_client_t client_out 

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.

Definition at line 3043 of file hs_descriptor.c.

◆ hs_desc_build_fake_authorized_client()

hs_desc_authorized_client_t * hs_desc_build_fake_authorized_client ( void  )

Allocate and build a new fake client info for the descriptor. Return a newly allocated object. This can't fail.

Definition at line 3024 of file hs_descriptor.c.

◆ hs_desc_decode_descriptor()

hs_desc_decode_status_t hs_desc_decode_descriptor ( const char *  encoded,
const hs_subcredential_t subcredential,
const curve25519_secret_key_t client_auth_sk,
hs_descriptor_t **  desc_out 

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.

Return 0 on success. A negative value is returned on error and desc_out is set to NULL.

Definition at line 2722 of file hs_descriptor.c.

Referenced by hs_client_decode_descriptor(), and hs_desc_encode_descriptor().

◆ hs_desc_decode_encrypted()

hs_desc_decode_status_t hs_desc_decode_encrypted ( const hs_descriptor_t desc,
const curve25519_secret_key_t client_auth_sk,
hs_desc_encrypted_data_t desc_encrypted 

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.

Definition at line 2543 of file hs_descriptor.c.

◆ hs_desc_decode_plaintext()

hs_desc_decode_status_t hs_desc_decode_plaintext ( const char *  encoded,
hs_desc_plaintext_data_t plaintext 

Fully decode the given descriptor plaintext and store the data in the plaintext data object.

Definition at line 2644 of file hs_descriptor.c.

◆ hs_desc_decode_superencrypted()

hs_desc_decode_status_t hs_desc_decode_superencrypted ( const hs_descriptor_t desc,
hs_desc_superencrypted_data_t desc_superencrypted 

Decode the superencrypted data section of the given descriptor and store the data in the given superencrypted data object.

Definition at line 2593 of file hs_descriptor.c.

◆ hs_desc_encode_descriptor()

int hs_desc_encode_descriptor ( const hs_descriptor_t desc,
const ed25519_keypair_t signing_kp,
const uint8_t *  descriptor_cookie,
char **  encoded_out 

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 as the one used to build hs_desc_authorized_client_t in the descriptor. Otherwise, it must be NULL. On success, encoded_out points to a newly allocated NUL terminated string that contains the encoded descriptor as a string.

Return 0 on success and encoded_out is a valid pointer. On error, -1 is returned and encoded_out is set to NULL.

Definition at line 2803 of file hs_descriptor.c.

Referenced by service_encode_descriptor().

◆ hs_desc_encrypted_data_free_()

void hs_desc_encrypted_data_free_ ( hs_desc_encrypted_data_t desc)

Free the descriptor encrypted data object.

Definition at line 2928 of file hs_descriptor.c.

◆ hs_desc_encrypted_data_free_contents()

void hs_desc_encrypted_data_free_contents ( hs_desc_encrypted_data_t desc)

Free the content of the encrypted section of a descriptor.

Definition at line 2890 of file hs_descriptor.c.

Referenced by hs_desc_encrypted_data_free_(), and hs_descriptor_free_().

◆ hs_desc_intro_point_free_()

void hs_desc_intro_point_free_ ( hs_desc_intro_point_t ip)

Free a descriptor intro point object.

Definition at line 3004 of file hs_descriptor.c.

◆ hs_desc_intro_point_new()

hs_desc_intro_point_t * hs_desc_intro_point_new ( void  )

Return a newly allocated descriptor intro point.

Definition at line 2995 of file hs_descriptor.c.

◆ hs_desc_is_supported_version()

static int hs_desc_is_supported_version ( uint32_t  version)

Return true iff the given descriptor format version is supported.

Definition at line 262 of file hs_descriptor.h.

Referenced by hs_cache_lookup_as_dir(), and hs_desc_encode_descriptor().

◆ hs_desc_obj_size()

size_t hs_desc_obj_size ( const hs_descriptor_t data)

Return the size in bytes of the given descriptor object. Used by OOM subsystem.

Definition at line 2983 of file hs_descriptor.c.

Referenced by cache_get_client_entry_size().

◆ hs_desc_plaintext_data_free_()

void hs_desc_plaintext_data_free_ ( hs_desc_plaintext_data_t desc)

Free the descriptor plaintext data object.

Definition at line 2912 of file hs_descriptor.c.

◆ hs_desc_plaintext_data_free_contents()

void hs_desc_plaintext_data_free_contents ( hs_desc_plaintext_data_t desc)

Free the content of the plaintext section of a descriptor.

Definition at line 2854 of file hs_descriptor.c.

Referenced by hs_desc_plaintext_data_free_(), and hs_descriptor_free_().

◆ hs_desc_plaintext_obj_size()

size_t hs_desc_plaintext_obj_size ( const hs_desc_plaintext_data_t data)

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.

Definition at line 2953 of file hs_descriptor.c.

Referenced by cache_get_dir_entry_size(), and hs_desc_obj_size().

◆ hs_desc_superencrypted_data_free_()

void hs_desc_superencrypted_data_free_ ( hs_desc_superencrypted_data_t desc)

Free the descriptor plaintext data object.

Definition at line 2920 of file hs_descriptor.c.

◆ hs_desc_superencrypted_data_free_contents()

void hs_desc_superencrypted_data_free_contents ( hs_desc_superencrypted_data_t desc)

Free the content of the superencrypted section of a descriptor.

Definition at line 2870 of file hs_descriptor.c.

Referenced by hs_desc_superencrypted_data_free_(), and hs_descriptor_free_().

◆ hs_desc_supports_congestion_control()

bool hs_desc_supports_congestion_control ( const hs_descriptor_t desc)

Return true iff we support the given descriptor congestion control parameters.

Definition at line 3123 of file hs_descriptor.c.

Referenced by setup_rendezvous_circ_congestion_control().

◆ hs_descriptor_clear_intro_points()

void hs_descriptor_clear_intro_points ( hs_descriptor_t desc)

From the given descriptor, remove and free every introduction point.

Definition at line 3106 of file hs_descriptor.c.

Referenced by build_desc_intro_points().

◆ hs_descriptor_free_()

void hs_descriptor_free_ ( hs_descriptor_t desc)

Free the given descriptor object.

Definition at line 2936 of file hs_descriptor.c.