123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179 |
- Ed25519 certificates in Tor
- 1. Scope and Preliminaries
- This document describes a certificate format that Tor uses for
- its Ed25519 internal certificates. It is not the only
- certificate format that Tor uses. For the certificates that
- authorities use for their signing keys, see dir-spec.txt.
- Additionally, Tor uses TLS, which depends on X.509 certificates;
- see tor-spec.txt for details.
- The certificates in this document were first introduced in
- proposal 220, and were first supported by Tor in Tor version
- 0.2.7.2-alpha.
- 1.1. Signing
- All signatures here, unless otherwise specified, are computed
- using an Ed25519 key.
- In order to future-proof the format, before signing anything, the
- signed document is prefixed with a personalization string, which
- will be different in each case.
- 1.2 Integer encoding
- Network byte order (big-endian) is used to encode all integer values
- in Ed25519 certificates unless explicitly specified otherwise.
- 2. Document formats
- 2.1. Ed25519 Certificates
- When generating a signing key, we also generate a certificate for it.
- Unlike the certificates for authorities' signing keys, these
- certificates need to be sent around frequently, in significant
- numbers. So we'll choose a compact representation.
- VERSION [1 Byte]
- CERT_TYPE [1 Byte]
- EXPIRATION_DATE [4 Bytes]
- CERT_KEY_TYPE [1 byte]
- CERTIFIED_KEY [32 Bytes]
- N_EXTENSIONS [1 byte]
- EXTENSIONS [N_EXTENSIONS times]
- SIGNATURE [64 Bytes]
- The "VERSION" field holds the value [01]. The "CERT_TYPE" field
- holds a value depending on the type of certificate. (See appendix
- A.1.) The CERTIFIED_KEY field is an Ed25519 public key if
- CERT_KEY_TYPE is [01], or a SHA256 hash of some other key type
- depending on the value of CERT_KEY_TYPE. The EXPIRATION_DATE is a
- date, given in HOURS since the epoch, after which this
- certificate isn't valid. (A four-byte field here will work fine
- until 10136 A.D.)
- The EXTENSIONS field contains zero or more extensions, each of
- the format:
- ExtLength [2 bytes]
- ExtType [1 byte]
- ExtFlags [1 byte]
- ExtData [ExtLength bytes]
- The meaning of the ExtData field in an extension is type-dependent.
- The ExtFlags field holds flags; this flag is currently defined:
- 1 -- AFFECTS_VALIDATION. If this flag is present, then the
- extension affects whether the certificate is valid; clients
- must not accept the certificate as valid unless they
- understand the extension.
- It is an error for an extension to be truncated; such a
- certificate is invalid.
- Before processing any certificate, parties SHOULD know which
- identity key it is supposed to be signed by, and then check the
- signature. The signature is formed by signing the first N-64
- bytes of the certificate.
- 2.2. Basic extensions
- 2.2.1. Signed-with-ed25519-key extension [type 04]
- In several places, it's desirable to bundle the key signing a
- certificate along with the certificate. We do so with this
- extension.
- ExtLength = 32
- ExtData =
- An ed25519 key [32 bytes]
- When this extension is present, it MUST match the key used to
- sign the certificate.
- 2.3. RSA->Ed25519 cross-certificate
- Certificate type [07] (Cross-certification of Ed25519 identity
- with RSA key) contains the following data:
- ED25519_KEY [32 bytes]
- EXPIRATION_DATE [4 bytes]
- SIGLEN [1 byte]
- SIGNATURE [SIGLEN bytes]
- Here, the Ed25519 identity key is signed with router's RSA
- identity key, to indicate that authenticating with a key
- certified by the Ed25519 key counts as certifying with RSA
- identity key. (The signature is computed on the SHA256 hash of
- the non-signature parts of the certificate, prefixed with the
- string "Tor TLS RSA/Ed25519 cross-certificate".)
- This certificate type is used to mean, "This Ed25519 identity key
- acts with the authority of the RSA key that signed this
- certificate."
- A.1. List of certificate types
- The values marked with asterisks are not types corresponding to
- the certificate format of section 2.1. Instead, they are
- reserved for RSA-signed certificates to avoid conflicts between
- the certificate type enumeration of the CERTS cell and the
- certificate type enumeration of in our Ed25519 certificates.
- **[00],[01],[02],[03] - Reserved to avoid conflict with types used
- in CERTS cells.
- [04] - Ed25519 signing key with an identity key
- (see prop220 section 4.2)
- [05] - TLS link certificate signed with ed25519 signing key
- (see prop220 section 4.2)
- [06] - Ed25519 authentication key signed with ed25519 signing key
- (see prop220 section 4.2)
- **[07] - Reserved for RSA identity cross-certification;
- (see section 2.3 above, and tor-spec.txt section 4.2)
- [08] - Onion service: short-term descriptor signing key, signed
- with blinded public key.
- (See rend-spec-v3.txt, section [DESC_OUTER])
- [09] - Onion service: intro point authentication key, cross-certifying the
- descriptor signing key.
- (See rend-spec-v3.txt, description of "auth-key")
- [0A] - ntor onion key cross-certifying ed25519 identity key
- (see dir-spec.txt, description of "ntor-onion-key-crosscert")
- [0B] - Onion service: ntor-extra encryption key, cross-certifying
- descriptor signing key.
- (see rend-spec-v3.txt, description of "enc-key-cert")
- A.2. List of extension types
- [01] - signed-with-ed25519-key (section 2.2.1)
- A.3. List of signature prefixes
- We describe various documents as being signed with a prefix. Here
- are those prefixes:
- "Tor router descriptor signature v1" (see dir-spec.txt)
- A.4. List of certified key types
- [01] ed25519 key
- [02] SHA256 hash of an RSA key
- [03] SHA256 hash of an X.509 certificate
- [08] short-term HS descriptor signing key, signed with blinded public key (rend-spec-v3.txt)
- [09] intro point authentication key, cross-certifying the HS descriptor
- signing key (rend-spec-v3.txt)
- [0B] ed25519 key derived from the curve25519 intro point encryption key,
- cross-certifying the HS descriptor signing key (rend-spec-v3.txt)
|