RFC 9115
An Automatic Certificate Management Environment (ACME) Profile for Generating Delegated Certificates
RFC 9115: An Automatic Certificate Management Environment (ACME) Profile for Generating Delegated Certificates 🎀
- Who wrote it: Y. Sheffer (Intuit), D. López (Telefonica I+D), A. Pastor Perales (Telefonica I+D), and T. Fossati (ARM) 💜
- Published by: the Internet Engineering Task Force (IETF) 🌸
- Category: Standards Track, so this is an official Internet standard 👑
- ISSN: 2070-1721
- Date: September 2021 🍓
- Obsoletes and Updates: the title block doesn't list either one, so this RFC doesn't name any other RFC as obsoleted or updated 🧚
Abstract 🦋
Okay so this document defines a profile of the Automatic Certificate Management Environment (ACME) protocol ✨ It lets the holder of an identifier (like a domain name) let a third party get an X.509 certificate. The certificate's subject is the delegated identifier, but the public key inside it matches a private key that the third party controls 🔐
The main use case is a Content Delivery Network (CDN), which is the third party, terminating TLS sessions for a content provider (the holder of the domain name). The big win is that the holder keeps control over the delegation and can revoke it at any time 💅 And importantly, this mechanism doesn't require any modification to the deployed TLS clients and servers 🫶
Status of This Memo 📜
This is an Internet Standards Track document. 🌈
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9115.
Copyright Notice ©️
Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Table of Contents 📚
1. Introduction
1.1. Terminology
1.2. Conventions Used in This Document
2. Protocol Flow
2.1. Preconditions
2.2. Overview
2.3. Delegated Identity Profile
2.3.1. Delegation Configuration
2.3.2. Order Object Transmitted from NDC to IdO and to ACME
Server (STAR)
2.3.3. Order Object Transmitted from NDC to IdO and to ACME
Server (Non-STAR)
2.3.4. Capability Discovery
2.3.5. Negotiating an Unauthenticated GET
2.3.6. Terminating the Delegation
2.4. Proxy Behavior
3. CA Behavior
4. CSR Template
4.1. Template Syntax
4.2. Example
5. Further Use Cases
5.1. CDN Interconnection (CDNI)
5.1.1. Multiple Parallel Delegates
5.1.2. Chained Delegation
5.2. Secure Telephone Identity Revisited (STIR)
6. IANA Considerations
6.1. New Fields in the "meta" Object within a Directory Object
6.2. New Fields in the Order Object
6.3. New Fields in the Account Object
6.4. New Error Types
6.5. CSR Template Extensions
7. Security Considerations
7.1. Trust Model
7.2. Delegation Security Goal
7.3. New ACME Channels
7.4. Restricting CDNs to the Delegation Mechanism
8. References
8.1. Normative References
8.2. Informative References
Appendix A. CSR Template: CDDL
Appendix B. CSR Template: JSON Schema
Acknowledgements
Authors' Addresses1. Introduction ✨
Heads up bestie: this document is related to [RFC8739], because some important use cases need both documents implemented. To avoid repeating ourselves, we only give a bare-bones version of the motivation here. For the full story, check the introductory sections of [RFC8739] 📖
An Identifier Owner (IdO) has agreements in place with one or more Name Delegation Consumers (NDCs) so they can use and attest its identity 🫶
In the primary use case, the IdO is a content provider, and a Content Delivery Network (CDN) provider has been contracted to serve the content over HTTPS 🌐 The CDN terminates the HTTPS connection at one of its edge cache servers. It has to show its clients (browsers, mobile apps, set-top boxes) a certificate whose name matches the domain name in the requested URL, which is the IdO's domain 💖 Honestly, some IdOs are going to balk at sharing their long-term private keys with another organization, and delegates would rather not be stuck handling other parties' long-term secrets 🙈 Other relevant use cases are covered in Section 5.
This document describes a profile of the ACME protocol [RFC8555]. It lets the NDC ask the IdO, acting as a profiled ACME server, for a certificate for a delegated identity, meaning one that belongs to the IdO 🦋 The IdO then uses the ACME protocol (with the extensions described in [RFC8739]) to request issuance of a Short-Term, Automatically Renewed (STAR) certificate for that same delegated identity ✨ The short-term certificate is automatically renewed by the ACME Certification Authority (CA), gets periodically fetched by the NDC, and is used to terminate HTTPS connections in place of the IdO. The IdO can end the delegation at any time by just telling the CA to stop the automatic renewal, and then the certificate expires shortly after 🍃
While the primary use case is delegating STAR certificates, this mechanism also works for long-lived certificates managed with the ACME protocol 💜 The biggest difference between the two is how the delegation gets terminated. For long-lived certificates, the IdO uses the "revokeCert" URL exposed by the CA and waits for the explicit revocation, based on the Certificate Revocation List (CRL) and Online Certificate Status Protocol (OCSP), to propagate to the relying parties 🕰️
If the delegated identity is a domain name, this document also gives the NDC a way to tell the IdO about the CNAME mappings that need to be installed in the IdO's DNS zone. That lets the aliasing of the delegated name happen, so the whole name delegation workflow can run through a single interface 🎀
We also note that other standardization efforts tackle certificate delegation for TLS connections, specifically [TLS-SUBCERTS] and [MGLT-LURK-TLS13]. The former extends the TLS certificate chain with a customer-owned signing certificate. The latter splits the server's private key off into a dedicated, more-secure component. Compared to those approaches, this document doesn't require changes to the TLS network stack of the client or the server, and it doesn't add any extra latency to the TLS connection 🚀
1.1. Terminology 📝
IdO: Identifier Owner, the holder (current owner) of an identifier, like a domain name, that needs to be delegated. Depending on context, IdO can also refer to the (profiled) ACME server deployed by the Identifier Owner, or to the ACME client the Identifier Owner uses to interact with the CA.NDC: Name Delegation Consumer, the entity that the domain name gets delegated to for a limited time. In the primary use case this is a CDN (readers may notice the two abbreviations look alike 👀). Depending on context, NDC can also refer to the (profiled) ACME client used by the Name Delegation Consumer.CDN: Content Delivery Network, a widely distributed network that serves the domain's web content to a wide audience at high performance.STAR: Short-Term, Automatically Renewed, as applied to X.509 certificates.ACME: Automated Certificate Management Environment, a certificate management protocol [RFC8555].CA: Certification Authority, specifically one that implements the ACME protocol. In this document, the term is synonymous with "ACME server deployed by the Certification Authority".CSR: Certificate Signing Request, specifically a PKCS#10 [RFC2986] Certificate Signing Request, as supported by ACME.FQDN: Fully Qualified Domain Name.
1.2. Conventions Used in This Document 🌸
Here's the important bit about how to read the requirement words 🤓 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. So if you see them in lowercase, they're just normal words, not requirements 💅
2. Protocol Flow 🌊
This section presents the protocol flow. For completeness, we include the ACME profile proposed in this document as well as the ACME STAR protocol described in [RFC8739] 🧚
2.1. Preconditions 🎀
The protocol assumes the following preconditions are met:
- The IdO exposes an ACME server interface to the NDC(s), including the account management interface.
- The NDC has registered an ACME account with the IdO.
- The NDC and IdO have agreed on a "CSR template" to use, including at a minimum: subject name (e.g.,
abc.ido.example), requested algorithms and key length, key usage, and extensions. The NDC will use this template for every CSR created under the same delegation. - The IdO has registered an ACME account with the Certification Authority (CA).
Note that even if the IdO implements the ACME server role, it is not acting as a CA. From the point of view of the certificate issuance process, the IdO only works as a "policing" forwarder of the NDC's key pair, and it's responsible for completing the identity verification process towards the CA 🕵️♀️ That's a lot of responsibility, but the IdO totally has it handled 👑
2.2. Overview ✨
okay so quick heads up, this overview is mostly about the main thing this protocol does: delegating STAR certificates 🎀 (the short-lived ones!). Non-STAR certificates work pretty similarly, and the differences get spelled out in the sections that follow 💅
The NDC and the IdO talk through a profiled ACME workflow, which lives in Section 2.3 🦋 The IdO and the CA are governed by ACME [RFC8555], ACME STAR [RFC8739], and any other ACME extension that applies (e.g., [TOKEN-TNAUTHLIST] for Secure Telephone Identity Revisited (STIR)) 💜
Here's the full combined STAR flow for the bullet-point version (Figure 1) 🌸:
- NDC sends an Order1 for the delegated identifier to IdO.
- IdO creates an Order1 resource in the
readystate, with afinalizeURL. ✨ - NDC immediately sends a
finalizerequest (which includes the CSR) to the IdO. - IdO checks the CSR against the agreed upon CSR template.
- If the CSR check fails, Order1 goes to
invalidand everything stops 💀 - If the CSR check passes, IdO moves Order1 to
processingand sends a brand new Order2 (using its own account) for the delegated identifier to the CA. - If the ACME STAR protocol fails, Order2 goes to
invalid, and that same state gets mirrored in Order1 (aka the NDC Order). - If the ACME STAR run succeeds (so Order2 is
valid), IdO copies thestar-certificateURL from Order2 over to Order1 and flips Order1 tovalid🔥
Once that's done, the NDC can grab the short-term certificate with the delegated name, install it, and use it 🫶 The STAR certificate is good until it expires, and when it does, the NDC is guaranteed to have a fresh one waiting to be downloaded, installed, and used. This keeps going with each new certificate until either Order1 expires or the IdO decides to cancel the auto-renewal with the CA. Iconic cycle, honestly 👑
Note that the interactive identifier authorization phase from Section 7.5 of [RFC8555] gets skipped on the NDC-IdO side 🙈 That's because the delegated identity in the CSR that the NDC hands to the IdO gets checked against the configured CSR template (Section 4.1). So the NDC sends its finalize request, CSR and all, to the IdO right after Order1 has been acknowledged. The IdO SHALL buffer a (valid) CSR until the Validation phase completes successfully.
Also, the unauthenticated GET from Section 3.4 of [RFC8739] needs to work out, because that's how the NDC gets to read the star-certificate URL on the CA. No GET, no cert, no vibes ✨
.------. .---------------. .------.
| NDC | | IdO | | ACME |
+--------+ +--------+--------+ +--------+
| Client | | Server | Client | | Server |
'---+----' '----+---+---+----' '----+---'
| | | |
| Order1 | | |
| Signature | | |
o------------------->| | |
| | | |
| [ No identity ] | | |
| [ validation via ] | | |
| [ authorizations ] | | |
| | | |
| CSR | | |
| Signature | | |
o------------------->| | |
| Acknowledgement | | Order2 |
|<-------------------o | Signature |
| | o------------------->|
| | | Required |
| | | Authorizations |
| | |<-------------------o
| | | Responses |
| | | Signature |
| | o------------------->|
| | | |
| | |<~~~~Validation~~~~>|
| | | |
| | | CSR |
| | | Signature |
| | o------------------->|
| | | Acknowledgement |
| | |<-------------------o
| | | |
|<~~Await issuance~->| |<~~Await issuance~~>|
| |
| (unauthenticated) GET STAR certificate |
o------------------------------------------------>|
| Certificate #1 |
|<------------------------------------------------o
| (unauthenticated) GET STAR certificate |
o------------------------------------------------>|
| Certificate #2 |
|<------------------------------------------------o
| [...] |
| (unauthenticated) GET STAR certificate |
o------------------------------------------------>|
| Certificate #n |
|<------------------------------------------------o
Figure 1: End-to-End STAR Delegation Flow2.3. Delegated Identity Profile 💖
This section defines a profile of the ACME protocol to be used between the NDC and IdO. It's the rulebook for their little chat 🧚
2.3.1. Delegation Configuration 🌈
The IdO must be preconfigured to recognize one or more NDCs and hand them the details about the certificate delegations that apply to each one 💅
2.3.1.1. Account Object Extensions
An NDC shows up to the IdO as an ACME account. The IdO can delegate multiple names to a single NDC, and those setups get described through "delegation" objects hanging off that NDC's account object on the IdO 🦋
As Figure 2 shows, the ACME account resource on the IdO gets a new delegations attribute:
delegations (required, string): A URL where you can fetch a list of the delegations configured for this account (Section 2.3.1.3) using a POST-as-GET request.
{
"status": "valid",
"contact": [
"mailto:delegation-admin@ido.example"
],
"termsOfServiceAgreed": true,
"orders": "https://example.com/acme/orders/saHpfB",
"delegations": "https://acme.ido.example/acme/delegations/adFqoz"
}Figure 2: Example Account Object with Delegations
2.3.1.2. Delegation Lists
Every account object has a delegations URL that gives you the list of delegation configs the IdO made, again through a POST-as-GET request. The response MUST be a JSON object where the delegations field is an array of URLs, and each URL points to a delegation configuration that's available to the NDC account (Section 2.3.1.3). The server MAY send back an incomplete list, and if it does, it'll include a Link header field with a next link relation that tells you where to find the rest 🧠
HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://acme.ido.example/acme/directory>;rel="index"
Link: <https://acme.ido.example/acme/delegations/adFqoz?/
cursor=2>;rel="next"
{
"delegations": [
"https://acme.ido.example/acme/delegation/ogfr8EcolOT",
"https://acme.ido.example/acme/delegation/wSi5Lbb61E4",
/* more URLs not shown for example brevity */
"https://acme.ido.example/acme/delegation/gm0wfLYHBen"
]
}Quick note on that example: the second Link URL got split across two lines purely so it'd fit on the page 🙈 The actual URL is https://acme.ido.example/acme/delegations/adFqoz?cursor=2.
2.3.1.3. Delegation Objects
This profile adds a new read-only delegation object to the ACME resource model. It represents a delegation configuration that applies to a given NDC, and honestly it's giving main character energy 👑
A delegation object holds the CSR template (see Section 4) that applies to that delegation and, if you want, any related CNAME mapping for the delegated identifiers. Here's how it's laid out:
csr-template (required, object): The CSR template, as defined in Section 4.
cname-map (optional, object): A map of FQDN pairs. In each pair, the name is the delegated identifier, and the value is the matching NDC name that gets aliased in the IdO's zone file so resolvers get redirected to the delegated entity. Both names and values MUST be FQDNs with a terminating '.'. This field only means something for identifiers of type "dns" 🍓
Figure 3 has an example delegation object in JSON:
{
"csr-template": {
"keyTypes": [
{
"PublicKeyType": "id-ecPublicKey",
"namedCurve": "secp256r1",
"SignatureType": "ecdsa-with-SHA256"
}
],
"subject": {
"country": "CA",
"stateOrProvince": "**",
"locality": "**"
},
"extensions": {
"subjectAltName": {
"DNS": [
"abc.ido.example"
]
},
"keyUsage": [
"digitalSignature"
],
"extendedKeyUsage": [
"serverAuth"
]
}
},
"cname-map": {
"abc.ido.example.": "abc.ndc.example."
}
}Figure 3: Example Delegation Configuration Object
Now, to say which delegation applies to a certificate request, the order object on the NDC-IdO side gets a new delegation attribute (see Figures 4 and 7) ✨ Its value is the URL of the delegation configuration object to use for that certificate request. If the delegation attribute in the order object has a URL that doesn't match a configuration the requesting ACME account can access, the IdO MUST return an error response with status code 403 (Forbidden), along with a problem document [RFC7807] whose type is urn:ietf:params:acme:error:unknownDelegation 🥺
2.3.2. Order Object Transmitted from NDC to IdO and to ACME Server (STAR) 🎀
okay bestie, this is the STAR version, so the NDC has to build a request that's fully loaded for auto-renewal 💅 If the delegation is for a STAR certificate, the request object the NDC creates:
- MUST have a
"delegation"attribute pointing at the preconfigured delegation that applies to this Order 🦋 - MUST have entries in the
"identifiers"field for each delegated name present in the configuration 🌸 - MUST NOT contain the
"notBefore"and"notAfter"fields 🙈 - MUST contain an
"auto-renewal"object, and inside it the fields listed in Section 3.1.1 of [RFC8739]. In particular, the"allow-certificate-get"attribute MUST be present and set to true ✨
Here's what that looks like on the wire 👀
POST /acme/new-order HTTP/1.1
Host: acme.ido.example
Content-Type: application/jose+json
{
"protected": base64url({
"alg": "ES256",
"kid": "https://acme.ido.example/acme/acct/evOfKhNU60wg",
"nonce": "Alc00Ap6Rt7GMkEl3L1JX5",
"url": "https://acme.ido.example/acme/new-order"
}),
"payload": base64url({
"identifiers": [
{
"type": "dns",
"value": "abc.ido.example"
}
],
"auto-renewal": {
"end-date": "2021-04-20T00:00:00Z",
"lifetime": 345600, // 4 days
"allow-certificate-get": true
},
"delegation":
"https://acme.ido.example/acme/delegation/gm0wfLYHBen"
}),
"signature": "g454e3hdBlkT4AEw...nKePnUyZTjGtXZ6H"
}Figure 4: New STAR Order from NDC
Now the IdO makes its own order object, and it's giving very specific energy 💖 The order object that is created on the IdO:
- MUST start in the
"ready"state 🍓 - MUST contain an
"authorizations"array with zero elements 🧚 - MUST contain the indicated
"delegation"configuration 💜 - MUST contain the indicated
"auto-renewal"settings ⭐ - MUST NOT contain the
"notBefore"and"notAfter"fields 💀
{
"status": "ready",
"expires": "2021-05-01T00:00:00Z",
"identifiers": [
{
"type": "dns",
"value": "abc.ido.example"
}
],
"auto-renewal": {
"end-date": "2021-04-20T00:00:00Z",
"lifetime": 345600,
"allow-certificate-get": true
},
"delegation":
"https://acme.ido.example/acme/delegation/gm0wfLYHBen",
"authorizations": [],
"finalize": "https://acme.ido.example/acme/order/TO8rfgo/finalize"
}Figure 5: STAR Order Resource Created on IdO
Next up, the NDC finalizes the Order by sending over the CSR with the delegated identifiers 🫶 The IdO checks that CSR against the template in the "delegation" object that applies to this request, as described in Section 4.1. If the CSR fails validation for any of the identifiers, the IdO MUST return an error response with status code 403 (Forbidden) and an appropriate type, e.g., "rejectedIdentifier" or "badCSR". The error response SHOULD contain subproblems (Section 6.7.1 of [RFC8555]) for each failed identifier 🔥 If the CSR passes, the order status moves to "processing" and the twin ACME protocol instance kicks off on the IdO-CA side ✨
The request object the IdO creates (the one heading to the CA) is also a little picky 💅 The request object created by the IdO:
- MUST copy the identifiers sent by the NDC 🌈
- MUST strip the
"delegation"attribute 🙈 - MUST carry a copy of the
"auto-renewal"object sent by the NDC 🎀
Once the identifiers' authorization is done and the CA has issued the certificate, the IdO does two things. When the identifiers' authorization has been successfully completed and the certificate has been issued by the CA, the IdO:
- MUST move its Order resource status to
"valid"and - MUST copy the
"star-certificate"field from the STAR Order returned by the CA into its Order resource. When dereferenced, the"star-certificate"URL includes (via the"Cert-Not-Before"and"Cert-Not-After"HTTP header fields) the renewal timers needed by the NDC to inform its certificate reload logic 🦋
{
"status": "valid",
"expires": "2021-05-01T00:00:00Z",
"identifiers": [
{
"type": "dns",
"value": "abc.ido.example"
}
],
"auto-renewal": {
"end-date": "2021-04-20T00:00:00Z",
"lifetime": 345600,
"allow-certificate-get": true
},
"delegation":
"https://acme.ido.example/acme/delegation/gm0wfLYHBen",
"authorizations": [],
"finalize": "https://acme.ido.example/acme/order/TO8rfgo/finalize",
"star-certificate": "https://acme.ca.example/acme/order/yTr23sSDg9"
}Figure 6: STAR Order Resource Updated on IdO
Now for the big catch 🙈 This whole delegation thing only works if the NDC can grab certificates on a schedule with an unauthenticated HTTP GET. The NDC usually doesn't have an account on the CA, so it can't send the usual POST-as-GET ACME request. That means the IdO SHOULD check the CA's directory object (as per Section 3.4 of [RFC8739]) to confirm the selected CA supports unauthenticated GET before it forwards the Order request. If the CA doesn't support unauthenticated GET of STAR certificates, the IdO MUST NOT forward the Order request. Instead, it MUST move the Order status to "invalid" and set "allow-certificate-get" in the "auto-renewal" object to "false". Same deal if the Order gets forwarded but the CA doesn't reflect the "allow-certificate-get" setting in its Order resource 💀 The combo of "invalid" status plus denied "allow-certificate-get" at the IdO is a clear, unambiguous (asynchronous) signal to the NDC about why it failed ✨
2.3.2.1. CNAME Installation 🌸
If one of the objects in the "identifiers" list is of type "dns", the IdO can add the CNAME records specified in the "delegation" object to its zone. For example:
abc.ido.example. CNAME abc.ndc.example.2.3.3. Order Object Transmitted from NDC to IdO and to ACME Server (Non-STAR) 🧚
Now the non-STAR version, which is the simpler sibling 💖 If the delegation is for a non-STAR certificate, the request object the NDC creates:
- MUST have a
"delegation"attribute pointing at the preconfigured delegation that applies to this Order 🦋 - MUST have entries in the
"identifiers"field for each delegated name present in the configuration; and - MUST have the
"allow-certificate-get"attribute set to true 🍓
POST /acme/new-order HTTP/1.1
Host: acme.ido.example
Content-Type: application/jose+json
{
"protected": base64url({
"alg": "ES256",
"kid": "https://acme.ido.example/acme/acct/evOfKhNU60wg",
"nonce": "IYBkoQfaCS80UcCn9qH8Gt",
"url": "https://acme.ido.example/acme/new-order"
}),
"payload": base64url({
"identifiers": [
{
"type": "dns",
"value": "abc.ido.example"
}
],
"delegation":
"https://acme.ido.example/acme/delegation/gm0wfLYHBen",
"allow-certificate-get": true
}),
"signature": "j9JBUvMigi4zodud...acYkEKaa8gqWyZ6H"
}Figure 7: New Non-STAR Order from NDC
The order object the IdO creates for this one:
- MUST start in the
"ready"state 🌈 - MUST contain an
"authorizations"array with zero elements 🎀 - MUST contain the indicated
"delegation"configuration; and - MUST contain the indicated
"allow-certificate-get"setting 💜
{
"status": "ready",
"expires": "2021-05-01T00:00:00Z",
"identifiers": [
{
"type": "dns",
"value": "abc.ido.example"
}
],
"delegation":
"https://acme.ido.example/acme/delegation/gm0wfLYHBen",
"allow-certificate-get": true,
"authorizations": [],
"finalize": "https://acme.ido.example/acme/order/3ZDlhYy/finalize"
}Figure 8: Non-STAR Order Resource Created on IdO
Finalization by the NDC and the CSR validation by the IdO go exactly like the STAR case 🫶 If the CSR passes, the order status moves to "processing" and the twin ACME protocol instance starts on the IdO-CA side.
The request object the IdO creates:
- MUST copy the identifiers sent by the NDC ✨
- MUST strip the
"delegation"attribute 💅 - MUST copy the
"allow-certificate-get"attribute 🦋
When the identifiers' authorization is done and the CA issues the certificate, the IdO:
- MUST move its Order resource status to
"valid"and - MUST copy the
"certificate"field from the Order returned by the CA into its Order resource, as well as"notBefore"and"notAfter"if these fields exist 🌸
{
"status": "valid",
"expires": "2021-05-01T00:00:00Z",
"identifiers": [
{
"type": "dns",
"value": "abc.ido.example"
}
],
"delegation":
"https://acme.ido.example/acme/delegation/gm0wfLYHBen",
"allow-certificate-get": true,
"authorizations": [],
"finalize": "https://acme.ido.example/acme/order/3ZDlhYy/finalize",
"certificate": "https://acme.ca.example/acme/order/YtR23SsdG9"
}Figure 9: Non-STAR Order Resource Updated on IdO
At this point in the flow, the same considerations as in Section 2.3.2.1 apply 🎀
Before the IdO forwards the Order request to the CA, it SHOULD confirm that the selected CA supports unauthenticated GET. It does this by checking the relevant settings in the CA's directory object, as per Section 2.3.5. If the CA doesn't support unauthenticated GET of certificate resources, the IdO MUST NOT forward the Order request. Instead, it MUST move the Order status to "invalid" and set the "allow-certificate-get" attribute to "false". The same thing happens if the Order request does get forwarded and the CA doesn't reflect the "allow-certificate-get" setting in its Order resource. The combo of "invalid" status and denied "allow-certificate-get" in the Order resource at the IdO is an unambiguous (asynchronous) signal to the NDC about the failure reason 🔥
2.3.4. Capability Discovery 🔍
To help a client find out whether this profile is supported, the directory object of an ACME server (usually one the IdO deploys) includes the following attribute in the "meta" field:
delegation-enabled (optional, boolean): Boolean flag indicating support for the profile specified in this memo. An ACME server that supports this delegation profile MUST include this key and MUST set it to true 💖
The IdO MUST declare its support for delegation using "delegation-enabled", no matter whether it supports delegation of STAR certificates, non-STAR certificates, or both 🌈
And to help a client discover support for certificate fetching with unauthenticated HTTP GET, the directory object of an ACME server (usually one the CA deploys) includes the following attribute in the "meta" field:
allow-certificate-get (optional, boolean): See Section 2.3.5. 🧚
2.3.5. Negotiating an Unauthenticated GET 🔓✨
okay so bestie, this part is about letting non-STAR certificates be delegated too 💅. The trick is a little handshake where the server says "yep, I'll let anyone GET my cert" and the client says "cool, I want that for this Order" 🫶. It's giving trust, but make it per-Order 🦋.
Heads up, this is basically the same vibe as Section 3.4 of [RFC8739] for STAR, same names and same meanings 🌸. The only difference is the cert lives on the certificate resource, not the star-certificate resource. ALSO the placement is different. Instead of hiding everything inside an "auto-renewal" subobject like STAR does, these attributes just chill at the top level 💜.
The server flags that it's down to grant unauthenticated access by setting "allow-certificate-get" to "true" in the "meta" field of the directory object 🍓:
allow-certificate-get (optional, boolean): If this field is present
and set to "true", the server allows GET (and HEAD) requests to
certificate URLs.Then the client says it wants that same access by adding an "allow-certificate-get" attribute to its newOrder payload and setting it to "true" 🧚:
allow-certificate-get (optional, boolean): If this field is present
and set to "true", the client requests the server to allow
unauthenticated GET (and HEAD) to the certificate associated with
this Order.If the server accepts, it MUST reflect the attribute setting in the resulting order object 📝. That's the non-negotiable part, periodt 💀.
Also, even when unauthenticated GET has been agreed on, the server MUST also allow POST-as-GET requests to the certificate resource 🔥. So the unauthenticated lane doesn't replace the authenticated one, it just sits next to it 👑.
2.3.6. Terminating the Delegation 🥀
okay, the ending of a delegation is different depending on whether it's a STAR certificate or not 🌈. Let's break it down ✨.
2.3.6.1. By Cancellation (STAR) 🛑
The IdO can end the delegation of a STAR certificate by asking for its cancellation (see Section 3.1.2 of [RFC8739]) 💖.
Cancellation of the ACME STAR certificate is the IdO's main character move 👑. The NDC doesn't own the relevant account key on the CA, so it can't send a cancellation request for the STAR cert 🙈. It could technically ask to revoke a single STAR cert, since it holds that cert's private key 😭. BUT STAR explicitly disables the revokeCert interface, so, not me… 💅.
Once the IdO stops the automatic renewal, the last issued STAR cert expires shortly after and the delegation is over 🦋.
2.3.6.2. By Revocation (Non-STAR) 🧨
For non-STAR certs, the IdO can end the delegation by asking for the cert to be revoked using the "revokeCert" URL exposed by the CA 💜.
According to Section 7.6 of [RFC8555], the revocation endpoint can be used with either the account key pair or the certificate key pair 🔑. So an NDC that finds the CA's "revokeCert" URL (it's publicly available in the CA's directory object) could revoke the cert using the associated private key 👀. BUT, given the trust relationship between the NDC and IdO that the delegation trust model expects (Section 7.1), plus the lack of incentive for the NDC to end the delegation early, this isn't a significant security risk 🫶✨.
2.4. Proxy Behavior 🔀
There are cases where the ACME Delegation flow should be proxied, like the use case in Section 5.1.2 🌸. This section explains how those proxies behave 🧚.
An entity playing the IdO server role (an "ACME Delegation server") may, per identity, either act as a proxy into another ACME Delegation server or act as an IdO and get a cert directly 🦋. The deciding factor is whether it can get successfully authorized by the next-hop ACME server for the identity tied to the cert request 🔥.
The identities each server supports, and the disposition for each one, are preconfigured 📝.
Here's what the proxy does for each message in the ACME Delegation process 💅:
New-order request:
- The complete
"identifiers"attribute MUST be copied as is 💖. - Similarly, the
"auto-renewal"object MUST be copied as is 🌈.
New-order response:
- The
"status","expires","authorizations","identifiers", and"auto-renewal"attributes/objects MUST be copied as is 🫶. - The
"finalize"URL is rewritten so the"finalize"request goes to the proxy 🔁. - Similarly, the
"Location"header MUST be rewritten to point to an order object on the proxy 📍. - Any
"Link"relations MUST be rewritten to point to the proxy 🔗.
Get Order response:
- The
"status","expires","authorizations","identifiers", and"auto-renewal"attributes/objects MUST be copied as is ✨. - Similarly, the
"star-certificate"URL (or the"certificate"URL for non-STAR requests) MUST be copied as is 🎀. - The
"finalize"URL is rewritten so the"finalize"request goes to the proxy 🔁. - The
"Location"header MUST be rewritten to point to an order object on the proxy 📍. - Any
"Link"relations MUST be rewritten to point to the proxy 🔗.
"finalize" request:
- The CSR MUST be copied as is 📜.
"finalize" response:
- The
"Location"header,"Link"relations, and the"finalize"URLs are rewritten as for Get Order 🦋.
We should note that all the above messages are authenticated, so each proxy must be able to authenticate any subordinate server 🔐. Trust chains, bestie 🫶.
3. CA Behavior 🏛️
okay so, this document (especially Section 2) is mostly about the protocol between the NDC and IdO 💜. BUT the protocol also affects the ACME server running in the CA 🧚.
A CA that wants to support certificate delegation MUST also support unauthenticated certificate fetching 🔓. It declares that using "allow-certificate-get" (Section 2.3.5, Paragraph 3) 📣. No CA left behind 💅.
4. CSR Template 📜💖
The CSR template is how the shape of the CSR the NDC uses to request the certificate gets expressed and constrained 🎀. The same CSR is used for every certificate created under the same delegation 🔁. Its validation by the IdO is a critical piece of the security of the whole delegation mechanism 🔐, so no slacking 😤.
Instead of defining every possible CSR attribute, this document keeps it minimalist 🌸. It only declares the minimum attribute set and leaves registering more specific attributes to future documents 🦋.
4.1. Template Syntax ✍️
The template is a JSON document 🧾. Each field (except "keyTypes", which we'll get to) means one of these three things 💅:
- A mandatory field where the template gives the literal value of that field. This is shown as a literal string, like
"abc.ido.example"📍. - A mandatory field where the client defines the content. This is shown as
"**"🫶. - An optional field where the client decides whether the field is included in the CSR and, if so, what its value is. This is shown as
"*"🎀.
The NDC MUST NOT include any fields in the CSR, including any extensions, unless they're specified in the template 🚫. Strict, but that's the vibe 💀.
The structure of the template object is defined by the Concise Data Definition Language (CDDL) [RFC8610] document in Appendix A 📚. There's also an alternative, nonnormative JSON Schema syntax in Appendix B 🧩. The CSR template has to follow the syntax defined here, but neither the IdO nor the NDC is expected to validate it at runtime 🙃.
The "subject" field and its subfields get mapped into the "subject" field of the CSR, as per Section 4.1.2.6 of [RFC5280] 🗺️. Other extension fields of the CSR template get mapped into the CSR according to the table in Section 6.5 📊.
The "subjectAltName" field is currently defined for these identifiers: DNS names, email addresses, and URIs 🌐. New identifier types may be added later by documents that extend this spec 🔮. Each new identifier type SHALL have an associated identifier validation challenge that the CA can use to get proof of the requester's control over it 🔑. That's a must-have, bestie.
The "keyTypes" property isn't copied into the CSR 🙅. Instead, it constrains the "SubjectPublicKeyInfo" field of the CSR, which MUST have the type/size defined by one of the array members of the "keyTypes" property 🔑✨.
When the IdO receives the CSR, it MUST verify that the CSR is consistent with the template in the "delegation" object referenced in the Order 🕵️♀️. The IdO MAY enforce additional constraints, like restricting field lengths 📏. Also, a "subjectAltName" of type "DNS" can use wildcard notation, which means the NDC can be required ("**") or offered the option ("*") to define the delegated domain name itself 🌸. If that's the case, the IdO MUST apply application-specific checks on top of the control rules the CSR template already provides, so the requested domain name is legit under its local policy 🔥👑.
4.2. Example 🎀
The CSR template in Figure 10 is one possible CSR template governing the delegation exchanges in the rest of this document 💖.
{
"keyTypes": [
{
"PublicKeyType": "rsaEncryption",
"PublicKeyLength": 2048,
"SignatureType": "sha256WithRSAEncryption"
},
{
"PublicKeyType": "id-ecPublicKey",
"namedCurve": "secp256r1",
"SignatureType": "ecdsa-with-SHA256"
}
],
"subject": {
"country": "CA",
"stateOrProvince": "**",
"locality": "**"
},
"extensions": {
"subjectAltName": {
"DNS": [
"abc.ido.example"
]
},
"keyUsage": [
"digitalSignature"
],
"extendedKeyUsage": [
"serverAuth",
"clientAuth"
]
}
}Figure 10: Example CSR Template 🧾
5. Further Use Cases 🌈
This nonnormative section covers more use cases that implement STAR certificate delegation in nontrivial ways 🧩.
5.1. CDN Interconnection (CDNI) 🌐
[HTTPS-DELEGATION] talks through several solutions for different delegation requirements in the CDN Interconnection (CDNI) environment 📖. This section covers two of those requirements in the context of the STAR delegation workflow ✨.
This section uses CDNI terminology, like Upstream CDN (uCDN) and Downstream (dCDN), as defined in [RFC7336] 💜.
5.1.1. Multiple Parallel Delegates 👯♀️
Sometimes the content owner (IdO) wants to delegate authority over a website to multiple NDCs (CDNs) 🍓. This could happen if the IdO has agreements with different regional CDNs for different geographic regions, or if a "backup" CDN handles overflow traffic by temporarily changing some of the CNAME mappings in place 🔁. The STAR delegation flow makes this use case work naturally 🦋, since each CDN can authenticate separately to the IdO (through its own separate account), specify its CSR, and the IdO is free to allow or deny each certificate request according to its own policy 👑💅.
5.1.2. Chained Delegation 🔗✨
okay so bestie, this one is a whole vibe 💅 a content owner (IdO) delegates some domains to a big CDN (uCDN), and that big CDN turns around and delegates to a smaller regional CDN (dCDN) 🌸 the IdO has a contract with uCDN, and uCDN has a similar contract with dCDN, but the IdO may not even know dCDN exists 🙈 the way that works, lowkey messy but iconic 👑
if it's needed, the STAR protocol can be chained to make this work 🦋 uCDN could forward requests from dCDN over to IdO and then forward the responses back down to dCDN 🎀 whether that kind of proxying is allowed is totally up to policy and the contracts between everyone 📜
there also has to be a mechanism at the uCDN-to-dCDN interface 💜 so uCDN can advertise:
- the names that dCDN is allowed to use, and
- the policy for making the key material (allowed algorithms, minimum key lengths, key usage, etc.) that dCDN has to meet 🔐
and ngl, the CSR template is the thing that provides that mechanism 💖
5.1.2.1. Two-Level Delegation in CDNI 🌈
okay picture this 🧚 a User Agent (UA), like a browser or a set-top box, wants to fetch the video at https://video.cp.example/movie. the redirection between the content provider (CP) and the upstream and downstream CDNs is set up as a CNAME-based aliasing chain, shown in Figure 11 🦋
.------------.
video.cp.example ? | .-----. |
.---------------------------------->| | |
| (a) | | DNS | CP |
| .-------------------------------+ | |
| | CNAME video.ucdn.example | '-----' |
| | '------------'
| |
| |
.-----------|---v--. .------------.
| .-----.-+-----. | video.ucdn.example ? | .-----. |
| | | +----------------------------->| | |
| UA | TLS | DNS | | (b) | | DNS | uCDN |
| | | |<-----------------------------+ | |
| '--+--'-----+-' | CNAME video.dcdn.example | '-----' |
'------|----^---|--' '------------'
| | |
| | |
| | | .------------.
| | | video.dcdn.example ? | .-----. |
| | '------------------------------>| | |
| | (c) | | DNS | |
| '-----------------------------------+ | |
| A 192.0.2.1 | +-----+ dCDN |
| | | | |
'--------------------------------------->| TLS | |
SNI: video.cp.example | | | |
| '-----' |
'------------'
Figure 11: DNS Redirectionso here's the spicy part 🌶️ with HTTP-based redirection, the original URL gets swapped out for whatever is in the "Location" header of the 302 response. but DNS redirection is totally transparent to the User Agent 🫥 which means the TLS connection to the dCDN edge uses a Server Name Indication (SNI) equal to the "host" in the original URI. in this example, that's "video.cp.example" 😭 so to actually finish the handshake, the landing dCDN node has to be configured with a certificate whose "subjectAltName" field matches "video.cp.example", which is a content provider's name 💀
Figure 12 shows the cascaded delegation flow that lets dCDN get a STAR certificate with a name belonging to the content provider, while the private key is only known to dCDN 🔑✨ slay 👑
.--------------------.
| .------.------. |
| | STAR | ACME |<-------------.
| CP | dele | STAR | | |
| | srv | cli +-----. |
| '---+--'------' | | 6
'---------|------^---' 5 |
| | | .--|-------.
| | | | .-+----. |
7 | '---->| ACME | |
| | | | STAR | C |
| 4 | +------| A |
| | | | HTTP | |
| | | '----+-' |
| .-' '--^--|----'
.--------------v--|--. | |
| .------.----+-. | | 10
| | | STAR | | | |
| uCDN | CDNI | dele | | | |
| | | fwd | | | |
| '----+-'-+----' | | |
'-------^--|---|--^--' | |
| | | | | |
| 2 8 | | |
1 | | 3 | |
| | | | 9 |
.-------|--v---v--|---------. | |
| .-+----.----+-.------. | | |
| | | STAR | +------------' |
| dCDN | CDNI | dele | HTTP | | |
| | | cli | |<--------------'
| '------'------'------' |
'---------------------------'
Figure 12: Two-Level Delegation in CDNIthe setup here is that uCDN is configured to delegate to dCDN, and CP is configured to delegate to uCDN, both as defined in Section 2.3.1 🎀 and then the flow goes like this:
- dCDN requests CDNI path metadata from uCDN 📨
- uCDN replies with, among other CDNI metadata, the STAR delegation configuration, which includes the delegated content provider's name 🗂️
- dCDN creates a key pair and the CSR with the delegated name, then places an order for that name with uCDN 🔐
- uCDN forwards the received order to the content provider (CP) 🚀
- CP creates an order for a STAR certificate and sends it to the CA. the order also asks for unauthenticated access to the certificate resource 🙌
- once all the authorizations finish successfully, the STAR certificate gets issued 🎉
- CP lets uCDN know the STAR certificate is ready at the order's "star-certificate" URL 📣
- uCDN passes that info along to dCDN, and at this point the ACME signaling is complete ✅
- dCDN grabs the STAR certificate with an unauthenticated GET from the CA 🏃♀️
- the CA sends back the certificate, and now dCDN is fully set up to handle HTTPS traffic in place of the content provider 💖
note that steps 9 and 10 keep repeating until the delegation expires or gets terminated 🔁⏳
5.2. Secure Telephone Identity Revisited (STIR) 📞
okay second use case, and this one is about delegating credentials in the STIR ecosystem [RFC9060] 💅
this section uses STIR terminology. the Personal Assertion Token (PASSporT) is defined in [RFC8225], and "TNAuthList" is defined in [RFC8226] 🎀
so in STIR delegated mode, a service provider SP2 (the NDC) needs to sign PASSporTs [RFC8225] for telephone numbers (e.g., TN=+123) that belong to another service provider, SP1 (the IdO) 📱 to pull that off, SP2 needs a STIR certificate and a private key that includes TN=+123 in the TNAuthList [RFC8226] certificate extension 🔑
here's the step-by-step (Figure 13) 🦋
- SP1 and SP2 agree on the configuration of the delegation, especially the CSR template that applies 🤝
- SP2 generates a private/public key pair and sends a CSR to SP1. it requests a certificate with an SP1 name, an SP2 public key, and a TNAuthList extension listing the TNs that SP1 delegates to SP2 📝 (heads up: the CSR SP2 sends to SP1 needs to be validated against the CSR template agreed on in step 1.)
- SP1 sends an order for the CSR to the CA. the order also asks for unauthenticated access to the certificate resource 📬
- after the required TNAuthList authorizations succeed, the CA moves the order to a "valid" state, and at the same time the star-certificate endpoint gets populated 🎊
- the contents of the order get forwarded from SP1 to SP2 through the paired "delegation" order 🔁
- SP2 dereferences the "star-certificate" URL in the order to fetch the rolling STAR certificate with the delegated identifiers 🏃♀️
- the STAR certificate is returned to SP2 🎁
.-------------------.
| .------.------. |
| | STAR | STAR |<--------------.
.-->| SP1 | dele | dele | | |
| | | srv | cli +-----. |
| | '----+-'------' | | 4
| '------^--|---------' 3 |
| | | | | .----|-----.
| | | 5 | | .---+--. |
| | | | '--->| ACME | |
| | | | | | STAR | C |
1 | | | | +------| A |
| | 2 | | | | HTTP | |
| | | | | | '---+--' |
| | .------|--v---------. 6 '----|-----'
| | | .-+----.------. | | 7
| | | | STAR | +-----' |
'-->| SP2 | dele | HTTP | | |
| | cli | |<--------------'
| '----+-'-+----' |
'-------------------'
Figure 13: Delegation in STIRso the STAR delegation profile in this document applies straightforwardly 🌟 the only extra requirement is being able to tell the NDC which TNAuthList values are allowed, and that can be done with a simple extension to the CSR template 💜
6. IANA Considerations 🌸
6.1. New Fields in the "meta" Object within a Directory Object 🧁
this document adds the following entries to the "ACME Directory Metadata Fields" registry 📋
+=======================+============+===========+
| Field Name | Field Type | Reference |
+=======================+============+===========+
| delegation-enabled | boolean | RFC 9115 |
+-----------------------+------------+-----------+
| allow-certificate-get | boolean | RFC 9115 |
+-----------------------+------------+-----------+
Table 16.2. New Fields in the Order Object 🎀
this document adds the following entries to the "ACME Order Object Fields" registry 📋✨
+=======================+============+==============+===========+
| Field Name | Field Type | Configurable | Reference |
+=======================+============+==============+===========+
| allow-certificate-get | boolean | true | RFC 9115 |
+-----------------------+------------+--------------+-----------+
| delegation | string | true | RFC 9115 |
+-----------------------+------------+--------------+-----------+
Table 26.3. New Fields in the Account Object 💅
Okay bestie, this section adds one new entry to the "ACME Account Object Fields" registry 🦋 Here's the table, and yes it's giving formal, but the info is so good ✨
+=============+============+==========+===========+
| Field Name | Field Type | Requests | Reference |
+=============+============+==========+===========+
| delegations | string | none | RFC 9115 |
+-------------+------------+----------+-----------+
Table 3Lowkey the important bit is that the delegations field only gets reported by ACME servers that have delegation-enabled set to true in their meta Object 🫶
6.4. New Error Types 🚨
This one adds entries to the "ACME Error Types" registry, and the new error is literally called unknownDelegation 💀 It shows up when an unknown configuration is listed in the "delegation" attribute of the order request. Here's the table:
+===================+================================+===========+
| Type | Description | Reference |
+===================+================================+===========+
| unknownDelegation | An unknown configuration is | RFC 9115 |
| | listed in the "delegation" | |
| | attribute of the order request | |
+-------------------+--------------------------------+-----------+
Table 46.5. CSR Template Extensions 🎀
IANA set up a brand new registry called "STAR Delegation CSR Template Extensions", and the registration procedure is "Specification Required". Main character energy for sure 👑
Every extension that gets registered has to spell out three things:
- an extension name,
- an extension syntax, as a reference to a CDDL document that defines this extension, and
- the extension's mapping into an X.509 certificate extension.
The starting contents of this registry are the extensions defined by the CDDL in Appendix A. Check out the table, it's so organized 🌸
+==================+===========+===============================+
| Extension Name | Extension | Mapping to X.509 Certificate |
| | Syntax | Extension |
+==================+===========+===============================+
| keyUsage | See | [RFC5280], Section 4.2.1.3 |
| | Appendix | |
| | A | |
+------------------+-----------+-------------------------------+
| extendedKeyUsage | See | [RFC5280], Section 4.2.1.12 |
| | Appendix | |
| | A | |
+------------------+-----------+-------------------------------+
| subjectAltName | See | [RFC5280], Section 4.2.1.6 |
| | Appendix | (note that only specific name |
| | A | formats are allowed: URI, DNS |
| | | name, email address) |
+------------------+-----------+-------------------------------+
Table 5When the designated expert is checking a request for something in this registry, they should follow this guidance:
- The definition must include a full CDDL definition, which the expert will validate.
- The definition must include both positive and negative test cases.
- Additional requirements that are not captured by the CDDL definition are allowed but must be explicitly specified.
7. Security Considerations 🔐
Okay this part is SERIOUS, so read it slowly bestie 🙈 The security stuff is the whole reason delegation has to be done carefully.
7.1. Trust Model 🤝
The ACME trust model needs to be extended to cover the trust relationship between NDC and IdO. Once that trust link is set up, it can potentially turn recursive 🌀 That means there has to be a trust relationship between every node in the delegation chain. For example, with cascading CDNs, this is contractually defined.
When you're using standard [RFC6125] identity verification, the IdO has no mechanisms to restrict use of the delegated name once it's been handed over to the first NDC. So contractual measures are expected to be in place to get some assurance that redelegation isn't happening. Scary but important 😭
7.2. Delegation Security Goal 🎯
Delegation brings in a new security goal: only an NDC that has been authorized by the IdO, either directly or transitively, can get a certificate with an IdO identity. Iconic goal honestly 💜
From a security point of view, the delegation process has five separate parts:
- enabling a specific third party (the intended NDC) to submit requests for delegated certificates
- making sure that any request for a delegated certificate matches the intended "shape" in terms of delegated identities as well as any other certificate metadata, e.g., key length, x.509 extensions, etc.
- serving the certificate back to the NDC
- handling revocation of the delegation
- handling revocation of the certificate itself
The first part is covered by the NDC's ACME account, which the IdO administers. Its security relies on the correct handling of the associated key pair 🔑 When a compromise of the private key is detected, the delegate MUST use the account deactivation procedures defined in Section 7.3.6 of [RFC8555]. Non-negotiable, periodt 💅
The second part is covered by checking an NDC's certificate request against the intended CSR template. Shaping the CSR template correctly, picking the right CSR template to check against the presented CSR, and making sure the presented CSR matches the selected CSR template are all security relevant 🧚
The third part builds on the trust relationship between NDC and IdO, which is responsible for correctly forwarding the certificate URL from the Order returned by the CA 🦋
The fourth part is about the IdO's ability to unilaterally remove the "delegation" object tied to the revoked identity. That blocks any further NDC requests for that identity 🚫 Note that in more extreme circumstances, the IdO might decide to disable the NDC account, which blocks all further interaction.
The fifth part is covered by two different mechanisms, depending on the kind of certificate. For STAR, the IdO shall use the cancellation interface defined in Section 2.3 of [RFC8739]. For non-STAR, the certificate revocation interface defined in Section 7.6 of [RFC8555]) is used.
The ACME account tied to the delegation plays a crucial role in the overall security of the protocol 👑 That means that, in delegation scenarios, the security requirements and verification for an ACME account may be more stringent than in base ACME deployments. The reason is that out-of-band configuration of the delegations an account is allowed to use (combined with account authentication) takes the place of the normal ACME authorization challenge procedures. So the IdO MUST ensure that each account is associated with the exact policies (via their matching "delegation" objects) that define which domain names can be delegated to the account and how. The IdO is expected to use out-of-band means to preregister each NDC to the corresponding account 🫶
7.3. New ACME Channels 📡
Using the model established in Section 10.1 of [RFC8555], we can break down the interactions of the basic delegation workflow, as shown in Figure 14. Picture time 🎀
.-----. ACME Channel .--------.
| NDC +------------->| IdO |
'--+--' | server |
| '--o-----'
| |
| | ACME Channel
| | .------------>-------------.
| | | |
| .--o--+--. .--+---.
| | IdO | | CA |
| | client | '--+-+-'
| '-----+--' | |
| '-----------<--------------' |
| Validation Channel |
'-------------------->-------------------------------'
(subset of) ACME Channel [1]
[1] Unauthenticated certificate fetch and non-STAR certificate
revocation.
Figure 14: Delegation Channels TopologyThe security considerations for the ACME Channel and Validation Channel from [RFC8555] apply verbatim to the IdO-CA leg. The same goes for the ACME Channel on the NDC-IdO leg. The ACME Channel between the NDC and CA is a bit different, since it's a subset of the ACME interface with two API endpoints: unauthenticated certificate retrieval and, potentially, non-STAR revocation via certificate private key. No specific security considerations apply to the former, but the privacy considerations in Section 6.3 of [RFC8739] do. For the latter, there's currently no way for an IdO to disable authorizing revocation based on certificate private keys. So, in theory, an NDC could use the revocation API directly with the CA, bypassing the IdO 😬 The NDC SHOULD NOT directly use the revocation interface exposed by the CA unless failing to do so would compromise the overall security. For example, that would be the case if the certificate private key is compromised and the IdO is not currently reachable.
All other security considerations from [RFC8555] and [RFC8739] apply as is to the delegation topology ✨
7.4. Restricting CDNs to the Delegation Mechanism 🛡️
When a website is delegated to a CDN, the CDN can in principle modify the website at will, e.g., create and remove pages. That means a malicious or breached CDN can pass the ACME (as well as common non-ACME) HTTPS-based validation challenges and generate a certificate for the site 💀 This is true whether or not the CNAME mechanisms defined in the current document are used.
In some cases this is the desired behavior, because the domain holder trusts the CDN to have full control of the cryptographic credentials for the site. But this document assumes a scenario where the domain holder only wants to delegate restricted control, and wants to keep the ability to cancel the CDN's credentials at short notice 🦋
Here's a possible mitigation for when the IdO wants to make sure a rogue CDN can't issue unauthorized certificates:
- The domain holder makes sure that the CDN cannot modify the DNS records for the domain. The domain holder should ensure it is the only entity authorized to modify the DNS zone. Typically, it establishes a CNAME resource record from a subdomain into a CDN-managed domain.
- The domain holder uses a Certification Authority Authorization (CAA) record [RFC8659] to restrict certificate issuance for the domain to specific CAs that comply with ACME and are known to implement [RFC8657].
- The domain holder uses the ACME-specific CAA mechanism [RFC8657] to restrict issuance to a specific CA account that is controlled by it, and MUST require
dns-01as the sole validation method.
We should note that the solution above may need tweaking depending on the exact capabilities and authorization flows the selected CA supports. Also, this mitigation may be bypassed if a malicious or misconfigured CA doesn't comply with CAA restrictions 🙃
8. References 📚
8.1. Normative References 📚
Okay bestie, these are the normative references, which means the stuff you actually need to have read to get the spec. 💅
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. - [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification Request Syntax Specification Version 1.7", RFC 2986, DOI 10.17487/RFC2986, November 2000,
<https://www.rfc-editor.org/info/rfc2986>. - [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/info/rfc5280>. - [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
<https://www.rfc-editor.org/info/rfc7807>. - [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017,
<https://www.rfc-editor.org/info/rfc8174>. - [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. Kasten, "Automatic Certificate Management Environment (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019,
<https://www.rfc-editor.org/info/rfc8555>. - [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019,
<https://www.rfc-editor.org/info/rfc8610>. - [RFC8739] Sheffer, Y., Lopez, D., Gonzalez de Dios, O., Pastor Perales, A., and T. Fossati, "Support for Short-Term, Automatically Renewed (STAR) Certificates in the Automated Certificate Management Environment (ACME)", RFC 8739, DOI 10.17487/RFC8739, March 2020,
<https://www.rfc-editor.org/info/rfc8739>.
8.2. Informative References 🦋
These ones are the extra-credit reading, the bonus content that gives you more context but isn't required to build the thing. 🧚
- [HTTPS-DELEGATION] Fieau, F., Stephan, E., and S. Mishra, "CDNI extensions for HTTPS delegation", Work in Progress, Internet-Draft, draft-ietf-cdni-interfaces-https-delegation-06, 10 September 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-cdni-interfaces-https-delegation-06>. - [json-schema-07] Wright, A., Andrews, H., and B. Hutton, "JSON Schema Validation: A Vocabulary for Structural Validation of JSON", Work in Progress, Internet-Draft, draft-handrews-json-schema-validation-02, 17 September 2019,
<https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-validation-02>. - [MGLT-LURK-TLS13] Migault, D., "LURK Extension version 1 for (D)TLS 1.3 Authentication", Work in Progress, Internet-Draft, draft-mglt-lurk-tls13-05, 26 July 2021,
<https://datatracker.ietf.org/doc/html/draft-mglt-lurk-tls13-05>. - [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2011,
<https://www.rfc-editor.org/info/rfc6125>. - [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, Ed., "Framework for Content Distribution Network Interconnection (CDNI)", RFC 7336, DOI 10.17487/RFC7336, August 2014,
<https://www.rfc-editor.org/info/rfc7336>. - [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion Token", RFC 8225, DOI 10.17487/RFC8225, February 2018,
<https://www.rfc-editor.org/info/rfc8225>. - [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity Credentials: Certificates", RFC 8226, DOI 10.17487/RFC8226, February 2018,
<https://www.rfc-editor.org/info/rfc8226>. - [RFC8657] Landau, H., "Certification Authority Authorization (CAA) Record Extensions for Account URI and Automatic Certificate Management Environment (ACME) Method Binding", RFC 8657, DOI 10.17487/RFC8657, November 2019,
<https://www.rfc-editor.org/info/rfc8657>. - [RFC8659] Hallam-Baker, P., Stradling, R., and J. Hoffman-Andrews, "DNS Certification Authority Authorization (CAA) Resource Record", RFC 8659, DOI 10.17487/RFC8659, November 2019,
<https://www.rfc-editor.org/info/rfc8659>. - [RFC9060] Peterson, J., "Secure Telephone Identity Revisited (STIR) Certificate Delegation", RFC 9060, DOI 10.17487/RFC9060, September 2021,
<https://www.rfc-editor.org/info/rfc9060>. - [TLS-SUBCERTS] Barnes, R., Iyengar, S., Sullivan, N., and E. Rescorla, "Delegated Credentials for TLS", Work in Progress, Internet-Draft, draft-ietf-tls-subcerts-10, 24 January 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-tls-subcerts-10>. - [TOKEN-TNAUTHLIST] Wendt, C., Hancock, D., Barnes, M., and J. Peterson, "TNAuthList profile of ACME Authority Token", Work in Progress, Internet-Draft, draft-ietf-acme-authority-token-tnauthlist-08, 27 March 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-acme-authority-token-tnauthlist-08>.
Appendix A. CSR Template: CDDL ✨
Here's the official CDDL definition of the CSR template [RFC8610], so this is the source of truth, no cap 💖 The CSR template MUST be a valid JSON document that is compliant with the syntax defined here.
Some constraints just can't be written in CDDL, so they're a separate vibe check. These MUST be validated by the recipient, including:
- the value of each "subjectAltName" entry is compatible with its type and
- the parameters in each "keyTypes" entry form an acceptable combination.
csr-template-schema = {
keyTypes: [ + $keyType ]
? subject: non-empty<distinguishedName>
extensions: extensions
}
non-empty<M> = (M) .and ({ + any => any })
mandatory-wildcard = "**"
optional-wildcard = "*"
wildcard = mandatory-wildcard / optional-wildcard
; regtext matches all text strings but "*" and "**"
regtext = text .regexp "([^\*].*)|([\*][^\*].*)|([\*][\*].+)"
regtext-or-wildcard = regtext / wildcard
distinguishedName = {
? country: regtext-or-wildcard
? stateOrProvince: regtext-or-wildcard
? locality: regtext-or-wildcard
? organization: regtext-or-wildcard
? organizationalUnit: regtext-or-wildcard
? emailAddress: regtext-or-wildcard
? commonName: regtext-or-wildcard
}
$keyType /= rsaKeyType
$keyType /= ecdsaKeyType
rsaKeyType = {
PublicKeyType: "rsaEncryption" ; OID: 1.2.840.113549.1.1.1
PublicKeyLength: rsaKeySize
SignatureType: $rsaSignatureType
}
rsaKeySize = uint
; RSASSA-PKCS1-v1_5 with SHA-256
$rsaSignatureType /= "sha256WithRSAEncryption"
; RSASSA-PCKS1-v1_5 with SHA-384
$rsaSignatureType /= "sha384WithRSAEncryption"
; RSASSA-PCKS1-v1_5 with SHA-512
$rsaSignatureType /= "sha512WithRSAEncryption"
; RSASSA-PSS with SHA-256, MGF-1 with SHA-256, and a 32 byte salt
$rsaSignatureType /= "sha256WithRSAandMGF1"
; RSASSA-PSS with SHA-384, MGF-1 with SHA-384, and a 48 byte salt
$rsaSignatureType /= "sha384WithRSAandMGF1"
; RSASSA-PSS with SHA-512, MGF-1 with SHA-512, and a 64 byte salt
$rsaSignatureType /= "sha512WithRSAandMGF1"
ecdsaKeyType = {
PublicKeyType: "id-ecPublicKey" ; OID: 1.2.840.10045.2.1
namedCurve: $ecdsaCurve
SignatureType: $ecdsaSignatureType
}
$ecdsaCurve /= "secp256r1" ; OID: 1.2.840.10045.3.1.7
$ecdsaCurve /= "secp384r1" ; OID: 1.3.132.0.34
$ecdsaCurve /= "secp521r1" ; OID: 1.3.132.0.3
$ecdsaSignatureType /= "ecdsa-with-SHA256" ; paired with secp256r1
$ecdsaSignatureType /= "ecdsa-with-SHA384" ; paired with secp384r1
$ecdsaSignatureType /= "ecdsa-with-SHA512" ; paired with secp521r1
subjectaltname = {
? DNS: [ + regtext-or-wildcard ]
? Email: [ + regtext ]
? URI: [ + regtext ]
* $$subjectaltname-extension
}
extensions = {
? keyUsage: [ + keyUsageType ]
? extendedKeyUsage: [ + extendedKeyUsageType ]
subjectAltName: non-empty<subjectaltname>
}
keyUsageType /= "digitalSignature"
keyUsageType /= "nonRepudiation"
keyUsageType /= "keyEncipherment"
keyUsageType /= "dataEncipherment"
keyUsageType /= "keyAgreement"
keyUsageType /= "keyCertSign"
keyUsageType /= "cRLSign"
keyUsageType /= "encipherOnly"
keyUsageType /= "decipherOnly"
extendedKeyUsageType /= "serverAuth"
extendedKeyUsageType /= "clientAuth"
extendedKeyUsageType /= "codeSigning"
extendedKeyUsageType /= "emailProtection"
extendedKeyUsageType /= "timeStamping"
extendedKeyUsageType /= "OCSPSigning"
extendedKeyUsageType /= oid
oid = text .regexp "([0-2])((\.0)|(\.[1-9][0-9]*))*"Appendix B. CSR Template: JSON Schema 🎀
Okay so this appendix is a bonus, an alternative way to write down the CSR template as a JSON Schema 🧚 It's nonnormative, which means it's a helpful reference and not the official rulebook. The schema is written in draft 7 of JSON Schema, documented in [json-schema-07]. Heads up: later drafts of this (now-expired) version describe later versions of the JSON Schema syntax. At the time of writing, there isn't a stable reference for this syntax yet, so the team went with the draft version, which tool implementations support best 💅
The same considerations about additional constraints checking that we covered in Appendix A apply here too, so don't skip that bit bestie 🙈
{
"title": "JSON Schema for the STAR Delegation CSR template",
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://ietf.org/acme/drafts/star-delegation/csr-template",
"$defs": {
"distinguished-name": {
"$id": "#distinguished-name",
"type": "object",
"minProperties": 1,
"properties": {
"country": {
"type": "string"
},
"stateOrProvince": {
"type": "string"
},
"locality": {
"type": "string"
},
"organization": {
"type": "string"
},
"organizationalUnit": {
"type": "string"
},
"emailAddress": {
"type": "string"
},
"commonName": {
"type": "string"
}
},
"additionalProperties": false
},
"rsaKeyType": {
"$id": "#rsaKeyType",
"type": "object",
"properties": {
"PublicKeyType": {
"type": "string",
"const": "rsaEncryption"
},
"PublicKeyLength": {
"type": "integer"
},
"SignatureType": {
"type": "string",
"enum": [
"sha256WithRSAEncryption",
"sha384WithRSAEncryption",
"sha512WithRSAEncryption",
"sha256WithRSAandMGF1",
"sha384WithRSAandMGF1",
"sha512WithRSAandMGF1"
]
}
},
"required": [
"PublicKeyType",
"PublicKeyLength",
"SignatureType"
],
"additionalProperties": false
},
"ecdsaKeyType": {
"$id": "#ecdsaKeyType",
"type": "object",
"properties": {
"PublicKeyType": {
"type": "string",
"const": "id-ecPublicKey"
},
"namedCurve": {
"type": "string",
"enum": [
"secp256r1",
"secp384r1",
"secp521r1"
]
},
"SignatureType": {
"type": "string",
"enum": [
"ecdsa-with-SHA256",
"ecdsa-with-SHA384",
"ecdsa-with-SHA512"
]
}
},
"required": [
"PublicKeyType",
"namedCurve",
"SignatureType"
],
"additionalProperties": false
}
},
"type": "object",
"properties": {
"keyTypes": {
"type": "array",
"minItems": 1,
"items": {
"anyOf": [
{
"$ref": "#rsaKeyType"
},
{
"$ref": "#ecdsaKeyType"
}
]
}
},
"subject": {
"$ref": "#distinguished-name"
},
"extensions": {
"type": "object",
"properties": {
"keyUsage": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": [
"digitalSignature",
"nonRepudiation",
"keyEncipherment",
"dataEncipherment",
"keyAgreement",
"keyCertSign",
"cRLSign",
"encipherOnly",
"decipherOnly"
]
}
},
"extendedKeyUsage": {
"type": "array",
"minItems": 1,
"items": {
"anyOf": [
{
"type": "string",
"enum": [
"serverAuth",
"clientAuth",
"codeSigning",
"emailProtection",
"timeStamping",
"OCSPSigning"
]
},
{
"type": "string",
"pattern": "^([0-2])((\\.0)|(\\.[1-9][0-9]*))*$",
"description": "Used for OID values"
}
]
}
},
"subjectAltName": {
"type": "object",
"minProperties": 1,
"properties": {
"DNS": {
"type": "array",
"minItems": 1,
"items": {
"anyOf": [
{
"type": "string",
"enum": [
"*",
"**"
]
},
{
"type": "string",
"format": "hostname"
}
]
}
},
"Email": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"format": "email"
}
},
"URI": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"format": "uri"
}
}
},
"additionalProperties": false
}
},
"required": [
"subjectAltName"
],
"additionalProperties": false
}
},
"required": [
"extensions",
"keyTypes"
],
"additionalProperties": false
}Acknowledgements 💖
Huge thank you to the people who helped make this document shine ✨ with their review comments and design proposals: Richard Barnes, Carsten Bormann, Roman Danyliw, Lars Eggert, Frédéric Fieau, Russ Housley, Ben Kaduk, Eric Kline, Sanjay Mishra, Francesca Palombini, Jon Peterson, Ryan Sleevi, Emile Stephan, and Éric Vyncke. You all are literally the best 🫶
This work was partially supported by the European Commission under Horizon 2020 grant agreement no. 688421 Measurement and Architecture for a Middleboxed Internet (MAMI). Quick reminder that this support does not imply endorsement 🌈
Authors' Addresses 🦋
Yaron Sheffer Intuit
Email: yaronf.ietf@gmail.com
Diego López Telefonica I+D
Email: diego.r.lopez@telefonica.com
Antonio Agustín Pastor Perales Telefonica I+D
Email: antonio.pastorperales@telefonica.com
Thomas Fossati ARM
Email: thomas.fossati@arm.com
📦 where this page comes from
- ietf: rfc9115 2021-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms