An ACME Profile for Generating Delegated Certificates

1.1. Terminology

IdO

Identifier Owner, the owner of an identifier (e.g., a domain name) that needs to be delegated.¶

NDC

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 symmetry of the two acronyms).¶

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 X.509 certificates.¶

ACME

Automated Certificate Management Environment, a certificate management protocol [RFC8555].¶

CA

A Certification Authority that implements the ACME protocol. In this document, the term is synonymous with "ACME server".¶

CSR

A PKCS#10 [RFC2986] Certificate Signing Request, as supported by ACME.¶

FQDN

Fully Qualified Domain Name.¶

1.2. Conventions used in this document

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.¶

2.1. Preconditions

The protocol assumes the following preconditions are met:¶

• The IdO exposes an ACME server interface to the NDC(s) comprising the account management interface;¶
• The NDC has registered an ACME account with the IdO;¶
• NDC and IdO have agreed on a "CSR template" to use, including at a minimum: subject name (e.g., somesite.example.com), requested algorithms and key length, key usage, extensions (e.g., TNAuthList). The NDC is required to use this template for every CSR created under the same delegation;¶
• 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: 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 ACME server.¶

2.2. Overview

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] as well as any other ACME extension that applies (e.g., [I-D.ietf-acme-authority-token-tnauthlist] for STIR).¶

The outline of the combined protocol for STAR certificates is as follow (Figure 1):¶

• NDC sends an order Order1 for the delegated identifier to IdO;¶
• IdO creates an Order1 resource in state ready with a finalize URL;¶
• NDC immediately sends a finalize request (which includes the CSR) to the IdO;¶
• IdO verifies the CSR according to the agreed upon CSR template;¶
• If the CSR verification fails, Order1 is moved to an invalid state and everything stops;¶
• If the CSR verification is successful, IdO moves Order1 to state processing, and sends a new Order2 (using its own account) for the delegated identifier to the CA;¶
• If the ACME STAR protocol fails, Order2 moves to invalid and the same state is reflected in Order1 (i.e., the NDC Order);¶
• If the ACME STAR run is successful (i.e., Order2 is 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. This can continue until the STAR certificate 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 2.3.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.¶

2.3. Delegated Identity Profile

This section defines a profile of the ACME protocol, to be used between the NDC and IdO.¶

{
  "status": "valid",
  "contact": [
    "mailto:delegation-admin@ido.example"
  ],
  "termsOfServiceAgreed": true,
  "orders": "https://example.com/acme/orders/rzGoeA",
  "delegations": "https://acme.ido.example/acme/delegations/adFqoz"
}

{
  "csr-template": {
    "keyTypes": [
      {
        "PublicKeyType": "id-ecPublicKey",
        "namedCurve": "secp256r1",
        "SignatureType": "ecdsa-with-SHA256"
      }
    ],
    "subject": {
      "country": "CA",
      "stateOrProvince": "**",
      "locality": "**",
      "commonName": "**"
    },
    "extensions": {
      "subjectAltName": {
        "DNS": [
          "abc.ndc.ido.example"
        ]
      },
      "keyUsage": [
        "digitalSignature"
      ],
      "extendedKeyUsage": [
        "serverAuth"
      ]
    }
  },
  "cname-map": {
    "abc.ndc.ido.example.": "abc.ndc.example."
  }
}

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": "5XJ1L3lEkMG7tR6pA00clA",
    "url": "https://acme.ido.example/acme/new-order"
  }),
  "payload": base64url({
    "identifiers": [
      {
        "type": "dns",
        "value": "abc.ndc.ido.example.",
        "delegation":
           "https://acme.ido.example/acme/delegations/adFqoz/2"
      }
    ],
    "auto-renewal": {
      "end-date": "2020-04-20T00:00:00Z",
      "lifetime": 345600,          // 4 days
      "allow-certificate-get": true
    }
  }),
  "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
}

