From 9f56ea8412acb862bc535d7e1f0fa4dc64e5eda5 Mon Sep 17 00:00:00 2001 From: Hayden Blauzvern Date: Fri, 22 Jul 2022 21:55:05 +0000 Subject: [PATCH 1/3] Create certificate specification This outlines what MUST and SHOULD and MAY and SHOULD NOT and MUST NOT be included with CA and end-entity certificates. Signed-off-by: Hayden Blauzvern --- docs/certificate-specification.md | 112 ++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/certificate-specification.md diff --git a/docs/certificate-specification.md b/docs/certificate-specification.md new file mode 100644 index 000000000..5b751c663 --- /dev/null +++ b/docs/certificate-specification.md @@ -0,0 +1,112 @@ +# Certificate Specification + +This document includes the requirements for root, intermediate, and issued certificates. + +## Root Certificate + +A root certificate MUST: + +* Specify a Subject with a common name and organization +* Specify an Issuer with the same values as the Subject +* Specify Key Usages for Certificate Sign and CRL Sign +* Specify Basic Constraints to `CA:TRUE` +* Specify a unique, positive, 160 bit serial number +* Specify a Subject Key Identifier +* Be compliant with [RFC5280](https://datatracker.ietf.org/doc/html/rfc5280) + +A root certificate MUST NOT: + +* Specify other Key Usages besides Certificate Sign and CRL Sign +* Specify any Extended Key Usages + +A root certificate SHOULD: + +* Use the signing algorithm ECDSA NIST P-384 (secp384r1) or stronger, or RSA-4096 +* Have a lifetime that does not require frequent rotation, such as 10 years + +A root certificate MAY: + +* Specify a Basic Constraints path length constraint to prevent additional CA certificates + from being issued beneath the root +* Specify an Authority Key Identifier. If specified, it MUST be the same as the Subject Key Identifier +* Specify other values in the Subject. + +## Intermediate Certificate + +An intermediate certificate MUST: + +* Specify a Subject with a common name and organization +* Specify an Issuer equal to the parent certificate's Subject +* Specify Key Usages for Certificate Sign and CRL Sign +* Specify an Extended Key Usage for Code Signing +* Specify a lifetime that does not exceed the parent certificiate +* Specify Basic Constraints to `CA:TRUE` +* Specify a unique, positive, 160 bit serial number +* Specify a Subject Key Identifier +* Specify an Authority Key Identifier equal to the parent certificate's Subject Key Identifier +* Be compliant with [RFC5280](https://datatracker.ietf.org/doc/html/rfc5280) + +An intermediate certificate MUST NOT: + +* Specify other Key Usages besides Certificate Sign and CRL Sign +* Specify other Extended Key Usages besides Code Signing + +An intermediate certificate SHOULD: + +* Specify a Basic Constraints path length constraint of 0, `pathlen:0`. This limits the intermediate + CA to only issue end-entity certificates +* Use the signing algorithm ECDSA NIST P-384 (secp384r1) or stronger, or RSA-4096 +* Have a lifetime that does not require frequent rotation, such as 3 years + +An intermediate certificate SHOULD NOT: + +* Use a different signature scheme (ECDSA vs RSA) than its parent certificate, as some clients do not support this + +## Issued Certificate + +An issued certificate MUST: + +* Specify a Subject Alternative Name as a critical extension. It MUST be populated by either: + * An email + * A URI +* Specify an Issuer equal to the parent certificate's Subject +* Specify a Key Usage for Digital Signature +* Specify an Extended Key Usage for Code Signing +* Specify a lifetime that does not exceed the parent certificiate +* Specify a unique, positive, 160 bit serial number +* Specify a Subject Key Identifier +* Specify an Authority Key Identifier equal to the parent certificate's Subject Key Identifier +* Specify an empty Subject +* Be compliant with [RFC5280](https://datatracker.ietf.org/doc/html/rfc5280) +* Specify a public key that is either: + * ECDSA NIST P-256, NIST P-384, or NIST P-521 + * RSA of key size 2048 to 4096 (inclusive) with size % 8 = 0, E = 65537, and containing no weak primes + * ED25519 +* Specify the OpenID Connect identity token issuer with OID `1.3.6.1.4.1.57264.1.1` +* Append a precertificate to a Certificate Transparency log, where the precertificate MUST be signed by the certificate authority + and MUST include a poison extension with OID `1.3.6.1.4.1.11129.2.4.3` +* Specify the Signed Certificate Timestamp (SCT) from the Certificate Transparency log with OID `1.3.6.1.4.1.11129.2.4.2` + +An issued certificate MUST NOT: + +* Specify a Subject +* Specify multiple Subject Alternative Name values +* Specify other Key Usages besides Digital Signature +* Specify other Extended Key Usages besides Code Signing + +An issued certificate SHOULD: + +* Use an ephemeral key. A client MAY request a certificate with a long-lived key, but a client MUST + adequately secure the key material + +An issued certificate SHOULD NOT: + +* Use a different public key scheme (ECDSA vs RSA) than its parent certificate, as some clients do not support this +* Specify a public key that is stronger than its parent certificate + +An issued certificate MAY: + +* Specify Basic Constraints to `CA:FALSE` +* Specify values from the OpenID Connect identity token in OIDs prefixed with `1.3.6.1.4.1.57264.1`, + such as values from a GitHub Actions workflow +* Specify multiple SCTs with OID `1.3.6.1.4.1.11129.2.4.2`, denoting that the certificate has been appended to multiple logs \ No newline at end of file From 2ae4012d9ee3b265bbe8828371f8e1f237530cc6 Mon Sep 17 00:00:00 2001 From: Hayden Blauzvern Date: Tue, 26 Jul 2022 05:02:16 +0000 Subject: [PATCH 2/3] Address comments Signed-off-by: Hayden Blauzvern --- docs/certificate-specification.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/certificate-specification.md b/docs/certificate-specification.md index 5b751c663..a326e99c3 100644 --- a/docs/certificate-specification.md +++ b/docs/certificate-specification.md @@ -1,6 +1,11 @@ # Certificate Specification This document includes the requirements for root, intermediate, and issued certificates. +This document applies to all instances of Fulcio, including the production instance and +all private instances using the service defined in this repository. + +The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are +to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). ## Root Certificate @@ -29,7 +34,7 @@ A root certificate MAY: * Specify a Basic Constraints path length constraint to prevent additional CA certificates from being issued beneath the root * Specify an Authority Key Identifier. If specified, it MUST be the same as the Subject Key Identifier -* Specify other values in the Subject. +* Specify other values in the Subject ## Intermediate Certificate @@ -62,11 +67,16 @@ An intermediate certificate SHOULD NOT: * Use a different signature scheme (ECDSA vs RSA) than its parent certificate, as some clients do not support this +An intermediate certificate MAY: + +* Be optional. An end-entity certificate MAY be issued from a root certificate or an intermediate certificate. + Clients MUST be able to verify a chain with any number of intermediate certificates. + ## Issued Certificate An issued certificate MUST: -* Specify a Subject Alternative Name as a critical extension. It MUST be populated by either: +* Specify exactly one Subject Alternative Name, as a critical extension. It MUST be populated by either: * An email * A URI * Specify an Issuer equal to the parent certificate's Subject @@ -83,13 +93,12 @@ An issued certificate MUST: * RSA of key size 2048 to 4096 (inclusive) with size % 8 = 0, E = 65537, and containing no weak primes * ED25519 * Specify the OpenID Connect identity token issuer with OID `1.3.6.1.4.1.57264.1.1` -* Append a precertificate to a Certificate Transparency log, where the precertificate MUST be signed by the certificate authority - and MUST include a poison extension with OID `1.3.6.1.4.1.11129.2.4.3` -* Specify the Signed Certificate Timestamp (SCT) from the Certificate Transparency log with OID `1.3.6.1.4.1.11129.2.4.2` +* Be appended to a Certificate Transparency log. Clients MUST NOT trust certificates that do not present + either a proof of inclusion or a Signed Certificate Timestamp (SCT) An issued certificate MUST NOT: -* Specify a Subject +* Specify a nonempty Subject * Specify multiple Subject Alternative Name values * Specify other Key Usages besides Digital Signature * Specify other Extended Key Usages besides Code Signing @@ -98,6 +107,9 @@ An issued certificate SHOULD: * Use an ephemeral key. A client MAY request a certificate with a long-lived key, but a client MUST adequately secure the key material +* Append a precertificate to a Certificate Transparency log, where the precertificate MUST be signed by the certificate authority + and MUST include a poison extension with OID `1.3.6.1.4.1.11129.2.4.3` +* Specify the Signed Certificate Timestamp (SCT) from the Certificate Transparency log with OID `1.3.6.1.4.1.11129.2.4.2` An issued certificate SHOULD NOT: @@ -109,4 +121,5 @@ An issued certificate MAY: * Specify Basic Constraints to `CA:FALSE` * Specify values from the OpenID Connect identity token in OIDs prefixed with `1.3.6.1.4.1.57264.1`, such as values from a GitHub Actions workflow -* Specify multiple SCTs with OID `1.3.6.1.4.1.11129.2.4.2`, denoting that the certificate has been appended to multiple logs \ No newline at end of file +* Specify multiple SCTs with OID `1.3.6.1.4.1.11129.2.4.2`, denoting that the certificate has been appended to multiple logs +* Specify the Signed Certificate Timestamp (SCT) in a response header `SCT` instead of embedding the SCT in the certificate \ No newline at end of file From 0648fb4ad6de20294ce36b83a691897a05870925 Mon Sep 17 00:00:00 2001 From: Hayden Blauzvern Date: Thu, 4 Aug 2022 23:06:44 +0000 Subject: [PATCH 3/3] Address more comments Signed-off-by: Hayden Blauzvern --- docs/certificate-specification.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/certificate-specification.md b/docs/certificate-specification.md index a326e99c3..364d5aab0 100644 --- a/docs/certificate-specification.md +++ b/docs/certificate-specification.md @@ -15,7 +15,7 @@ A root certificate MUST: * Specify an Issuer with the same values as the Subject * Specify Key Usages for Certificate Sign and CRL Sign * Specify Basic Constraints to `CA:TRUE` -* Specify a unique, positive, 160 bit serial number +* Specify a unique, random, positive, 160 bit serial number according to [RFC5280 4.1.2.2](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.2) * Specify a Subject Key Identifier * Be compliant with [RFC5280](https://datatracker.ietf.org/doc/html/rfc5280) @@ -46,7 +46,7 @@ An intermediate certificate MUST: * Specify an Extended Key Usage for Code Signing * Specify a lifetime that does not exceed the parent certificiate * Specify Basic Constraints to `CA:TRUE` -* Specify a unique, positive, 160 bit serial number +* Specify a unique, random, positive, 160 bit serial number according to [RFC5280 4.1.2.2](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.2) * Specify a Subject Key Identifier * Specify an Authority Key Identifier equal to the parent certificate's Subject Key Identifier * Be compliant with [RFC5280](https://datatracker.ietf.org/doc/html/rfc5280) @@ -83,7 +83,7 @@ An issued certificate MUST: * Specify a Key Usage for Digital Signature * Specify an Extended Key Usage for Code Signing * Specify a lifetime that does not exceed the parent certificiate -* Specify a unique, positive, 160 bit serial number +* Specify a unique, random, positive, 160 bit serial number according to [RFC5280 4.1.2.2](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.2) * Specify a Subject Key Identifier * Specify an Authority Key Identifier equal to the parent certificate's Subject Key Identifier * Specify an empty Subject @@ -92,7 +92,7 @@ An issued certificate MUST: * ECDSA NIST P-256, NIST P-384, or NIST P-521 * RSA of key size 2048 to 4096 (inclusive) with size % 8 = 0, E = 65537, and containing no weak primes * ED25519 -* Specify the OpenID Connect identity token issuer with OID `1.3.6.1.4.1.57264.1.1` +* Specify the OpenID Connect identity token issuer with OID [`1.3.6.1.4.1.57264.1.1`](https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md#1361415726411--issuer) * Be appended to a Certificate Transparency log. Clients MUST NOT trust certificates that do not present either a proof of inclusion or a Signed Certificate Timestamp (SCT) @@ -114,7 +114,8 @@ An issued certificate SHOULD: An issued certificate SHOULD NOT: * Use a different public key scheme (ECDSA vs RSA) than its parent certificate, as some clients do not support this -* Specify a public key that is stronger than its parent certificate +* Specify a public key that is stronger than its parent certificate. As weaknesses in keys are found, an issued + certificate should be weakened before its parent, since once the parent key is compromised, it can issue new certificates. An issued certificate MAY: