RFC 9115 | ACME Delegation | September 2021 |
Sheffer, et al. | Standards Track | [Page] |
This document defines a profile of the Automatic Certificate Management Environment (ACME) protocol by which the holder of an identifier (e.g., a domain name) can allow a third party to obtain an X.509 certificate such that the certificate subject is the delegated identifier while the certified public key corresponds to a private key controlled by the third party. A primary use case is that of a Content Delivery Network (CDN), the third party, terminating TLS sessions on behalf of a content provider (the holder of a domain name). The presented mechanism allows the holder of the identifier to retain control over the delegation and revoke it at any time. Importantly, this mechanism does not require any modification to the deployed TLS clients and servers.¶
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 (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.¶
This document is related to [RFC8739], in that some important use cases require both documents to be implemented. To avoid duplication, we give here a bare-bones description of the motivation for this solution. For more details, please refer to the introductory sections of [RFC8739].¶
An Identifier Owner (IdO) has agreements in place with one or more Name Delegation Consumer (NDC) to use and attest its identity.¶
In the primary use case, the IdO is a content provider, and we consider a Content Delivery Network (CDN) provider contracted to serve the content over HTTPS. The CDN terminates the HTTPS connection at one of its edge cache servers and needs to present its clients (browsers, mobile apps, set-top boxes) a certificate whose name matches the domain name of the URL that is requested, i.e., that of the IdO. Understandably, some IdOs may balk at sharing their long-term private keys with another organization; equally, delegates would rather not have to handle other parties' long-term secrets. Other relevant use cases are discussed in Section 5.¶
This document describes a profile of the ACME protocol [RFC8555] that allows the NDC to request from the IdO, acting as a profiled ACME server, a certificate for a delegated identity -- i.e., one belonging 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 the same delegated identity. The generated short-term certificate is automatically renewed by the ACME Certification Authority (CA), is periodically fetched by the NDC, and is used to terminate HTTPS connections in lieu of the IdO. The IdO can end the delegation at any time by simply instructing the CA to stop the automatic renewal and letting the certificate expire shortly thereafter.¶
While the primary use case we address is a delegation of STAR certificates, the
mechanism proposed here also accommodates long-lived certificates managed with
the ACME protocol. The most noticeable difference between long-lived and STAR
certificates is the way the termination of the delegation is managed. In the
case of 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.¶
In case the delegated identity is a domain name, this document also provides a way for the NDC to inform the IdO about the CNAME mappings that need to be installed in the IdO's DNS zone to enable the aliasing of the delegated name, thus allowing the complete name delegation workflow to be handled using a single interface.¶
We note that other standardization efforts address the problem of 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 separates the server's private key into a dedicated, more-secure component. Compared to these other approaches, the current document does not require changes to the TLS network stack of the client or the server, nor does it introduce additional latency to the TLS connection.¶
Identifier Owner, the holder (current owner) of an identifier (e.g., a domain name) that needs to be delegated. Depending on the context, the term IdO may also be used to designate the (profiled) ACME server deployed by the Identifier Owner or the ACME client used by the Identifier Owner to interact with the CA.¶
Name Delegation Consumer, the entity to which the domain name is delegated for a limited time. This is a CDN in the primary use case (in fact, readers may note the similarity of the two abbreviations). Depending on the context, the term NDC may also be used to designate the (profiled) ACME client used by the Name Delegation Consumer.¶
Content Delivery Network, a widely distributed network that serves the domain's web content to a wide audience at high performance.¶
Short-Term, Automatically Renewed, as applied to X.509 certificates.¶
Automated Certificate Management Environment, a certificate management protocol [RFC8555].¶
Certification Authority, specifically one that implements the ACME protocol. In this document, the term is synonymous with "ACME server deployed by the Certification Authority".¶
Certificate Signing Request, specifically a PKCS#10 [RFC2986] Certificate Signing Request, as supported by ACME.¶
Fully Qualified Domain Name.¶
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.¶
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].¶
The protocol assumes the following preconditions are met:¶
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.¶
Note that even if the IdO implements the ACME server role, it is not acting as a CA; in fact, 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 is responsible for completing the identity verification process towards the CA.¶
For clarity, the protocol overview presented here covers the main use case of this protocol, namely delegation of STAR certificates. Protocol behavior for non-STAR certificates is similar, and the detailed differences are listed in the following sections.¶
The interaction between the NDC and the IdO is governed by the profiled ACME workflow detailed in Section 2.3. The interaction between the IdO and the CA is ruled by ACME [RFC8555], ACME STAR [RFC8739], and any other ACME extension that applies (e.g., [TOKEN-TNAUTHLIST] for Secure Telephone Identity Revisited (STIR)).¶
The outline of the combined protocol for STAR certificates is as follows (Figure 1):¶
ready
with a finalize
URL.¶
finalize
request (which includes the CSR) to the IdO.¶
invalid
state and
everything stops.¶
processing
and sends a new Order2 (using its own account) for the delegated
identifier to the CA.¶
invalid
, and the same state
is reflected in Order1 (i.e., the NDC Order).¶
valid
), IdO copies the
star-certificate
URL from Order2 to Order1 and updates the Order1 state to
valid
.¶
The NDC can now download, install, and use the short-term certificate bearing the name delegated by the IdO. The STAR certificate can be used until it expires, at which time the NDC is guaranteed to find a new certificate it can download, install, and use. This continues with subsequent certificates until either Order1 expires or the IdO decides to cancel the automatic renewal process with the CA.¶
Note that the interactive identifier authorization phase described in Section 7.5 of [RFC8555] is suppressed on the NDC-IdO side because the delegated
identity contained in the CSR presented to the IdO is validated against the
configured CSR template (Section 4.1). Therefore, the NDC
sends the finalize
request, including the CSR, to the IdO immediately after
Order1 has been acknowledged. The IdO SHALL buffer a (valid) CSR until the
Validation phase completes successfully.¶
Also note that the successful negotiation of the unauthenticated GET (Section 3.4 of [RFC8739]) is required in order to allow the NDC to access the
star-certificate
URL on the CA.¶
This section defines a profile of the ACME protocol to be used between the NDC and IdO.¶
The IdO must be preconfigured to recognize one or more NDCs and present them with details about certificate delegations that apply to each one.¶
An NDC identifies itself to the IdO as an ACME account. The IdO can delegate
multiple names to an NDC, and these configurations are described through
delegation
objects associated with the NDC's account object on the IdO.¶
As shown in Figure 2, the ACME account resource on the IdO is
extended with a new delegations
attribute:¶
Each account object includes a delegations
URL from which a list of
delegation configurations created by the IdO can be fetched via a POST-as-GET
request. The result of the request MUST be a JSON object whose delegations
field is an array of URLs, each identifying a delegation configuration made
available to the NDC account (Section 2.3.1.3). The server MAY
return an incomplete list, along with a Link
header field with a next
link
relation indicating where further entries can be acquired.¶
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" ] }¶
Note that in the figure above, https://acme.ido.example/acme/delegations/adFqoz?cursor=2 includes a line break for the sake of presentation.¶
This profile extends the ACME resource model with a new read-only delegation
object that represents a delegation configuration that applies to a given NDC.¶
A delegation
object contains the CSR template (see Section 4) that
applies to that delegation and, optionally, any related CNAME mapping for the
delegated identifiers. Its structure is as follows:¶
dns
.¶
An example delegation
object in JSON format is shown in
Figure 3.¶
In order to indicate which specific delegation applies to the requested
certificate, a new delegation
attribute is added to the
order object on the NDC-IdO side (see Figures 4
and 7). The
value of this attribute is the URL pointing to the delegation configuration
object that is to be used for this certificate request. If the delegation
attribute in the order object contains a URL that does not correspond to a
configuration available to the requesting ACME account, the IdO MUST return an error
response with status code 403 (Forbidden), providing a problem document
[RFC7807] with type urn:ietf:params:acme:error:unknownDelegation
.¶
If the delegation is for a STAR certificate, the request object created by the NDC:¶
delegation
attribute indicating the preconfigured delegation
that applies to this Order;¶
identifiers
field for each delegated name
present in the configuration;¶
notBefore
and notAfter
fields; and¶
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.¶
The order object that is created on the IdO:¶
ready
state;¶
authorizations
array with zero elements;¶
delegation
configuration;¶
auto-renewal
settings; and¶
notBefore
and notAfter
fields.¶
The Order is then finalized by the NDC supplying the CSR containing the
delegated identifiers. The IdO checks the provided CSR against the template
contained 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 is successfully validated, the order
object status moves to processing
and the twin ACME protocol instance is
initiated on the IdO-CA side.¶
The request object created by the IdO:¶
delegation
attribute; and¶
auto-renewal
object sent by the NDC.¶
When the identifiers' authorization has been successfully completed and the certificate has been issued by the CA, the IdO:¶
valid
and¶
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.¶
This delegation protocol is predicated on the NDC being able to fetch
certificates periodically using an unauthenticated HTTP GET, since, in general,
the NDC does not possess an account on the CA; as a consequence, it cannot issue the
standard POST-as-GET ACME request. Therefore, before forwarding the Order
request to the CA, the IdO SHOULD ensure that the selected CA supports
unauthenticated GET by inspecting the relevant settings in the CA's
directory object, as per Section 3.4 of [RFC8739]. If the CA does not
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
the allow-certificate-get
in the auto-renewal
object to false
. The same
occurs in case the Order request is forwarded and the CA does not reflect the
allow-certificate-get
setting in its Order resource. The combination of
invalid
status and denied allow-certificate-get
in the Order resource at
the IdO provides an unambiguous (asynchronous) signal to the NDC about the
failure reason.¶
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.¶
If the delegation is for a non-STAR certificate, the request object created by the NDC:¶
delegation
attribute indicating the preconfigured delegation
that applies to this Order;¶
identifiers
field for each delegated name
present in the configuration; and¶
allow-certificate-get
attribute set to true.¶
The order object that is created on the IdO:¶
ready
state;¶
authorizations
array with zero elements;¶
delegation
configuration; and¶
allow-certificate-get
setting.¶
The Order finalization by the NDC and the subsequent validation of the CSR by
the IdO proceed in the same way as for the STAR case. If the CSR is
successfully validated, the order object status moves to processing
and the
twin ACME protocol instance is initiated on the IdO-CA side.¶
The request object created by the IdO:¶
delegation
attribute; and¶
allow-certificate-get
attribute.¶
When the identifiers' authorization has been successfully completed and the certificate has been issued by the CA, the IdO:¶
valid
and¶
certificate
field from the Order returned by the CA into its
Order resource, as well as notBefore
and notAfter
if these fields exist.¶
At this point of the protocol flow, the same considerations as in Section 2.3.2.1 apply.¶
Before forwarding the Order request to the CA, the IdO SHOULD ensure that the
selected CA supports unauthenticated GET by inspecting the relevant settings
in the CA's directory object, as per Section 2.3.5. If the CA
does not 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
occurs in case the Order request is forwarded and the CA does not reflect the
allow-certificate-get
setting in its Order resource. The combination of
invalid
status and denied allow-certificate-get
in the Order resource at
the IdO provides an unambiguous (asynchronous) signal to the NDC about the
failure reason.¶
In order to help a client discover support for this profile, the directory
object of an ACME server (typically, one deployed by the IdO) contains the
following attribute in the meta
field:¶
The IdO MUST declare its support for delegation using delegation-enabled
regardless of whether it supports delegation of STAR certificates, non-STAR
certificates, or both.¶
In order to help a client discover support for certificate fetching using
unauthenticated HTTP GET, the directory object of an ACME server (typically,
one deployed by the CA) contains the following attribute in the meta
field:¶
In order to enable the name delegation of non-STAR certificates, this document defines a mechanism that allows a server to advertise support for accessing certificate resources via unauthenticated GET (in addition to POST-as-GET) and a client to enable this service with per-Order granularity.¶
It is worth pointing out that the protocol elements described in this section
have the same names and semantics as those introduced in
Section 3.4 of [RFC8739] for the STAR use case (except, of course, they apply to the
certificate resource rather than the star-certificate resource). However, they
differ in terms of their position in the directory meta and order objects;
rather than being wrapped in an auto-renewal
subobject, they are located at the
top level.¶
A server states its availability to grant unauthenticated access to a client's
Order certificate by setting the allow-certificate-get
attribute to true
in
the meta
field inside the directory object:¶
true
, the server allows GET (and HEAD) requests to certificate URLs.¶
A client states its desire to access the issued certificate via unauthenticated
GET by adding an allow-certificate-get
attribute to the payload of its
newOrder request and setting it to true
.¶
true
, the client requests the server to allow unauthenticated GET (and
HEAD) to the certificate associated with this Order.¶
If the server accepts the request, it MUST reflect the attribute setting in the resulting order object.¶
Note that even when the use of unauthenticated GET has been agreed upon, the server MUST also allow POST-as-GET requests to the certificate resource.¶
Identity delegation is terminated differently depending on whether or not this is a STAR certificate.¶
The IdO can terminate the delegation of a STAR certificate by requesting its cancellation (see Section 3.1.2 of [RFC8739]).¶
Cancellation of the ACME STAR certificate is a prerogative of the IdO. The NDC does not own the relevant account key on the CA; therefore, it can't issue a cancellation request for the STAR certificate. Potentially, since it holds the STAR certificate's private key, it could request the revocation of a single STAR certificate. However, STAR explicitly disables the revokeCert interface.¶
Shortly after the automatic renewal process is stopped by the IdO, the last issued STAR certificate expires and the delegation terminates.¶
The IdO can terminate the delegation of a non-STAR certificate by requesting it
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. In other words, an
NDC that learns the revokeCert
URL of the CA (which is publicly available via
the CA's directory object) would be able to revoke the certificate using the
associated private key. However, given the trust relationship between the NDC and
IdO expected by the delegation trust model (Section 7.1), as well as
the lack of incentives for the NDC to prematurely terminate the delegation,
this does not represent a significant security risk.¶
There are cases where the ACME Delegation flow should be proxied, such as the use case described in Section 5.1.2. This section describes the behavior of such proxies.¶
An entity implementing the IdO server role -- an "ACME Delegation server" -- may behave, on a per-identity case, either as a proxy into another ACME Delegation server or as an IdO and obtain a certificate directly. The determining factor is whether it can successfully be authorized by the next-hop ACME server for the identity associated with the certificate request.¶
The identities supported by each server and the disposition for each of them are preconfigured.¶
Following is the proxy's behavior for each of the messages exchanged in the ACME Delegation process:¶
status
, expires
, authorizations
, identifiers
, and auto-renewal
attributes/objects MUST be copied as is.¶
finalize
URL is rewritten so that the finalize
request will be
made to the proxy.¶
Location
header MUST be rewritten to point to an order object on the proxy.¶
Link
relations MUST be rewritten to point to the proxy.¶
status
, expires
, authorizations
, identifiers
, and auto-renewal
attributes/objects MUST be copied as is.¶
star-certificate
URL (or the certificate
URL in case of
non-STAR requests) MUST be copied as is.¶
finalize
URL is rewritten so that the finalize
request will be
made to the proxy.¶
Location
header MUST be rewritten to point to an order object on the proxy.¶
Link
relations MUST be rewritten to point to the proxy.¶
finalize
request:finalize
response:Location
header, Link
relations, and the finalize
URLs are rewritten as for Get Order.¶
We note that all the above messages are authenticated; therefore, each proxy must be able to authenticate any subordinate server.¶
Although most of this document, and in particular Section 2, is focused on the protocol between the NDC and IdO, the protocol does affect the ACME server running in the CA. A CA that wishes to support certificate delegation MUST also support unauthenticated certificate fetching, which it declares using allow-certificate-get
(Section 2.3.5, Paragraph 3).¶
The CSR template is used to express and constrain the shape of the CSR that the NDC uses to request the certificate. The CSR is used for every certificate created under the same delegation. Its validation by the IdO is a critical element in the security of the whole delegation mechanism.¶
Instead of defining every possible CSR attribute, this document takes a minimalist approach by declaring only the minimum attribute set and deferring the registration of further, more-specific attributes to future documents.¶
The template is a JSON document. Each field (with the exception of keyTypes
, see below) denotes one of the following:¶
abc.ido.example
.¶
**
.¶
*
.¶
The NDC MUST NOT include any fields in the CSR, including any extensions, unless they are specified in the template.¶
The structure of the template object is defined by the Concise Data Definition Language (CDDL) [RFC8610] document in Appendix A. An alternative, nonnormative JSON Schema syntax is given in Appendix B. While the CSR template must follow the syntax defined here, neither the IdO nor the NDC are expected to validate it at runtime.¶
The subject
field and its subfields are mapped into the subject
field of the CSR, as per Section 4.1.2.6 of [RFC5280]. Other extension fields of the CSR template are mapped into the CSR according to the table in Section 6.5.¶
The subjectAltName
field is currently defined for the following identifiers:
DNS names, email addresses, and URIs. New identifier types may be added in the
future by documents that extend this specification. Each new identifier type
SHALL have an associated identifier validation challenge that the CA can
use to obtain proof of the requester's control over it.¶
The keyTypes
property is not copied into the CSR. Instead, this property 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 contained in the delegation
object referenced in the Order. The IdO MAY enforce additional
constraints, e.g., by restricting field lengths. In this regard, note that a
subjectAltName
of type DNS
can be specified using the wildcard notation,
meaning that the NDC can be required (**
) or offered the possibility (*
) to
define the delegated domain name by itself. If this is the case, the IdO MUST
apply application-specific checks on top of the control rules already provided
by the CSR template to ensure the requested domain name is legitimate according
to its local policy.¶
This nonnormative section describes additional use cases implementing the STAR certificate delegation in nontrivial ways.¶
[HTTPS-DELEGATION] discusses several solutions addressing different delegation requirements for the CDN Interconnection (CDNI) environment. This section discusses two of the stated requirements in the context of the STAR delegation workflow.¶
This section uses specific CDNI terminology, e.g., Upstream CDN (uCDN) and Downstream (dCDN), as defined in [RFC7336].¶
In some cases, the content owner (IdO) would like to delegate authority over a website to multiple NDCs (CDNs). This could happen if the IdO has agreements in place with different regional CDNs for different geographical regions or if a "backup" CDN is used to handle overflow traffic by temporarily altering some of the CNAME mappings in place. The STAR delegation flow enables this use case naturally, since each CDN can authenticate separately to the IdO (via its own separate account) specifying its CSR, and the IdO is free to allow or deny each certificate request according to its own policy.¶
In other cases, a content owner (IdO) delegates some domains to a large CDN (uCDN), which in turn delegates to a smaller regional CDN (dCDN). The IdO has a contractual relationship with uCDN, and uCDN has a similar relationship with dCDN. However, IdO may not even know about dCDN.¶
If needed, the STAR protocol can be chained to support this use case: uCDN could forward requests from dCDN to IdO and forward responses back to dCDN. Whether such proxying is allowed is governed by policy and contracts between the parties.¶
A mechanism is necessary at the interface between uCDN and dCDN, by which the uCDN can advertise:¶
Note that such mechanism is provided by the CSR template.¶
A User Agent (UA), e.g., a browser or set-top box, wants to fetch the video resource at
the following URI: https://video.cp.example/movie
.
Redirection between the
content provider (CP) and upstream and downstream CDNs is arranged as a
CNAME-based aliasing chain, as illustrated in Figure 11.¶
Unlike HTTP-based redirection, where the original URL is supplanted by the one
found in the Location
header of the 302 response, DNS redirection is completely
transparent to the User Agent. As a result, the TLS connection to the dCDN
edge is done with a Server Name Indication (SNI) equal to the host
in the
original URI -- in the example, video.cp.example
. So, in order to
successfully complete the handshake, the landing dCDN node has to be configured
with a certificate whose subjectAltName
field matches video.cp.example
, i.e., a
content provider's name.¶
Figure 12 illustrates the cascaded delegation flow that allows dCDN to obtain a STAR certificate that bears a name belonging to the content provider with a private key that is only known to the dCDN.¶
uCDN is configured to delegate to dCDN, and CP is configured to delegate to uCDN, both as defined in Section 2.3.1.¶
star-certificate
URL.¶
Note that 9 and 10 repeat until the delegation expires or is terminated.¶
As a second use case, we consider the delegation of credentials in the STIR ecosystem [RFC9060].¶
This section uses STIR terminology. The term Personal Assertion Token (PASSporT) is defined in [RFC8225], and "TNAuthList" is defined in [RFC8226].¶
In the STIR delegated mode, a service provider SP2 -- the NDC -- needs to sign PASSporTs [RFC8225] for telephone numbers (e.g., TN=+123) belonging to another service provider, SP1 -- the IdO. In order to do that, SP2 needs a STIR certificate and a private key that includes TN=+123 in the TNAuthList [RFC8226] certificate extension.¶
star-certificate
URL in the order to fetch the rolling
STAR certificate bearing the delegated identifiers.¶
As shown, the STAR delegation profile described in this document applies straightforwardly; the only extra requirement being the ability to instruct the NDC about the allowed TNAuthList values. This can be achieved by a simple extension to the CSR template.¶
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 |
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 |
This document adds the following entries to the "ACME Account Object Fields" registry:¶
Field Name | Field Type | Requests | Reference |
---|---|---|---|
delegations | string | none | RFC 9115 |
Note that the delegations
field is only reported by ACME servers that have
delegation-enabled
set to true in their meta Object.¶
This document adds the following entries to the "ACME Error Types" registry:¶
Type | Description | Reference |
---|---|---|
unknownDelegation | An unknown configuration is listed in the delegation attribute of the order request |
RFC 9115 |
IANA has established the "STAR Delegation CSR Template Extensions" registry, with "Specification Required" as its registration procedure.¶
Each extension registered must specify:¶
The initial contents of this registry are the extensions defined by the CDDL in Appendix A.¶
Extension Name | Extension Syntax | Mapping to X.509 Certificate Extension |
---|---|---|
keyUsage | See Appendix A | [RFC5280], Section 4.2.1.3 |
extendedKeyUsage | See Appendix A | [RFC5280], Section 4.2.1.12 |
subjectAltName | See Appendix A | [RFC5280], Section 4.2.1.6 (note that only specific name formats are allowed: URI, DNS name, email address) |
When evaluating a request for an assignment in this registry, the designated expert should follow this guidance:¶
The ACME trust model needs to be extended to include the trust relationship between NDC and IdO. Note that once this trust link is established, it potentially becomes recursive. Therefore, there has to be a trust relationship between each of the nodes in the delegation chain; for example, in case of cascading CDNs, this is contractually defined. Note that when using standard [RFC6125] identity verification, there are no mechanisms available to the IdO to restrict the use of the delegated name once the name has been handed over to the first NDC. It is, therefore, expected that contractual measures are in place to get some assurance that redelegation is not being performed.¶
Delegation introduces a new security goal: only an NDC that has been authorized by the IdO, either directly or transitively, can obtain a certificate with an IdO identity.¶
From a security point of view, the delegation process has five separate parts:¶
The first part is covered by the NDC's ACME account that is administered by the IdO, whose 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].¶
The second part is covered by the act of checking an NDC's certificate request against the intended CSR template. The steps of shaping the CSR template correctly, selecting the right CSR template to check against the presented CSR, and making sure that the presented CSR matches the selected CSR template are all security relevant.¶
The third part builds on the trust relationship between NDC and IdO that is responsible for correctly forwarding the certificate URL from the Order returned by the CA.¶
The fourth part is associated with the ability of the IdO to unilaterally
remove the delegation
object associated with the revoked identity, therefore,
disabling any further NDC requests for such identity. Note that, in more
extreme circumstances, the IdO might decide to disable the NDC account,
thus entirely blocking any further interaction.¶
The fifth is covered by two different mechanisms, depending on the nature of the 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 associated with the delegation plays a crucial role in the
overall security of the presented protocol. This, in turn, means that (in
delegation scenarios) the security requirements and verification associated with
an ACME account may be more stringent than in base ACME deployments, since the
out-of-band configuration of delegations that an account is authorized to use
(combined with account authentication) takes the place of the normal ACME
authorization challenge procedures. Therefore, 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.¶
Using the model established in Section 10.1 of [RFC8555], we can decompose the interactions of the basic delegation workflow, as shown in Figure 14.¶
The considerations regarding the security of the ACME Channel and Validation Channel discussed in [RFC8555] apply verbatim to the IdO-CA leg. The same can be said for the ACME Channel on the NDC-IdO leg. A slightly different set of considerations apply to the ACME Channel between the NDC and CA, which consists of a subset of the ACME interface comprising two API endpoints: the 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. With regard to the latter, it should be noted that there is currently no means 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, therefore, 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, 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.¶
When a website is delegated to a CDN, the CDN can in principle modify the website at will, e.g., create and remove pages. This means that 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 regardless of whether or not the CNAME mechanisms defined in the current document is used.¶
In some cases, this is the desired behavior; the domain holder trusts the CDN to have full control of the cryptographic credentials for the site. However, this document assumes a scenario where the domain holder only wants to delegate restricted control and wishes to retain the capability to cancel the CDN's credentials at a short notice.¶
The following is a possible mitigation when the IdO wishes to ensure that a rogue CDN cannot issue unauthorized certificates:¶
We note that the above solution may need to be tweaked depending on the exact capabilities and authorization flows supported by the selected CA. In addition, this mitigation may be bypassed if a malicious or misconfigured CA does not comply with CAA restrictions.¶
Following is the normative definition of the CSR template using CDDL [RFC8610]. The CSR template MUST be a valid JSON document that is compliant with the syntax defined here.¶
There are additional constraints not expressed in CDDL that MUST be validated by the recipient, including:¶
subjectAltName
entry is compatible with its type and¶
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]*))*"¶
This appendix includes an alternative, nonnormative JSON Schema definition of the CSR template. The syntax used is that of draft 7 of JSON Schema, which is documented in [json-schema-07]. Note that later versions of this (now-expired) draft describe later versions of the JSON Schema syntax. At the time of writing, a stable reference for this syntax is not yet available, and we have chosen to use the draft version, which is currently best supported by tool implementations.¶
The same considerations about additional constraints checking discussed in Appendix A apply here as well.¶
{ "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 }¶
We would like to thank the following people who contributed significantly to this document 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.¶
This work is partially supported by the European Commission under Horizon 2020 grant agreement no. 688421 Measurement and Architecture for a Middleboxed Internet (MAMI). This support does not imply endorsement.¶