{
  "status": "ready",
  "expires": "2019-05-01T00:00:00Z",

  "identifiers": [
   {
     "type": "dns",
     "value": "abc.ndc.ido.example.",
     "delegation":
        "https://acme.ido.example/acme/delegations/adFqoz/2"
   }
  ],

  "auto-renewal": {
    "end-date": "2020-04-20T00:00:00Z",
    "lifetime": 345600,
    "allow-certificate-get": true
  },

  "authorizations": [],

  "finalize": "https://acme.ido.example/acme/order/TO8rfgo/finalize"
}

{
  "status": "valid",
  "expires": "2019-05-01T00:00:00Z",

  "identifiers": [
   {
     "type": "dns",
     "value": "abc.ndc.ido.example.",
     "delegation":
        "https://acme.ido.example/acme/delegations/adFqoz/2"
   }
  ],

  "auto-renewal": {
    "end-date": "2020-04-20T00:00:00Z",
    "lifetime": 345600,
    "allow-certificate-get": true
  },

  "authorizations": [],

  "finalize": "https://acme.ido.example/acme/order/TO8rfgo/finalize",

  "star-certificate": "https://acme.ca.example/acme/order/yTr23sSDg9"
}

   abc.ndc.ido.example. CNAME abc.ndc.example.

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.ndc.ido.example.",
        "delegation":
           "https://acme.ido.example/acme/delegations/adFqoz/2"
      }
    ]
  }),
  "signature": "H6ZyWqg8aaKEkYca...dudoz4igiMvUBJ9j"
}

{
  "status": "ready",
  "expires": "2019-05-01T00:00:00Z",

  "identifiers": [
   {
     "type": "dns",
     "value": "abc.ndc.ido.example.",
     "delegation":
        "https://acme.ido.example/acme/delegations/adFqoz/2"
   }
  ],

  "authorizations": [],

  "finalize": "https://acme.ido.example/acme/order/to8RFGO/finalize"
}

{
  "status": "valid",
  "expires": "2019-05-01T00:00:00Z",

  "identifiers": [
   {
     "type": "dns",
     "value": "abc.ndc.ido.example.",
     "delegation":
        "https://acme.ido.example/acme/delegations/adFqoz/2"
   }
  ],

  "allow-certificate-get": true,

  "authorizations": [],

  "finalize": "https://acme.ido.example/acme/order/to8RFGO/finalize",

  "certificate": "https://acme.ca.example/acme/order/YtR23SsdG9"
}

2.4. Proxy Behavior

There are cases where the ACME Delegation flow should be proxied, such as the use case described in Section 4.1.2. This section describes the behavior of such proxies.¶

An entity implementing the IdO server role - an "ACME Delegation server" - can decide, on a per-identity case, whether to act as a proxy into another ACME Delegation server, or to behave as an IdO and obtain a certificate directly. The determining factor is whether it can successfully be authorized by the 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:¶

• New-order request:¶

  • The complete identifiers object 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 that the finalize request will be made to the proxy.¶
  • Similarly, the Location header MUST be rewritten to point to an Order object on the proxy.¶
  • And similarly, any Link relations.¶

• 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 in case of non-STAR requests) MUST be copied as-is.¶
  • The finalize URL is rewritten, so that the finalize request will be made 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 note that all the above messages are authenticated, and therefore each proxy must be able to authenticate any subordinate server.¶

3.1. Template Syntax

The template is a JSON document. Each field (with the exception of keyTypes, see below) denotes one of:¶

• A mandatory field, where the template specifies the literal value of that field. This is denoted by a literal string, such as client1.ndc.ido.example.com.¶
• A mandatory field, where the content of the field is defined by the client. This is denoted by **.¶
• An optional field, where the client decides whether the field is included in the CSR and if so, what its value is. This is denoted by *.¶

The NDC MUST NOT include in the CSR any fields, including any extensions, unless they are specified in the template.¶

The structure of the template object is defined by the CDDL [RFC8610] document in Appendix B.¶

