routerkeys.c File Reference

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

#include "or.h"
#include "config.h"
#include "crypto_util.h"
#include "router.h"
#include "crypto_pwbox.h"
#include "routerkeys.h"
#include "torcert.h"

Include dependency graph for routerkeys.c:

Macros
#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)))

Functions
int	read_encrypted_secret_key (ed25519_secret_key_t *out, const char *fname)
int	write_encrypted_secret_key (const ed25519_secret_key_t *key, const char *fname)
ed25519_keypair_t *	ed_key_init_from_file (const char *fname, uint32_t flags, int severity, const ed25519_keypair_t *signing_key, time_t now, time_t lifetime, uint8_t cert_type, struct tor_cert_st **cert_out)
ed25519_keypair_t *	ed_key_new (const ed25519_keypair_t *signing_key, uint32_t flags, time_t now, time_t lifetime, uint8_t cert_type, struct tor_cert_st **cert_out)
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)
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)
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)
	MOCK_IMPL (int, check_tap_onion_key_crosscert,(const uint8_t *crosscert, int crosscert_len, const crypto_pk_t *onion_pkey, const ed25519_public_key_t *master_id_pkey, const uint8_t *rsa_id_digest))
void	routerkeys_free_all (void)

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

Macro Definition Documentation

FAIL

#define FAIL

(

msg

)

Value:

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

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

ed_key_init_from_file()

ed25519_keypair_t* ed_key_init_from_file	(	const char *	fname,
		uint32_t	flags,
		int	severity,
		const ed25519_keypair_t *	signing_key,
		time_t	now,
		time_t	lifetime,
		uint8_t	cert_type,
		struct tor_cert_st **	cert_out
	)

Read an ed25519 key and associated certificates from files beginning with fname, with certificate type cert_type. On failure, return NULL; on success return the keypair.

If INIT_ED_KEY_CREATE is set in flags, then create the key (and certificate if requested) if it doesn't exist, and save it to disk.

If INIT_ED_KEY_NEEDCERT is set in flags, load/create a certificate too and store it in *cert_out. Fail if the cert can't be found/created. To create a certificate, signing_key must be set to the key that should sign it; now to the current time, and lifetime to the lifetime of the key.

If INIT_ED_KEY_REPLACE is set in flags, then create and save new key whether we can read the old one or not.

If INIT_ED_KEY_EXTRA_STRONG is set in flags, set the extra_strong flag when creating the secret key.

If INIT_ED_KEY_INCLUDE_SIGNING_KEY_IN_CERT is set in flags, and we create a new certificate, create it with the signing key embedded.

If INIT_ED_KEY_SPLIT is set in flags, and we create a new key, store the public key in a separate file from the secret key.

If INIT_ED_KEY_MISSING_SECRET_OK is set in flags, and we find a public key file but no secret key file, return successfully anyway.

If INIT_ED_KEY_OMIT_SECRET is set in flags, do not try to load a secret key unless no public key is found. Do not return a secret key. (but create and save one if needed).

If INIT_ED_KEY_NO_LOAD_SECRET is set in flags, don't try to load a secret key, no matter what.

If INIT_ED_KEY_TRY_ENCRYPTED is set, we look for an encrypted secret key and consider encrypting any new secret key.

If INIT_ED_KEY_NO_REPAIR is set, and there is any issue loading the keys from disk other than their absence (full or partial), we do not try to replace them.

If INIT_ED_KEY_SUGGEST_KEYGEN is set, have log messages about failures refer to the –keygen option.

If INIT_ED_KEY_EXPLICIT_FNAME is set, use the provided file name for the secret key file, encrypted or not.

Here is the call graph for this function:

ed_key_new()

ed25519_keypair_t* ed_key_new	(	const ed25519_keypair_t *	signing_key,
		uint32_t	flags,
		time_t	now,
		time_t	lifetime,
		uint8_t	cert_type,
		struct tor_cert_st **	cert_out
	)

Create a new signing key and (optionally) certficiate; do not read or write from disk. See ed_key_init_from_file() for more information.

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

Here is the call graph for this function:

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.

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.

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

MOCK_IMPL()

MOCK_IMPL	(	int	,
		check_tap_onion_key_crosscert	,
		(const uint8_t *crosscert, int crosscert_len, const crypto_pk_t *onion_pkey, const ed25519_public_key_t *master_id_pkey, const uint8_t *rsa_id_digest)
	)

Check whether an RSA-TAP cross-certification is correct. Return 0 if it is, -1 if it isn't.

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.

Here is the call graph for this function:

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.