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.
I grepped and hand-inspected the "it's" instances, to see if any
were supposed to be possessive. While doing that, I found a
"the the", so I grepped to see if there were any more.
When we find a conflict in the keypinning journal, treat the new
entry as superseding all old entries that overlap either of its
keys.
Also add a (not-yet-used) configuration option to disable keypinning
enforcement.
The base64 and base32 functions used to be in crypto.c;
crypto_format.h had no header; some general-purpose functions were in
crypto_curve25519.c.
This patch makes a {crypto,util}_format.[ch], and puts more functions
there. Small modules are beautiful!
With this patch:
* Authorities load the key-pinning log at startup.
* Authorities open a key-pinning log for writing at startup.
* Authorities reject any router with an ed25519 key where they have
previously seen that ed25519 key with a different RSA key, or vice
versa.
* Authorities warn about, but *do not* reject, RSA-only descriptors
when the RSA key has previously gone along with an Ed25519 key.
(We should make this a 'reject' too, but we can't do that until we're
sure there's no legit reason to downgrade to 0.2.5.)
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.
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
a # are ignored. Lines beginning with @ are reserved for future
extensions.