An alternative, non-normative JSON Schema syntax is given in Appendix C.¶

The subject field and its subfields are mapped into the subject field of the CSR, as per [RFC5280], Section 4.1.2.6. Other extension fields of the CSR template are mapped into the CSR according to the table in Section 5.6.¶

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 ACME 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 needs to have a further layer of checks on top of the control rules already provided by the CSR template to fully validate the CSR input.¶

3.2. Example

The CSR template in Figure 10 represents one possible CSR template governing the delegation exchanges provided 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": "**",
    "commonName": "**"
  },
  "extensions": {
    "subjectAltName": {
      "DNS": [
        "client1.ndc.ido.example"
      ]
    },
    "keyUsage": [
      "digitalSignature"
    ],
    "extendedKeyUsage": [
      "serverAuth",
      "clientAuth"
    ]
  }
}

4.1. CDN Interconnection (CDNI)

[I-D.ietf-cdni-interfaces-https-delegation] discusses several solutions addressing different delegation requirements for the CDNI (CDN Interconnection) environment. This section discusses two of the stated requirements in the context of the STAR delegation workflow.¶

This section uses specifically CDNI terminology, e.g. "uCDN" and "dCDN", as defined in [RFC7336].¶

4.2. Secure Telephone Identity Revisited (STIR)

As a second use case, we consider the delegation of credentials in the STIR ecosystem [I-D.ietf-stir-cert-delegation].¶

This section uses STIR terminology. The term PASSPorT is defined in [RFC8225], and "TNAuthList" in [RFC8226].¶

In the STIR delegated mode, a service provider SP2 - the NDC - needs to sign PASSPorT's [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 private key, that includes TN=+123 in the TNAuthList [RFC8226] certificate extension.¶

In details (Figure 13):¶

1. SP1 and SP2 agree on the configuration of the delegation - in particular, the CSR template that applies;¶
2. SP2 generates a private/public key-pair and sends a CSR to SP1 requesting creation of a certificate with: SP1 name, SP2 public key, and a TNAuthList extension with the list of TNs that SP1 delegates to SP2. (Note that the CSR sent by SP2 to SP1 needs to be validated against the CSR template agreed upon in step 1.);¶
3. SP1 sends an Order for the CSR to the CA;¶
4. Subsequently, after the required TNAuthList authorizations are successfully completed, the CA moves the Order to a "valid" state; at the same time the star-certificate endpoint is populated.¶
5. The Order contents are forwarded from SP1 to SP2 by means of the paired "delegation" Order.¶
6. SP2 dereferences the 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.¶

5.1. New ACME Identifier Object Fields

This document requests that IANA create the following new registry under the Automated Certificate Management Environment (ACME) Protocol:¶

• ACME Identifier Object Fields¶

This registry is administered under a Specification Required policy [RFC8126].¶

The "ACME Identifier Object Fields" registry lists field names that are defined for use in the ACME identifier object.¶

Template:¶

• Field name: The string to be used as a field name in the JSON object¶
• Field type: The type of value to be provided, e.g., string, boolean, array of string¶
• Reference: Where this field is defined¶

Note: this registry was not created at the time [RFC8555] was standardized likely because it was not anticipated that the identifier object would be extended. It is retrospectively introduced to record the status quo and allow controlled extensibility of the identifier object.¶

5.2. New Fields in the "meta" Object within a Directory Object

This document adds the following entries to the ACME Directory Metadata Fields registry:¶

5.3. New Fields in the Order Object

This document adds the following entries to the ACME Order Object Fields registry:¶

5.4. New Fields in the Account Object

This document adds the following entries to the ACME Account Object Fields registry:¶

Note that the delegations field is only reported by ACME servers that have delegation-enabled set to true in their meta Object.¶

5.5. New Error Types

This document adds the following entries to the ACME Error Type registry:¶

5.6. CSR Template Extensions

