Functions and structures to handle generating and maintaining the set of keypairs necessary to be an OR. More...

#include "core/or/or.h"
#include "app/config/config.h"
#include "feature/relay/router.h"
#include "feature/relay/routerkeys.h"
#include "feature/relay/routermode.h"
#include "feature/keymgt/loadkey.h"
#include "feature/nodelist/torcert.h"
#include "feature/nodelist/networkstatus_st.h"
#include "feature/dirauth/dirvote.h"
#include "lib/crypt_ops/crypto_util.h"
#include "lib/crypt_ops/crypto_format.h"
#include "lib/tls/tortls.h"
#include "lib/tls/x509.h"

Macros
#define	ROUTERKEYS_PRIVATE

#define	ENC_KEY_HEADER "Boxed Ed25519 key"

#define	ENC_KEY_TAG "master"

#define	FAIL(msg)

#define	SET_KEY(key, newval)

#define	SET_CERT(cert, newval)

#define	HAPPENS_SOON(when, interval) ((when) < now + (interval))

#define	EXPIRES_SOON(cert, interval) (!(cert) \|\| HAPPENS_SOON((cert)->valid_until, (interval)))

#define	FAMILY_KEY_SUFFIX ".secret_family_key"

#define	FAMILY_KEY_FILE_TAG "fmly-id"

#define	FAMILY_INFO_URL "https://community.torproject.org/relay/setup/post-install/family-ids/"

Functions
int	load_ed_keys (const or_options_t *options, time_t now)

int	generate_ed_link_cert (const or_options_t *options, time_t now, int force)

int	should_make_new_ed_keys (const or_options_t *options, const time_t now)

static void	print_cert_expiration (const char expiration, const char description)

static void	log_ed_cert_expiration (const tor_cert_t cert, const char description, const char *fname, key_expiration_format_t time_format)

static int	log_master_signing_key_cert_expiration (const or_options_t *options)

int	log_cert_expiration (void)

const ed25519_public_key_t *	get_master_identity_key (void)

int	router_ed25519_id_is_me (const ed25519_public_key_t *id)

const ed25519_keypair_t *	get_master_signing_keypair (void)

const struct tor_cert_st *	get_master_signing_key_cert (void)

const ed25519_keypair_t *	get_current_auth_keypair (void)

const tor_cert_t *	get_current_link_cert_cert (void)

const tor_cert_t *	get_current_auth_key_cert (void)

STATIC bool	is_family_key_fname (const char *fname)

static bool	family_key_id_is_expected (const or_options_t options, const ed25519_public_key_t id)

static bool	family_key_is_present (const ed25519_public_key_t *id)

static smartlist_t *	list_family_key_files_impl (const char *keydir)

smartlist_t *	list_family_key_files (const or_options_t options, const char keydir)

STATIC int	load_family_id_keys_impl (const or_options_t options, const char keydir)

int	create_family_id_key (const char fname, ed25519_public_key_t pk_out)

int	load_family_id_keys (const or_options_t options, const networkstatus_t ns)

void	warn_about_family_id_config (const or_options_t options, const networkstatus_t ns)

const smartlist_t *	get_current_family_id_keys (void)

STATIC void	set_family_id_keys (smartlist_t *keys)

void	get_master_rsa_crosscert (const uint8_t *cert_out, size_t size_out)

tor_cert_t *	make_ntor_onion_key_crosscert (const curve25519_keypair_t onion_key, const ed25519_public_key_t master_id_key, time_t now, time_t lifetime, int *sign_out)

uint8_t *	make_tap_onion_key_crosscert (const crypto_pk_t onion_key, const ed25519_public_key_t master_id_key, const crypto_pk_t rsa_id_key, int len_out)

void	routerkeys_free_all (void)

Variables
static ed25519_keypair_t *	master_identity_key = NULL

static ed25519_keypair_t *	master_signing_key = NULL

static ed25519_keypair_t *	current_auth_key = NULL

static tor_cert_t *	signing_key_cert = NULL

static tor_cert_t *	link_cert_cert = NULL

static tor_cert_t *	auth_key_cert = NULL

static uint8_t *	rsa_ed_crosscert = NULL

static size_t	rsa_ed_crosscert_len = 0

static time_t	rsa_ed_crosscert_expiration = 0

static smartlist_t *	family_id_keys = NULL

static smartlist_t *	cached_family_key_file_list = NULL

Detailed Description

Functions and structures to handle generating and maintaining the set of keypairs necessary to be an OR.

The keys handled here now are the Ed25519 keys that Tor relays use to sign descriptors, authenticate themselves on links, and identify one another uniquely. Other keys are maintained in router.c and rendservice.c.

