Add documentation page for ACME Profiles

content/base-l10n/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/ca/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/cs/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/da/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/de/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/el/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/en/docs/glossary.md

@@ -128,6 +128,8 @@ Note for translators:
 
 {{% def id="precertificate" name="Precertificate" %}} Precertificates are a part of [Certificate Transparency](#def-CT). A precertificate is a copy of the [certificate](#def-leaf) that a CA intends to issue, with a [critical](#def-critical) poison extension added to prevent the precertificate from being accepted by software in the wild. A CA submits a precertificate to [CT logs](#def-CT-log) in exchange for [SCTs](#def-SCT). Since a precertificate is not identical to its corresponding certificate, Certificate Transparency logs may end up containing both. [RFC 6962 Section 3.1]( https://tools.ietf.org/html/rfc6962#section-3.1) {{% /def %}}
 
+{{% def id="profile" name="Profile" %}} A Profile is a collection of properties which affect both the validation of and final contents of a certificate. See the [profiles documentation](/docs/profiles) for descriptions of each profile, what they affect, and how to select them. {{% /def %}}
+
 {{% def id="HPKP" name="HTTP Public Key Pinning" abbr="HPKP" %}} A security mechanism that asks a browser to require that a site's [certificate chain](#def-chain) use certain public keys on future loads. Chrome introduced this mechanism to protect against CA compromises, but it caused site outages, leading Chrome to [deprecate and remove it](https://groups.google.com/a/chromium.org/forum/#!topic/blink-dev/he9tr7p3rZ8). [Wikipedia](https://en.wikipedia.org/wiki/HTTP_Public_Key_Pinning) {{% /def %}}
 
 {{% def id="PSL" name="Public Suffix List" abbr="PSL" %}} A list of *Public Suffixes* maintained by Mozilla, indicating which Internet domains are available for many separate entities to register subdomains. For instance, the list indicates that both `com` and `co.uk` are Public Suffixes even though `co.uk` is not a TLD. Web browsers use the list, among other things, for preventing sites that are likely operated by different entities from sharing web cookies with one another. [Let's Encrypt](#def-LE) also uses the list for rate-limit calculations: [/docs/rate-limits](/docs/rate-limits). https://publicsuffix.org/ {{% /def %}}

content/en/docs/profiles.md

@@ -0,0 +1,98 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+---
+
+A profile is a collection of characteristics that describe both the validation process required to get a certificate, and the final contents of that certificate. For the vast majority of Let's Encrypt subscribers, you should never have to worry about this: we automatically select the best profile for you, and ensure that it complies with all of the requirements and best practices that govern the Web PKI. But some people might be interested in proactively selecting a specific profile, so this page exists to provide the information necessary to make that choice.
+
+The following validation properties can be controlled by our profiles:
+
+- **Pending Authorization Lifetime:** This is how long an ACME client has to complete a domain control validation challenge. The clock starts when the ACME Authorization object is created (generally as a result of a new Order being created), and is represented by the [`expires` timestamp](https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.4) in the pending Authorization object. This value is restricted to [at most 30 days](https://github.com/cabforum/servercert/blob/main/docs/BR.md#322419-agreed-upon-change-to-website---acme) by the Baseline Requirements.
+
+- **Authorization Reuse Period:** This is how long an already-validated Authorization can be reused by new Orders containing the same identifier. The clock starts when a challenge is successfully fulfilled, and is represented by the [`expires` timestamp](https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.4) in the valid Authorization object. This value is restricted to [at most 398 days](https://github.com/cabforum/servercert/blob/main/docs/BR.md#421-performing-identification-and-authentication-functions) by the Baseline Requirements.
+
+- **Order Lifetime:** This is how long an ACME client has to complete the whole process of ordering a new certificate: placing a new Order, fulfilling any pending Authorizations, and finalizing that Order. The clock starts when the new Order object is created, and is represented by the [`expires` timestamp](https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.3) in the Order object.
+
+The following certificate properties can be controlled by our profiles:
+
+- **Certificate Common Name:** TLS Certificates can contain names (e.g. domain names or IP addresses) in two places: the [Subject Common Name field](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) and the [Subject Alternative Names extension](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.6). The Common Name used to be the most common place to put a domain name, and is displayed by many certificate-parsing tools. However, the Common Name can only hold one name, while many certificates want to contain multiple names (such as "example.com", "www.example.com", and "blog.example.com"). Today, the Common Name is largely redundant, as whatever name is contained in it is required to _also_ be contained in the Subject Alternative Names extension. Including this field in our certificates is now [NOT RECOMMENDED by the Baseline Requirements](https://github.com/cabforum/servercert/blob/main/docs/BR.md#71272-domain-validated).
+
+- **Key Encipherment Key Usage:** TLS Certificates have a ["Key Usage" extension](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3), which determines what sorts of cryptographic operations the key contained in the certificate is allowed to perform. All Let's Encrypt certificates contain the Digital Signature KU, which is necessary to perform TLS handshakes. The Key Encipherment KU was historically required by old versions of TLS to perform certain kinds of handshakes with RSA keys. However, those operations are now known to be insecure, and have been deprecated and removed from browsers for several years now. Including the Key Encipherment key usage is now [NOT RECOMMENDED by the Baseline Requirements](https://github.com/cabforum/servercert/blob/main/docs/BR.md#712711-subscriber-certificate-key-usage).
+
+- **TLS Client Authentication Extended Key Usage:** In addition to the above, TLS Certificates also have an ["Extended Key Usage" extension](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12), which provides an extra layer of granularity to the Key Usage extension described above. The two most common extended key usages are TLS Server Auth (which allows the certificate to be presented by a server during a TLS handshake) and TLS Client Auth (which allows the certificate to be presented by a _client_ during a TLS handshake). The latter is very rare, and root programs are [moving towards](https://www.chromium.org/Home/chromium-security/root-ca-policy/moving-forward-together/#phase-out-multi-purpose-roots-from-the-chrome-root-store) requiring that the TLS Client Auth EKU be omitted from certificates.
+
+- **Subject Key Identifier Extension:** TLS Certificates can have a ["Subject Key Identifier" extension](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.2), which provides a short string that uniquely identifies the public key present in the certificate. This extension is very important for CA certificates, because it allows browsers to quickly find the CA certificate which issued the end-entity certificate being presented by a website. However, the extension serves no purpose in end-entity certificates, and including it is now NOT RECOMMENDED by the Baseline Requirements.
+
+- **Validity Period:** This governs the amount of time between the [`notBefore` and `notAfter` timestamps](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.5) that are embedded in a TLS Certificate, in other words, how long the certificate will be trusted before it expires. This value is restricted to [at most 398 days](https://github.com/cabforum/servercert/blob/main/docs/BR.md#632-certificate-operational-periods-and-key-pair-usage-periods) by the Baseline Requirements.
+
+# Our Profiles
+
+Below are descriptions of each profile, including what effects they have on both the validation process and the contents of the issued certificate. Note that not all profiles are available in all environments: some may be available only in Staging or only in Production, and some may be (temporarily) locked behind an allowlist so we can roll them out slowly. The list of profiles advertised in the ACME Server's `directory` endpoint is the canonical list.
+
+## classic
+
+The classic profile is the default profile selected for all orders which do not request a specific profile. The validation process and resulting certificate are the same as you're used to from the last several years of Let's Encrypt operation. We recommend using this profile for subscribers who are happy to let others try new things first.
+
+| Property | Value |
+| -------- | ----- |
+| Pending Authorization Lifetime | 7 days |
+| Authorization Reuse Period | 30 days |
+| Order Lifetime | 7 days |
+| Certificate Common Name | Yes<sup>*</sup> |
+| Key Encipherment KU | Yes<sup>†</sup> |
+| TLS Client Auth EKU | Yes |
+| Subject Key ID | Yes |
+| Validity Period | 90 days |
+
+<sup>\*</sup>: If the CSR submitted at finalize time requests a specific Common Name, that request is honored. If the the CSR does not request a specific Common Name, the first Subject Alternative Name requested will be promoted into the Subject Common Name. If either the requested name or the to-be-promoted name is too long to fit in the Common Name field (64+ characters), the Common Name will be left empty.
+
+<sup>†</sup>: Only included for certificates with RSA public keys.
+
+## tlsserver
+
+The tlsserver profile is a new profile which updates several of these validation and certificate properties in order to reflect the latest recommendations from the CA/Browser Forum Baseline Requirements, as well as general trends within the WebPKI community. We recommend selecting this profile for subscribers who want smaller certificates and who fully embrace automation.
+
+The pending authorization lifetime has been reduced to further encourage automation: fully automated systems can complete a validation challenge within seconds, so a lifetime of just one hour is more than enough. The authorization reuse period has been reduced to seven hours. This is because the Baseline Requirements require that we re-check Certificate Authority Authorization (CAA) after eight hours, so limiting the reuse period means that we don't have to perform rechecks. The order lifetime has been reduced to the sum of two authorization lifetimes, because there is little purpose to having an order that outlives the authorizations it depends on.
+
+The issued certificate no longer contains any of the fields discussed above. The Common Name has been omitted, as it is redundant with the Subject Alternative Names and is marked as NOT RECOMMENDED by the Baseline Requirements. The Key Encipherment key usage is omitted because it is only relevant when using non-forward-secret TLS cipher suites, which have been removed by all major browsers due to the importance of forward-secrecy. The TLS Client Auth extended key usage is omitted to comply with upcoming root program requirements that require "single-purpose" (i.e. single EKU) certificates. And the Subject Key ID extension is omitted because it serves no purpose in end-entity certificates and is NOT RECOMMENDED by the Baseline Requirements.
+
+| Property | Value |
+| -------- | ----- |
+| Pending Authorization Lifetime | 1 hour |
+| Authorization Reuse Period | 7 hours |
+| Order Lifetime | 8 hours |
+| Certificate Common Name | No |
+| Key Encipherment KU | No |
+| TLS Client Auth EKU | No |
+| Subject Key ID | No |
+| Validity Period | 90 days |
+
+## shortlived
+
+The shortlived profile is identical to the tlsserver profile, with one key distinction: the resulting certificate is only valid for 6ish days. This allows these certificates to qualify as "Short-Lived Subscriber Certificates" under the Baseline Requirements, which means they do not need to contain any revocation information. This makes the certificates even smaller, and removes any possibility of a client accidentally trusting a certificate after it has been revoked.
+
+We recommend this profile for those who fully trust their automation to renew their certificates on time. This profile is not for everyone. Because this profile results in much higher issuance volume (since certificates need to be renewed every few days, instead of every few months), it is currently locked behind an allowlist. If you would like to be placed on the allowlist, please fill out [this form](TODO TKTK XXX).
+
+| Property | Value |
+| -------- | ----- |
+| Pending Authorization Lifetime | 1 hour |
+| Authorization Reuse Period | 7 hours |
+| Order Lifetime | 8 hours |
+| Certificate Common Name | No |
+| Key Encipherment KU | No |
+| TLS Client Auth EKU | No |
+| Subject Key ID | No |
+| Validity Period | 160 hours |
+
+# Selecting a Profile
+
+The process for selecting a profile is described in [this Internet-Draft](https://datatracker.ietf.org/doc/draft-aaron-acme-profiles/), which we plan to work with the IETF ACME Working Group to turn into a full RFC. Not all ACME Clients have implemented this draft, so the client you use may not yet be able to select a profile.
+
+In general, if you want to select a profile, you should:
+
+1. Read your ACME client's documentation to see if it support profile selection, and if it does, how to tell it which profile you want.
+2. Fetch the Let's Encrypt [production](https://acme-v02.api.letsencrypt.org/directory) or [staging](https://acme-staging-v02.api.letsencrypt.org/directory) directory object to see which profiles are available.
+3. Configure your desired profile within your ACME client.

content/es/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/fa/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/fi/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/fr/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/he/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/hr/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/hu/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/id/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/it/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/ja/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/ko/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/pl/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/pt-br/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/ru/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/si/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/sr/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/sv/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/ta/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/th/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/tr/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/uk/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/uz/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+

content/vi/docs/profiles.md

@@ -0,0 +1,9 @@
+---
+title: Profiles
+slug: profiles
+date: 2025-02-05
+lastmod: 2025-02-05
+show_lastmod: false
+untranslated: 1
+---
+