IANA is requested to establish a registry "STAR Delegation CSR Template Extensions", with "Expert Review" as its registration procedure.¶

Each extension registered must specify:¶

• An extension name.¶
• An extension syntax, as a reference to a JSON Schema document that defines this extension.¶
• The extension's mapping into an X.509 certificate extension.¶

The initial contents of this registry are the extensions defined by the CDDL in Appendix B.¶

6.1. Trust Model

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 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.¶

6.2. Delegation Security Goal

Delegation introduces a new security goal: only an NDC that has been authorised 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:¶

1. Enabling a specific third party (the intended NDC) to submit requests for delegated certificates;¶
2. 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.;¶
3. Serving the certificate back to the NDC;¶
4. A process for handling revocation of the delegation;¶
5. A process for handling revocation of the certificate itself.¶

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 ACME server.¶

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]).¶

6.3. New ACME Channels

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/ACME server 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 NDC and ACME server, 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 regards to the latter, it should be noted that there is currently no means for an IdO to disable authorising revocation based on certificate private keys. So, in theory, an NDC could use the revocation API directly with the ACME server, therefore bypassing the IdO. The NDC SHOULD NOT directly use the revocation interface exposed by the ACME server 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.¶

6.4. Restricting CDNs to the Delegation Mechanism

When a web site is delegated to a CDN, the CDN can in principle modify the web site at will, 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 the CNAME mechanisms defined in the current document is used or not.¶

In some cases, this is the desired behavior: the domain owner trusts the CDN to have full control of the cryptographic credentials for the site. The current document however assumes that the domain owner 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:¶

• The domain owner makes sure that the CDN cannot modify the DNS records for the domain. The domain owner 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 owner uses a 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 owner uses the ACME-specific CAA mechanism [RFC8657] to restrict issuance to a specific account key which is controlled by it, and MUST require "dns-01" as the sole validation method.¶

We note that the above solution may need to be tweaked depending on the exact capabilities and authorisation flows supported by the selected CAs.¶

A.1. draft-ietf-acme-star-delegation-07

• SecDir comments by Russ Housley.¶
• In particular, reorganized some parts of the document to clarify handling of non-STAR certificates.¶
• And changed the document's title accordingly.¶

A.2. draft-ietf-acme-star-delegation-06

• CDDL schema to address Roman's remaining comments.¶

A.3. draft-ietf-acme-star-delegation-05

• Detailed AD review by Roman Danyliw.¶
• Some comments that were left unaddressed in Ryan Sleevi's review.¶
• Numerous other edits for clarity and consistency.¶

A.4. draft-ietf-acme-star-delegation-04

• Delegation of non-STAR certificates.¶
• More IANA clarity, specifically on certificate extensions.¶
• Add delegation configuration object and extend account and order objects accordingly.¶
• A lot more depth on Security Considerations.¶

A.5. draft-ietf-acme-star-delegation-03

• Consistency with the latest changes in the base ACME STAR document, e.g. star-delegation-enabled capability renamed and moved.¶
• Proxy use cases (recursive delegation) and the definition of proxy behavior.¶
• More detailed analysis of the CDNI and STIR use cases, including sequence diagrams.¶

A.6. draft-ietf-acme-star-delegation-02

• Security considerations: review by Ryan Sleevi.¶
• CSR template simplified: instead of being a JSON Schema document itself, it is now a simple JSON document which validates to a JSON Schema.¶

A.7. draft-ietf-acme-star-delegation-01

• Refinement of the CDNI use case.¶
• Addition of the CSR template (partial, more work required).¶
• Further security considerations (work in progress).¶

A.8. draft-ietf-acme-star-delegation-00

• Republished as a working group draft.¶

A.9. draft-sheffer-acme-star-delegation-01

• Added security considerations about disallowing CDNs from issuing certificates for a delegated domain.¶

A.10. draft-sheffer-acme-star-delegation-00

• Initial version, some text extracted from draft-sheffer-acme-star-requests-02¶