keypin.c File Reference

Functions and structures for associating routers' RSA key fingerprints with their ED25519 keys. More...

#include "orconfig.h"
#include "compat.h"
#include "crypto_digest.h"
#include "crypto_format.h"
#include "di_ops.h"
#include "ht.h"
#include "keypin.h"
#include "siphash.h"
#include "torint.h"
#include "torlog.h"
#include "util.h"
#include "util_format.h"

Include dependency graph for keypin.c:

Macros
#define	KEYPIN_PRIVATE
#define	O_SYNC   0
#define	JOURNAL_LINE_LEN   (BASE64_DIGEST_LEN + BASE64_DIGEST256_LEN + 2)

Functions
	HT_PROTOTYPE (HT_GENERATE2(rsamap, HT_GENERATE2(keypin_ent_st, HT_GENERATE2(rsamap_node, HT_GENERATE2(keypin_ent_hash_rsa, HT_GENERATE2(keypin_ents_eq_rsa)
int	keypin_check (const uint8_t *rsa_id_digest, const uint8_t *ed25519_id_key)
	MOCK_IMPL (STATIC void, keypin_add_entry_to_map,(keypin_ent_t *ent))
int	keypin_check_lone_rsa (const uint8_t *rsa_id_digest)
int	keypin_open_journal (const char *fname)
int	keypin_close_journal (void)
STATIC int	keypin_load_journal_impl (const char *data, size_t size)
int	keypin_load_journal (const char *fname)
STATIC keypin_ent_t *	keypin_parse_journal_line (const char *cp)
void	keypin_clear (void)

Detailed Description

Functions and structures for associating routers' RSA key fingerprints with their ED25519 keys.

Key-pinning for RSA and Ed25519 identity keys at directory authorities.

Many older clients, and many internal interfaces, still refer to relays by their RSA1024 identity keys. We can make this more secure, however: authorities use this module to track which RSA keys have been used along with which Ed25519 keys, and force such associations to be permanent.

This module implements a key-pinning mechanism to ensure that it's safe to use RSA keys as identitifers even as we migrate to Ed25519 keys. It remembers, for every Ed25519 key we've seen, what the associated Ed25519 key is. This way, if we see a different Ed25519 key with that RSA key, we'll know that there's a mismatch.

(As of this writing, these key associations are advisory only, mostly because some relay operators kept mishandling their Ed25519 keys during the initial Ed25519 rollout. We should fix this problem, and then toggle the AuthDirPinKeys option.)

We persist these entries to disk using a simple format, where each line has a base64-encoded RSA SHA1 hash, then a base64-endoded Ed25519 key. Empty lines, misformed lines, and lines beginning with # are ignored. Lines beginning with @ are reserved for future extensions.

The dirserv.c module is the main user of these functions.

Macro Definition Documentation

JOURNAL_LINE_LEN

#define JOURNAL_LINE_LEN   (BASE64_DIGEST_LEN + BASE64_DIGEST256_LEN + 2)

Length of a keypinning journal line, including terminating newline.

Function Documentation

keypin_check()

int keypin_check	(	const uint8_t *	rsa_id_digest,
		const uint8_t *	ed25519_id_key
	)

As keypin_check_and_add, but do not add. Return KEYPIN_NOT_FOUND if we would add.

keypin_check_lone_rsa()

int keypin_check_lone_rsa

(

const uint8_t *

rsa_id_digest

)

Check whether we already have an entry in the key pinning table for a router with RSA ID digest rsa_id_digest. If we have no such entry, return KEYPIN_NOT_FOUND. If we find an entry that matches the RSA key but which has an ed25519 key, return KEYPIN_MISMATCH.

keypin_clear()

void keypin_clear

(

void

)

Remove all entries from the keypinning table.

keypin_close_journal()

int keypin_close_journal

(

void

)

Close the keypinning journal file.

keypin_load_journal()

int keypin_load_journal

(

const char *

fname

)

Load a journal from the file called fname. Return 0 on success, -1 on failure.

Here is the call graph for this function:

keypin_load_journal_impl()

STATIC int keypin_load_journal_impl	(	const char *	data,
		size_t	size
	)

Load a journal from the size-byte region at data. Return 0 on success, -1 on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

keypin_open_journal()

int keypin_open_journal

(

const char *

fname

)

Open the key-pinning journal to append to fname. Return 0 on success, -1 on failure.

Here is the call graph for this function:

keypin_parse_journal_line()

STATIC keypin_ent_t* keypin_parse_journal_line

(

const char *

cp

)

Parse a single keypinning journal line entry from cp. The input does not need to be NUL-terminated, but it does need to have KEYPIN_JOURNAL_LINE_LEN -1 bytes available to read. Return a new entry on success, and NULL on failure.

Here is the caller graph for this function:

MOCK_IMPL()

MOCK_IMPL	(	STATIC	void,
		keypin_add_entry_to_map	,
		(keypin_ent_t *ent)
	)

Helper: add ent to the hash tables.