src/lib/crypt_ops/certs.md

   1
   2 @page certificates Certificates in Tor
   3
   4 We have, alas, several certificate types in Tor.
   5
   6 The tor_x509_cert_t type represents an X.509 certificate. This document
   7 won't explain X.509 to you -- possibly, no document can. (OTOH, Peter
   8 Gutmann's "x.509 style guide", though severely dated, does a good job of
   9 explaining how awful x.509 can be.)  Do not introduce any new usages of
  10 X.509. Right now we only use it in places where TLS forces us to do so.
  11 See x509.c for more information about using this type.
  12
  13
  14 The authority_cert_t type is used only for directory authority keys. It
  15 has a medium-term signing key (which the authorities actually keep
  16 online) signed by a long-term identity key (which the authority operator
  17 had really better be keeping offline).  Don't use it for any new kind of
  18 certificate.
  19
  20 For new places where you need a certificate, consider tor_cert_t: it
  21 represents a typed and dated _something_ signed by an Ed25519 key.  The
  22 format is described in tor-spec. Unlike x.509, you can write it on a
  23 napkin.  The torcert.c file is used for manipulating these certificates and
  24 their associated keys.
  25
  26 (Additionally, the Tor directory design uses a fairly wide variety of
  27 documents that include keys and which are signed by keys. You can
  28 consider these documents to be an additional kind of certificate if you
  29 want.)