cert-spec.txt 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137
  1. Ed25519 certificates in Tor
  2. 1. Scope and Preliminaries
  3. This document describes a certificate format that Tor uses for
  4. its Ed25519 internal certificates. It is not the only
  5. certificate format that Tor uses. For the certificates that
  6. authorities use for their signing keys, see dir-spec.txt.
  7. Additionally, Tor uses TLS, which depends on X.509 certificates;
  8. see tor-spec.txt for details.
  9. The certificates in this document were first introduced in
  10. proposal 220, and were first supported by Tor in Tor version
  11. 0.2.7.2-alpha.
  12. 1.1. Signing
  13. All signatures here, unless otherwise specified, are computed
  14. using an Ed25519 key.
  15. In order to future-proof the format, before signing anything, the
  16. signed document is prefixed with a personalization string, which
  17. will be different in each case.
  18. 2. Document formats
  19. 2.1. Certificates
  20. When generating a signing key, we also generate a certificate for it.
  21. Unlike the certificates for authorities' signing keys, these
  22. certificates need to be sent around frequently, in significant
  23. numbers. So we'll choose a compact representation.
  24. VERSION [1 Byte]
  25. CERT_TYPE [1 Byte]
  26. EXPIRATION_DATE [4 Bytes]
  27. CERT_KEY_TYPE [1 byte]
  28. CERTIFIED_KEY [32 Bytes]
  29. N_EXTENSIONS [1 byte]
  30. EXTENSIONS [N_EXTENSIONS times]
  31. SIGNATURE [64 Bytes]
  32. The "VERSION" field holds the value [01]. The "CERT_TYPE" field
  33. holds a value depending on the type of certificate. (See appendix
  34. A.1.) The CERTIFIED_KEY field is an Ed25519 public key if
  35. CERT_KEY_TYPE is [01], or a SHA256 hash of some other key type
  36. depending on the value of CERT_KEY_TYPE. The EXPIRATION_DATE is a
  37. date, given in HOURS since the epoch, after which this
  38. certificate isn't valid. (A four-byte field here will work fine
  39. until 10136 A.D.)
  40. The EXTENSIONS field contains zero or more extensions, each of
  41. the format:
  42. ExtLength [2 bytes]
  43. ExtType [1 byte]
  44. ExtFlags [1 byte]
  45. ExtData [ExtLength bytes]
  46. The meaning of the ExtData field in an extension is type-dependent.
  47. The ExtFlags field holds flags; this flag is currently defined:
  48. 1 -- AFFECTS_VALIDATION. If this flag is present, then the
  49. extension affects whether the certificate is valid; clients
  50. must not accept the certificate as valid unless they
  51. understand the extension.
  52. It is an error for an extension to be truncated; such a
  53. certificate is invalid.
  54. Before processing any certificate, parties SHOULD know which
  55. identity key it is supposed to be signed by, and then check the
  56. signature. The signature is formed by signing the first N-64
  57. bytes of the certificate prefixed with the string "Tor node
  58. signing key certificate v1".
  59. 2.2. Basic extensions
  60. 2.2.1. Signed-with-ed25519-key extension [type 04]
  61. In several places, it's desirable to bundle the key signing a
  62. certificate along with the certificate. We do so with this
  63. extension.
  64. ExtLength = 32
  65. ExtData =
  66. An ed25519 key [32 bytes]
  67. When this extension is present, it MUST match the key used to
  68. sign the certificate.
  69. A.1. List of certificate types
  70. The values marked with asterisks are not types corresponding to
  71. the certificate format of section 2.1. Instead, they are
  72. reserved for RSA-signed certificates to avoid conflicts between
  73. the certificate type enumeration of the CERTS cell and the
  74. certificate type enumeration of in our Ed25519 certificates.
  75. **[00],[01],[02],[03] - Reserved to avoid conflict with types used
  76. in CERTS cells.
  77. [04] - Ed25519 signing key with an identity key
  78. (see prop220 section 4.2)
  79. [05] - TLS link certificate signed with ed25519 signing key
  80. (see prop220 section 4.2)
  81. [06] - Ed25519 authentication key signed with ed25519 signing key
  82. (see prop220 section 4.2)
  83. [07] - RSA identity cross-certification
  84. (see prop220 section 4.2)
  85. [0A] - ntor onion key cross-certifying ntor identity key
  86. (see prop228 section 2.3)
  87. A.2. List of extension types
  88. [01] - signed-with-ed25519-key (section 2.2.1)
  89. A.3. List of signature prefixes
  90. We describe various documents as being signed with a prefix. Here
  91. are those prefixes:
  92. "Tor node signing key certificate v1" (section 2.1)
  93. "Tor router descriptor signature v1" (see dir-spec.txt)
  94. A.4. List of certified key types
  95. [01] ed25519 key
  96. [02] SHA256 hash of an RSA key
  97. [03] SHA256 hash of an X.509 certificate