(TODO: The keys in router.c should go here too.)

Definition in file routerkeys.c.

Macro Definition Documentation

◆ ENC_KEY_HEADER

#define ENC_KEY_HEADER "Boxed Ed25519 key"

Definition at line 34 of file routerkeys.c.

◆ ENC_KEY_TAG

#define ENC_KEY_TAG "master"

Definition at line 35 of file routerkeys.c.

◆ FAIL

#define FAIL ( msg )

Value:

    do {                          \
    log_warn(LD_OR, (msg));                     \
    goto err;                                   \
  } while (0)

◆ FAMILY_INFO_URL

#define FAMILY_INFO_URL "https://community.torproject.org/relay/setup/post-install/family-ids/"

Definition at line 940 of file routerkeys.c.

◆ FAMILY_KEY_FILE_TAG

#define FAMILY_KEY_FILE_TAG "fmly-id"

Tag to use on family key files.

Definition at line 734 of file routerkeys.c.

◆ FAMILY_KEY_SUFFIX

#define FAMILY_KEY_SUFFIX ".secret_family_key"

Suffix for the filenames in which we expect to find a family ID key.

Definition at line 688 of file routerkeys.c.

◆ ROUTERKEYS_PRIVATE

#define ROUTERKEYS_PRIVATE

Definition at line 17 of file routerkeys.c.

◆ SET_CERT

#define SET_CERT	(	cert,
		newval
	)

Value:

    do {             \
    if ((cert) != (newval))                     \
      tor_cert_free(cert);                      \
    cert = (newval);                            \
  } while (0)

◆ SET_KEY

#define SET_KEY	(	key,
		newval
	)

Value:

    do {               \
    if ((key) != (newval))                      \
      ed25519_keypair_free(key);                \
    key = (newval);                             \
  } while (0)

Function Documentation

◆ create_family_id_key()

int create_family_id_key	(	const char *	fname,
		ed25519_public_key_t *	pk_out
	)

Create a new family ID key, and store it in fname.

If pk_out is provided, set it to the generated public key.

Definition at line 876 of file routerkeys.c.

◆ family_key_id_is_expected()

static bool family_key_id_is_expected	(	const or_options_t *	options,
		const ed25519_public_key_t *	id
	)

static

Return true if id is configured in options.

Definition at line 704 of file routerkeys.c.

◆ family_key_is_present()

static bool family_key_is_present ( const ed25519_public_key_t * id )

static

Return true if the key for id has been loaded.

Definition at line 719 of file routerkeys.c.

Referenced by load_family_id_keys().

◆ generate_ed_link_cert()

int generate_ed_link_cert	(	const or_options_t *	options,
		time_t	now,
		int	force
	)

