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"

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)
int 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)
int hs_desc_decode_plaintext (const char *encoded, hs_desc_plaintext_data_t *plaintext)
int hs_desc_decode_superencrypted (const hs_descriptor_t *desc, hs_desc_superencrypted_data_t *desc_out)
int 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)

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 66 of file hs_descriptor.h.

◆ hs_desc_authorized_client_free

#define hs_desc_authorized_client_free (   client)

Definition at line 300 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 38 of file hs_descriptor.h.



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

Definition at line 58 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 29 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 43 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 54 of file hs_descriptor.h.



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

Definition at line 40 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 49 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 32 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 47 of file hs_descriptor.h.

◆ hs_desc_superencrypted_data_free

#define hs_desc_superencrypted_data_free (   desc)

Definition at line 265 of file hs_descriptor.h.



The latest descriptor format version we support.

Definition at line 25 of file hs_descriptor.h.



The earliest descriptor format version we support.

Definition at line 23 of file hs_descriptor.h.

Enumeration Type Documentation

◆ hs_desc_auth_type_t

Type of authentication in the descriptor.

Definition at line 69 of file hs_descriptor.h.

◆ hs_desc_decode_status_t

Error code when decoding a descriptor.

Definition at line 74 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 2940 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 2884 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 2865 of file hs_descriptor.c.

◆ hs_desc_decode_descriptor()

int 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 2571 of file hs_descriptor.c.

Referenced by hs_client_decode_descriptor(), and hs_desc_encode_descriptor().

◆ hs_desc_decode_encrypted()

int 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 2393 of file hs_descriptor.c.

◆ hs_desc_decode_plaintext()

int 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 2494 of file hs_descriptor.c.

◆ hs_desc_decode_superencrypted()

int 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 2443 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 2652 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 2769 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 2733 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 2845 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 2836 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 247 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 2824 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 2753 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 2697 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 2794 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 2761 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 2713 of file hs_descriptor.c.

Referenced by hs_desc_superencrypted_data_free_(), and hs_descriptor_free_().

◆ 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 2947 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 2777 of file hs_descriptor.c.

void hs_desc_authorized_client_free_(hs_desc_authorized_client_t *client)
Definition: hs_descriptor.c:2940
Definition: hs_descriptor.h:143
void hs_desc_superencrypted_data_free_(hs_desc_superencrypted_data_t *desc)
Definition: hs_descriptor.c:2761
Definition: hs_descriptor.h:176