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

Macros
#define	HS_DESC_SUPPORTED_FORMAT_VERSION_MIN   3
#define	HS_DESC_SUPPORTED_FORMAT_VERSION_MAX   3
#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_ENCRYPTED_SALT_LEN   16
#define	HS_DESC_ENCRYPTED_KDF_OUTPUT_LEN    CIPHER256_KEY_LEN + CIPHER_IV_LEN + DIGEST256_LEN
#define	HS_DESC_SUPERENC_PLAINTEXT_PAD_MULTIPLE   10000
#define	HS_DESC_MAX_LEN   50000 /* 50kb max size */
#define	HS_DESC_ENCRYPTED_KEY_LEN   CIPHER256_KEY_LEN
#define	HS_DESC_ENCRYPTED_BIT_SIZE   (HS_DESC_ENCRYPTED_KEY_LEN * 8)
#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
#define	HS_DESC_AUTH_CLIENT_MULTIPLE   16
#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)

Enumerations
enum	hs_desc_auth_type_t { HS_DESC_AUTH_ED25519 = 1 }
enum	hs_desc_decode_status_t {   HS_DESC_DECODE_BAD_CLIENT_AUTH = -6 , HS_DESC_DECODE_NEED_CLIENT_AUTH = -5 , HS_DESC_DECODE_ENCRYPTED_ERROR = -4 , HS_DESC_DECODE_SUPERENC_ERROR = -3 ,   HS_DESC_DECODE_PLAINTEXT_ERROR = -2 , HS_DESC_DECODE_GENERIC_ERROR = -1 , HS_DESC_DECODE_OK = 0 }

Functions
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_t *	hs_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_t *	hs_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

HS_DESC_AUTH_CLIENT_MULTIPLE

#define HS_DESC_AUTH_CLIENT_MULTIPLE   16

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

)

Value:

  FREE_AND_NULL(hs_desc_authorized_client_t, \
                hs_desc_authorized_client_free_, (client))

Definition at line 300 of file hs_descriptor.h.

HS_DESC_CERT_LIFETIME

#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.

HS_DESC_CLIENT_ID_LEN

#define HS_DESC_CLIENT_ID_LEN   8

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

Definition at line 58 of file hs_descriptor.h.

HS_DESC_DEFAULT_LIFETIME

#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.

HS_DESC_ENCRYPTED_KDF_OUTPUT_LEN

#define HS_DESC_ENCRYPTED_KDF_OUTPUT_LEN    CIPHER256_KEY_LEN + CIPHER_IV_LEN + DIGEST256_LEN

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.

HS_DESC_ENCRYPTED_KEY_LEN

#define HS_DESC_ENCRYPTED_KEY_LEN   CIPHER256_KEY_LEN

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.

HS_DESC_ENCRYPTED_SALT_LEN

#define HS_DESC_ENCRYPTED_SALT_LEN   16

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

Definition at line 40 of file hs_descriptor.h.

HS_DESC_MAX_LEN

#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.

HS_DESC_MAX_LIFETIME

#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.

HS_DESC_SUPERENC_PLAINTEXT_PAD_MULTIPLE

#define HS_DESC_SUPERENC_PLAINTEXT_PAD_MULTIPLE   10000

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

)

Value:

  FREE_AND_NULL(hs_desc_superencrypted_data_t, \
                hs_desc_superencrypted_data_free_, (desc))

Definition at line 265 of file hs_descriptor.h.

HS_DESC_SUPPORTED_FORMAT_VERSION_MAX

#define HS_DESC_SUPPORTED_FORMAT_VERSION_MAX   3

The latest descriptor format version we support.

Definition at line 25 of file hs_descriptor.h.

HS_DESC_SUPPORTED_FORMAT_VERSION_MIN

#define HS_DESC_SUPPORTED_FORMAT_VERSION_MIN   3

The earliest descriptor format version we support.

Definition at line 23 of file hs_descriptor.h.

Enumeration Type Documentation

hs_desc_auth_type_t

enum 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

enum 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 2939 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 2883 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 2864 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 2570 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 2392 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 2493 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 2442 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 2651 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 2768 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 2732 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 2844 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 2835 of file hs_descriptor.c.

hs_desc_is_supported_version()

static int hs_desc_is_supported_version ( uint32_t  version )

inlinestatic

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 2823 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 2752 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 2696 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 2793 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 2760 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 2712 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 2946 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 2776 of file hs_descriptor.c.