Retrieve our currently-in-use Ed25519 link certificate and id certificate, and, if they would expire soon (based on the time now, generate new certificates (without embedding the public part of the signing key inside). If force is true, always generate a new certificate.

The signed_key from the current id->signing certificate will be used to sign the new key within newly generated X509 certificate.

Returns -1 upon error. Otherwise, returns 0 upon success (either when the current certificate is still valid, or when a new certificate was successfully generated, or no certificate was needed).

Definition at line 373 of file routerkeys.c.

◆ get_current_auth_key_cert()

const tor_cert_t * get_current_auth_key_cert ( void )

Definition at line 680 of file routerkeys.c.

◆ get_current_auth_keypair()

const ed25519_keypair_t * get_current_auth_keypair ( void )

Definition at line 668 of file routerkeys.c.

◆ get_current_family_id_keys()

const smartlist_t * get_current_family_id_keys ( void )

Return a list of our current family id keypairs, as a list of ed25519_keypair_t.

Never returns NULL.

TODO PROP321: Right now this is only used in testing; when we add relay support we'll need a way to actually read these keys from disk.

Definition at line 989 of file routerkeys.c.

◆ get_current_link_cert_cert()

const tor_cert_t * get_current_link_cert_cert ( void )

Definition at line 674 of file routerkeys.c.

◆ get_master_identity_key()

const ed25519_public_key_t * get_master_identity_key ( void )

Definition at line 630 of file routerkeys.c.

◆ get_master_rsa_crosscert()

void get_master_rsa_crosscert	(	const uint8_t **	cert_out,
		size_t *	size_out
	)

Definition at line 1014 of file routerkeys.c.

◆ get_master_signing_key_cert()

const struct tor_cert_st * get_master_signing_key_cert ( void )

Definition at line 662 of file routerkeys.c.

◆ get_master_signing_keypair()

const ed25519_keypair_t * get_master_signing_keypair ( void )

Definition at line 656 of file routerkeys.c.

◆ is_family_key_fname()

STATIC bool is_family_key_fname ( const char * fname )

Return true if fname is a possible filename of a family ID key.

Family ID key filenames are FAMILY_KEY_FNAME, followed optionally by "." and a positive integer.

Definition at line 697 of file routerkeys.c.

◆ list_family_key_files()

smartlist_t * list_family_key_files	(	const or_options_t *	options,
		const char *	keydir
	)

Return a list of all the possible family-key files in keydir. Return NULL on error.

Definition at line 782 of file routerkeys.c.

◆ list_family_key_files_impl()

static smartlist_t * list_family_key_files_impl ( const char * keydir )

static

Return a list of all the possible family-key files in keydir. Return NULL on error.

(Unlike list_family_key_files, this function does not use a cached list when the seccomp2 sandbox is enabled.)

Definition at line 742 of file routerkeys.c.

Referenced by list_family_key_files().

◆ load_ed_keys()

int load_ed_keys	(	const or_options_t *	options,
		time_t	now
	)

Running as a server: load, reload, or refresh our ed25519 keys and certificates, creating and saving new ones as needed.

Return -1 on failure; 0 on success if the signing key was not replaced; and 1 on success if the signing key was replaced.

Definition at line 63 of file routerkeys.c.

◆ load_family_id_keys()

int load_family_id_keys	(	const or_options_t *	options,
		const networkstatus_t *	ns
	)

If configured to do so, load our family keys from the key directory. Otherwise, clear the family keys.

Additionally, warn about inconsistencies between family options. If ns is provided, provide additional warnings.

options is required; ns may be NULL.

Definition at line 912 of file routerkeys.c.

◆ load_family_id_keys_impl()

STATIC int load_family_id_keys_impl	(	const or_options_t *	options,
		const char *	keydir
	)

Look for all the family keys in keydir, load them into family_id_keys.

Definition at line 805 of file routerkeys.c.

Referenced by load_family_id_keys().

◆ log_cert_expiration()

int log_cert_expiration ( void )

Log when a key certificate expires. Used when tor is given the –key-expiration command-line option.

If an command argument is given, which should specify the type of key to get expiry information about (currently supported arguments are "sign"), get info about that type of certificate. Otherwise, print info about the supported arguments.

Returns 0 on success and -1 on failure.

Definition at line 614 of file routerkeys.c.

◆ log_ed_cert_expiration()

static void log_ed_cert_expiration	(	const tor_cert_t *	cert,
		const char *	description,
		const char *	fname,
		key_expiration_format_t	time_format
	)

static

Log when a certificate, cert, with some description and stored in a file named fname, is going to expire. Formats the expire time according to time_format.

Definition at line 532 of file routerkeys.c.

◆ log_master_signing_key_cert_expiration()

static int log_master_signing_key_cert_expiration ( const or_options_t * options )

static

Log when our master signing key certificate expires. Used when tor is given the –key-expiration command-line option.

Returns 0 on success and 1 on failure.

Definition at line 568 of file routerkeys.c.

Referenced by log_cert_expiration().

◆ make_ntor_onion_key_crosscert()

tor_cert_t * make_ntor_onion_key_crosscert	(	const curve25519_keypair_t *	onion_key,
		const ed25519_public_key_t *	master_id_key,
		time_t	now,
		time_t	lifetime,
		int *	sign_out
	)

Construct cross-certification for the master identity key with the ntor onion key. Store the sign of the corresponding ed25519 public key in *sign_out.

Definition at line 1025 of file routerkeys.c.

◆ make_tap_onion_key_crosscert()

uint8_t * make_tap_onion_key_crosscert	(	const crypto_pk_t *	onion_key,
		const ed25519_public_key_t *	master_id_key,
		const crypto_pk_t *	rsa_id_key,
		int *	len_out
	)

Construct and return an RSA signature for the TAP onion key to cross-certify the RSA and Ed25519 identity keys. Set len_out to its length.

Definition at line 1048 of file routerkeys.c.

◆ print_cert_expiration()

static void print_cert_expiration	(	const char *	expiration,
		const char *	description
	)

static

Print the ISO8601-formated expiration for a certificate with some description to stdout.

For example, for a signing certificate, this might print out: signing-cert-expiry: 2017-07-25 08:30:15 UTC

Definition at line 520 of file routerkeys.c.

◆ router_ed25519_id_is_me()

int router_ed25519_id_is_me ( const ed25519_public_key_t * id )

Return true iff id is our Ed25519 master identity key.

Definition at line 639 of file routerkeys.c.

◆ routerkeys_free_all()

void routerkeys_free_all ( void )

Definition at line 1080 of file routerkeys.c.

◆ set_family_id_keys()

STATIC void set_family_id_keys ( smartlist_t * keys )

Replace our list of family ID keys with family_id_keys, which must be a list of ed25519_keypair_t.

Takes ownership of its input.

Definition at line 1003 of file routerkeys.c.

◆ should_make_new_ed_keys()

int should_make_new_ed_keys	(	const or_options_t *	options,
		const time_t	now
	)

Return 1 if any of the following are true:

if one of our Ed25519 signing, auth, or link certificates would expire soon w.r.t. the time now,
if we do not currently have a link certificate, or
if our cached Ed25519 link certificate is not same as the one we're currently using.

Otherwise, returns 0.

Definition at line 427 of file routerkeys.c.

◆ warn_about_family_id_config()

void warn_about_family_id_config	(	const or_options_t *	options,
		const networkstatus_t *	ns
	)

Generate warnings as appropriate about our family ID configuration.

options is required; ns may be NULL.

Definition at line 948 of file routerkeys.c.

Referenced by router_new_consensus_params().

Variable Documentation

◆ auth_key_cert

tor_cert_t* auth_key_cert = NULL

static

Definition at line 46 of file routerkeys.c.

◆ cached_family_key_file_list

smartlist_t* cached_family_key_file_list = NULL

static

A list of files returned by list_family_key_files_impl. Used when the seccomp2 sandbox is enabled.

Definition at line 776 of file routerkeys.c.

Referenced by list_family_key_files().

◆ current_auth_key

ed25519_keypair_t* current_auth_key = NULL

static

Definition at line 43 of file routerkeys.c.

◆ family_id_keys

smartlist_t* family_id_keys = NULL

static

Definition at line 53 of file routerkeys.c.

◆ link_cert_cert

tor_cert_t* link_cert_cert = NULL

static

Definition at line 45 of file routerkeys.c.

◆ master_identity_key

ed25519_keypair_t* master_identity_key = NULL

static

Definition at line 41 of file routerkeys.c.

◆ master_signing_key

ed25519_keypair_t* master_signing_key = NULL

static

Definition at line 42 of file routerkeys.c.

◆ rsa_ed_crosscert

uint8_t* rsa_ed_crosscert = NULL

static

Definition at line 48 of file routerkeys.c.

◆ rsa_ed_crosscert_expiration

time_t rsa_ed_crosscert_expiration = 0

static

Definition at line 50 of file routerkeys.c.

◆ rsa_ed_crosscert_len

size_t rsa_ed_crosscert_len = 0

static

Definition at line 49 of file routerkeys.c.

◆ signing_key_cert

tor_cert_t* signing_key_cert = NULL

static

Definition at line 44 of file routerkeys.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ENC_KEY_HEADER

◆ ENC_KEY_TAG

◆ FAIL

◆ FAMILY_INFO_URL

◆ FAMILY_KEY_FILE_TAG

◆ FAMILY_KEY_SUFFIX

◆ ROUTERKEYS_PRIVATE

◆ SET_CERT

◆ SET_KEY

Function Documentation

◆ create_family_id_key()

◆ family_key_id_is_expected()

◆ family_key_is_present()

◆ generate_ed_link_cert()

◆ get_current_auth_key_cert()

◆ get_current_auth_keypair()

◆ get_current_family_id_keys()

◆ get_current_link_cert_cert()

◆ get_master_identity_key()

◆ get_master_rsa_crosscert()

◆ get_master_signing_key_cert()

◆ get_master_signing_keypair()

◆ is_family_key_fname()

◆ list_family_key_files()

◆ list_family_key_files_impl()

◆ load_ed_keys()

◆ load_family_id_keys()

◆ load_family_id_keys_impl()

◆ log_cert_expiration()

◆ log_ed_cert_expiration()

◆ log_master_signing_key_cert_expiration()

◆ make_ntor_onion_key_crosscert()

◆ make_tap_onion_key_crosscert()

◆ print_cert_expiration()

◆ router_ed25519_id_is_me()

◆ routerkeys_free_all()

◆ set_family_id_keys()

◆ should_make_new_ed_keys()

◆ warn_about_family_id_config()

Variable Documentation

◆ auth_key_cert

◆ cached_family_key_file_list

◆ current_auth_key

◆ family_id_keys

◆ link_cert_cert

◆ master_identity_key

◆ master_signing_key

◆ rsa_ed_crosscert

◆ rsa_ed_crosscert_expiration

◆ rsa_ed_crosscert_len

◆ signing_key_cert