From aae034d13e458dfe82b503d3a1b54b0e5200b6b8 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Fri, 14 Oct 2016 20:08:51 -0400 Subject: Write a bunch of module documentation. This commit adds or improves the module-level documenation for: buffers.c circuitstats.c command.c connection_edge.c control.c cpuworker.c crypto_curve25519.c crypto_curve25519.h crypto_ed25519.c crypto_format.c dircollate.c dirserv.c dns.c dns_structs.h fp_pair.c geoip.c hibernate.c keypin.c ntmain.c onion.c onion_fast.c onion_ntor.c onion_tap.c periodic.c protover.c protover.h reasons.c rephist.c replaycache.c routerlist.c routerparse.c routerset.c statefile.c status.c tor_main.c workqueue.c In particular, I've tried to explain (for each documented module) what each module does, what's in it, what the big idea is, why it belongs in Tor, and who calls it. In a few cases, I've added TODO notes about refactoring opportunities. I've also renamed an argument, and fixed a few DOCDOC comments. --- src/or/keypin.c | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'src/or/keypin.c') diff --git a/src/or/keypin.c b/src/or/keypin.c index 335c793cd9..2d4c4e92d2 100644 --- a/src/or/keypin.c +++ b/src/or/keypin.c @@ -39,16 +39,28 @@ * @brief 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. */ static int keypin_journal_append_entry(const uint8_t *rsa_id_digest, -- cgit v1.2.3-54-g00ecf