HACKING/design: turn the remaining parts of crypto into a certs doc

2 files changed, 34 insertions, 0 deletions

diff --git a/src/lib/crypt_ops/certs.dox b/src/lib/crypt_ops/certs.dox
new file mode 100644
index 0000000000..4703f07bcd
--- /dev/null
+++ b/src/lib/crypt_ops/certs.dox
@@ -0,0 +1,32 @@
+/**
+
+@page certificates Certificates in Tor.
+
+We have, alas, several certificate types in Tor.
+
+The tor_x509_cert_t type represents an X.509 certificate. This document
+won't explain X.509 to you -- possibly, no document can. (OTOH, Peter
+Gutmann's "x.509 style guide", though severely dated, does a good job of
+explaining how awful x.509 can be.)  Do not introduce any new usages of
+X.509. Right now we only use it in places where TLS forces us to do so.
+See x509.c for more information about using this type.
+
+
+The authority_cert_t type is used only for directory authority keys. It
+has a medium-term signing key (which the authorities actually keep
+online) signed by a long-term identity key (which the authority operator
+had really better be keeping offline).  Don't use it for any new kind of
+certificate.
+
+For new places where you need a certificate, consider tor_cert_t: it
+represents a typed and dated _something_ signed by an Ed25519 key.  The
+format is described in tor-spec. Unlike x.509, you can write it on a
+napkin.  The torcert.c file is used for manipulating these certificates and
+their associated keys.
+
+(Additionally, the Tor directory design uses a fairly wide variety of
+documents that include keys and which are signed by keys. You can
+consider these documents to be an additional kind of certificate if you
+want.)
+
+**/
diff --git a/src/mainpage.dox b/src/mainpage.dox
index eb29eb5fa2..a5988aecff 100644
--- a/src/mainpage.dox
+++ b/src/mainpage.dox
@@ -31,6 +31,8 @@ Tor repository.
 @subpage intro
 
 @subpage dataflow
+
+@subpage certificates
 **/
 
 /**