idnits 2.17.1 draft-ietf-acme-star-delegation-09.txt: -(4): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 5 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 4 characters in excess of 72. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (11 June 2021) is 1049 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 1487 == Missing Reference: '0-2' is mentioned on line 2059, but not defined == Missing Reference: '1-9' is mentioned on line 2059, but not defined == Missing Reference: '0-9' is mentioned on line 2059, but not defined ** Downref: Normative reference to an Informational RFC: RFC 2986 ** Obsolete normative reference: RFC 7807 (Obsoleted by RFC 9457) == Outdated reference: A later version (-13) exists of draft-ietf-acme-authority-token-tnauthlist-08 == Outdated reference: A later version (-13) exists of draft-ietf-cdni-interfaces-https-delegation-05 == Outdated reference: A later version (-15) exists of draft-ietf-tls-subcerts-10 == Outdated reference: A later version (-06) exists of draft-mglt-lurk-tls13-04 -- Obsolete informational reference (is this intentional?): RFC 6125 (Obsoleted by RFC 9525) Summary: 3 errors (**), 0 flaws (~~), 9 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACME Y. Sheffer 3 Internet-Draft Intuit 4 Intended status: Standards Track D. López 5 Expires: 13 December 2021 A. Pastor Perales 6 Telefonica I+D 7 T. Fossati 8 ARM 9 11 June 2021 11 An ACME Profile for Generating Delegated Certificates 12 draft-ietf-acme-star-delegation-09 14 Abstract 16 This document defines a profile of the Automatic Certificate 17 Management Environment (ACME) protocol by which the holder of an 18 identifier (e.g., a domain name) can allow a third party to obtain an 19 X.509 certificate such that the certificate subject is the delegated 20 identifier while the certified public key corresponds to a private 21 key controlled by the third party. A primary use case is that of a 22 Content Delivery Network (CDN, the third party) terminating TLS 23 sessions on behalf of a content provider (the holder of a domain 24 name). The presented mechanism allows the holder of the identifier 25 to retain control over the delegation and revoke it at any time. 26 Importantly, this mechanism does not require any modification to the 27 deployed TLS clients and servers. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 13 December 2021. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.2. Conventions used in this document . . . . . . . . . . . . 5 65 2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.1. Preconditions . . . . . . . . . . . . . . . . . . . . . . 5 67 2.2. Overview . . . . . . . . . . . . . . . . . . . . . . . . 6 68 2.3. Delegated Identity Profile . . . . . . . . . . . . . . . 8 69 2.3.1. Delegation Configuration . . . . . . . . . . . . . . 8 70 2.3.2. Order Object Transmitted from NDC to IdO and to ACME 71 Server (STAR) . . . . . . . . . . . . . . . . . . . . 11 72 2.3.3. Order Object Transmitted from NDC to IdO and to ACME 73 Server (non-STAR) . . . . . . . . . . . . . . . . . . 15 74 2.3.4. Capability Discovery . . . . . . . . . . . . . . . . 18 75 2.3.5. Negotiating an Unauthenticated GET . . . . . . . . . 19 76 2.3.6. Terminating the Delegation . . . . . . . . . . . . . 20 77 2.4. Proxy Behavior . . . . . . . . . . . . . . . . . . . . . 21 78 3. CA Behavior . . . . . . . . . . . . . . . . . . . . . . . . . 22 79 4. CSR Template . . . . . . . . . . . . . . . . . . . . . . . . 22 80 4.1. Template Syntax . . . . . . . . . . . . . . . . . . . . . 22 81 4.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 23 82 5. Further Use Cases . . . . . . . . . . . . . . . . . . . . . . 24 83 5.1. CDN Interconnection (CDNI) . . . . . . . . . . . . . . . 24 84 5.1.1. Multiple Parallel Delegates . . . . . . . . . . . . . 25 85 5.1.2. Chained Delegation . . . . . . . . . . . . . . . . . 25 86 5.2. Secure Telephone Identity Revisited (STIR) . . . . . . . 28 87 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 88 6.1. New Fields in the "meta" Object within a Directory 89 Object . . . . . . . . . . . . . . . . . . . . . . . . . 29 90 6.2. New Fields in the Order Object . . . . . . . . . . . . . 30 91 6.3. New Fields in the Account Object . . . . . . . . . . . . 30 92 6.4. New Error Types . . . . . . . . . . . . . . . . . . . . . 30 93 6.5. CSR Template Extensions . . . . . . . . . . . . . . . . . 31 95 7. Security Considerations . . . . . . . . . . . . . . . . . . . 32 96 7.1. Trust Model . . . . . . . . . . . . . . . . . . . . . . . 32 97 7.2. Delegation Security Goal . . . . . . . . . . . . . . . . 32 98 7.3. New ACME Channels . . . . . . . . . . . . . . . . . . . . 33 99 7.4. Restricting CDNs to the Delegation Mechanism . . . . . . 35 100 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 35 101 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 102 9.1. Normative References . . . . . . . . . . . . . . . . . . 36 103 9.2. Informative References . . . . . . . . . . . . . . . . . 37 104 Appendix A. Document History . . . . . . . . . . . . . . . . . . 38 105 A.1. draft-ietf-acme-star-delegation-09 . . . . . . . . . . . 38 106 A.2. draft-ietf-acme-star-delegation-08 . . . . . . . . . . . 39 107 A.3. draft-ietf-acme-star-delegation-07 . . . . . . . . . . . 39 108 A.4. draft-ietf-acme-star-delegation-06 . . . . . . . . . . . 39 109 A.5. draft-ietf-acme-star-delegation-05 . . . . . . . . . . . 39 110 A.6. draft-ietf-acme-star-delegation-04 . . . . . . . . . . . 39 111 A.7. draft-ietf-acme-star-delegation-03 . . . . . . . . . . . 40 112 A.8. draft-ietf-acme-star-delegation-02 . . . . . . . . . . . 40 113 A.9. draft-ietf-acme-star-delegation-01 . . . . . . . . . . . 40 114 A.10. draft-ietf-acme-star-delegation-00 . . . . . . . . . . . 40 115 A.11. draft-sheffer-acme-star-delegation-01 . . . . . . . . . . 40 116 A.12. draft-sheffer-acme-star-delegation-00 . . . . . . . . . . 40 117 Appendix B. CSR Template: CDDL . . . . . . . . . . . . . . . . . 40 118 Appendix C. CSR Template: JSON Schema . . . . . . . . . . . . . 43 119 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 121 1. Introduction 123 This document is related to [RFC8739], in that some important use 124 cases require both documents to be implemented. To avoid 125 duplication, we give here a bare-bones description of the motivation 126 for this solution. For more details, please refer to the 127 introductory sections of [RFC8739]. 129 An Identifier Owner (IdO) has agreements in place with one or more 130 NDC (Name Delegation Consumer) to use and attest its identity. 132 In the primary use case the IdO is a content provider, and we 133 consider a Content Delivery Network (CDN) provider contracted to 134 serve the content over HTTPS. The CDN terminates the HTTPS 135 connection at one of its edge cache servers and needs to present its 136 clients (browsers, mobile apps, set-top-boxes) a certificate whose 137 name matches the domain name of the URL that is requested, i.e., that 138 of the IdO. Understandably, some IdOs may balk at sharing their 139 long-term private keys with another organization and, equally, 140 delegates would rather not have to handle other parties' long-term 141 secrets. Other relevant use cases are discussed in Section 5. 143 This document describes a profile of the ACME protocol [RFC8555] that 144 allows the NDC to request from the IdO, acting as a profiled ACME 145 server, a certificate for a delegated identity - i.e., one belonging 146 to the IdO. The IdO then uses the ACME protocol (with the extensions 147 described in [RFC8739]) to request issuance of a Short-Term, 148 Automatically Renewed (STAR) certificate for the same delegated 149 identity. The generated short-term certificate is automatically 150 renewed by the ACME Certification Authority (CA), periodically 151 fetched by the NDC and used to terminate HTTPS connections in lieu of 152 the IdO. The IdO can end the delegation at any time by simply 153 instructing the CA to stop the automatic renewal and letting the 154 certificate expire shortly thereafter. 156 While the primary use case we address is delegation of STAR 157 certificates, the mechanism proposed here accommodates also long- 158 lived certificates managed with the ACME protocol. The most 159 noticeable difference between long-lived and STAR certificates is the 160 way the termination of the delegation is managed. In the case of 161 long-lived certificates, the IdO uses the revokeCert URL exposed by 162 the CA and waits for the explicit revocation based on Certificate 163 Revocation List (CRL) and Online Certificate Status Protocol (OCSP) 164 to propagate to the relying parties. 166 In case the delegated identity is a domain name, this document also 167 provides a way for the NDC to inform the IdO about the CNAME mappings 168 that need to be installed in the IdO's DNS zone to enable the 169 aliasing of the delegated name, thus allowing the complete name 170 delegation workflow to be handled using a single interface. 172 We note that other standardization efforts address the problem of 173 certificate delegation for TLS connections, specifically 174 [I-D.ietf-tls-subcerts] and [I-D.mglt-lurk-tls13]. The former 175 extends the TLS certificate chain with a customer-owned signing 176 certificate; the latter separates the server's private key into a 177 dedicated, more secure component. Compared to these other 178 approaches, the current document does not require changes to the TLS 179 network stack of the client or the server, nor does it introduce 180 additional latency to the TLS connection. 182 1.1. Terminology 184 IdO Identifier Owner, the holder (current owner) of an identifier 185 (e.g., a domain name) that needs to be delegated. Depending on 186 the context, the term IdO may also be used to designate the 187 (profiled) ACME server deployed by the Identifier Owner or the 188 ACME client used by the Identifier Owner to interact with the CA. 190 NDC Name Delegation Consumer, the entity to which the domain name is 191 delegated for a limited time. This is a CDN in the primary use 192 case (in fact, readers may note the similarity of the two 193 acronyms). Depending on the context, the term NDC may also be 194 used to designate the (profiled) ACME client used by the Name 195 Delegation Consumer. 197 CDN Content Delivery Network, a widely distributed network that 198 serves the domain's web content to a wide audience at high 199 performance. 201 STAR Short-Term, Automatically Renewed X.509 certificates. 203 ACME Automated Certificate Management Environment, a certificate 204 management protocol [RFC8555]. 206 CA A Certification Authority that implements the ACME protocol. In 207 this document, the term is synonymous with "ACME server deployed 208 by the Certification Authority". 210 CSR A PKCS#10 [RFC2986] Certificate Signing Request, as supported by 211 ACME. 213 FQDN Fully Qualified Domain Name. 215 1.2. Conventions used in this document 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 219 "OPTIONAL" in this document are to be interpreted as described in 220 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 221 capitals, as shown here. 223 2. Protocol Flow 225 This section presents the protocol flow. For completeness, we 226 include the ACME profile proposed in this document as well as the 227 ACME STAR protocol described in [RFC8739]. 229 2.1. Preconditions 231 The protocol assumes the following preconditions are met: 233 * The IdO exposes an ACME server interface to the NDC(s) comprising 234 the account management interface; 235 * The NDC has registered an ACME account with the IdO; 236 * NDC and IdO have agreed on a "CSR template" to use, including at a 237 minimum: subject name (e.g., "abc.ido.example"), requested 238 algorithms and key length, key usage, extensions. The NDC will 239 use this template for every CSR created under the same delegation; 240 * IdO has registered an ACME account with the Certification 241 Authority (CA) 243 Note that even if the IdO implements the ACME server role, it is not 244 acting as a CA: in fact, from the point of view of the certificate 245 issuance process, the IdO only works as a "policing" forwarder of the 246 NDC's key-pair and is responsible for completing the identity 247 verification process towards the CA. 249 2.2. Overview 251 For clarity, the protocol overview presented here covers the main use 252 case of this protocol, namely delegation of STAR certificates. 253 Protocol behavior for non-STAR certificates is similar, and the 254 detailed differences are listed in the following sections. 256 The interaction between the NDC and the IdO is governed by the 257 profiled ACME workflow detailed in Section 2.3. The interaction 258 between the IdO and the CA is ruled by ACME [RFC8555], ACME STAR 259 [RFC8739] as well as any other ACME extension that applies (e.g., 260 [I-D.ietf-acme-authority-token-tnauthlist] for STIR). 262 The outline of the combined protocol for STAR certificates is as 263 follow (Figure 1): 265 * NDC sends an order Order1 for the delegated identifier to IdO; 266 * IdO creates an Order1 resource in state "ready" with a "finalize" 267 URL; 268 * NDC immediately sends a finalize request (which includes the CSR) 269 to the IdO; 270 * IdO verifies the CSR according to the agreed upon CSR template; 271 * If the CSR verification fails, Order1 is moved to an "invalid" 272 state and everything stops; 273 * If the CSR verification is successful, IdO moves Order1 to state 274 "processing", and sends a new Order2 (using its own account) for 275 the delegated identifier to the CA; 276 * If the ACME STAR protocol fails, Order2 moves to "invalid" and the 277 same state is reflected in Order1 (i.e., the NDC Order); 278 * If the ACME STAR run is successful (i.e., Order2 is "valid"), IdO 279 copies the "star-certificate" URL from Order2 to Order1 and 280 updates the Order1 state to "valid". 282 The NDC can now download, install and use the short-term certificate 283 bearing the name delegated by the IdO. This can continue until the 284 STAR certificate expires or the IdO decides to cancel the automatic 285 renewal process with the CA. 287 Note that the interactive identifier authorization phase described in 288 Section 7.5 of [RFC8555] is suppressed on the NDC-IdO side because 289 the delegated identity contained in the CSR presented to the IdO is 290 validated against the configured CSR template (Section 4.1). 291 Therefore, the NDC sends the finalize request, including the CSR, to 292 the IdO immediately after Order1 has been acknowledged. The IdO 293 SHALL buffer a (valid) CSR until the Validation phase completes 294 successfully. 296 Also note that the successful negotiation of the "unauthenticated 297 GET" (Section 3.4 of [RFC8739]) is required in order to allow the NDC 298 to access the "star-certificate" URL on the CA. 300 .------. .---------------. .------. 301 | NDC | | IdO | | ACME | 302 +--------+ +--------+--------+ +--------+ 303 | Client | | Server | Client | | Server | 304 '---+----' '----+---+---+----' '----+---' 305 | | | | 306 | Order1 | | | 307 | Signature | | | 308 o------------------->| | | 309 | | | | 310 | [ No identity ] | | | 311 | [ validation via ] | | | 312 | [ authorizations ] | | | 313 | | | | 314 | CSR | | | 315 | Signature | | | 316 o------------------->| | | 317 | Acknowledgement | | Order2 | 318 |<-------------------o | Signature | 319 | | o------------------->| 320 | | | Required | 321 | | | Authorizations | 322 | | |<-------------------o 323 | | | Responses | 324 | | | Signature | 325 | | o------------------->| 326 | | | | 327 | | |<~~~~Validation~~~~>| 328 | | | | 329 | | | CSR | 330 | | | Signature | 331 | | o------------------->| 332 | | | Acknowledgement | 333 | | |<-------------------o 334 | | | | 335 |<~~Await issuance~->| |<~~Await issuance~~>| 336 | | 337 | (unauthenticated) GET STAR certificate | 338 o------------------------------------------------>| 339 | Certificate #1 | 340 |<------------------------------------------------o 341 | (unauthenticated) GET STAR certificate | 342 o------------------------------------------------>| 343 | Certificate #2 | 344 |<------------------------------------------------o 345 | [...] | 346 | (unauthenticated) GET STAR certificate | 347 o------------------------------------------------>| 348 | Certificate #n | 349 |<------------------------------------------------o 351 Figure 1: End to end STAR delegation flow 353 2.3. Delegated Identity Profile 355 This section defines a profile of the ACME protocol, to be used 356 between the NDC and IdO. 358 2.3.1. Delegation Configuration 360 The IdO must be preconfigured to recognize one or more NDCs, and 361 present them with details about certificate delegations that apply to 362 each one. 364 2.3.1.1. Account Object Extensions 366 An NDC identifies itself to the IdO as an ACME account. The IdO can 367 delegate multiple names to a NDC, and these configurations are 368 described through "delegation" objects associated with the NDC's 369 Account object on the IdO. 371 As shown in Figure 2, the ACME account resource on the IdO is 372 extended with a new "delegations" attribute: 374 * delegations (required, string): A URL from which a list of 375 delegations configured for this account (Section 2.3.1.3) can be 376 fetched via a POST-as-GET request. 378 { 379 "status": "valid", 380 "contact": [ 381 "mailto:delegation-admin@ido.example" 382 ], 383 "termsOfServiceAgreed": true, 384 "orders": "https://example.com/acme/orders/saHpfB", 385 "delegations": "https://acme.ido.example/acme/delegations/adFqoz" 386 } 388 Figure 2: Example Account object with delegations 390 2.3.1.2. Delegation Lists 392 Each account object includes a "delegations" URL from which a list of 393 delegation configurations created by the IdO can be fetched via POST- 394 as-GET request. The result of the request MUST be a JSON object 395 whose "delegations" field is an array of URLs, each identifying a 396 delegation configuration made available to the NDC account 397 (Section 2.3.1.3). The server MAY return an incomplete list, along 398 with a Link header field with a "next" link relation indicating where 399 further entries can be acquired. 401 HTTP/1.1 200 OK 402 Content-Type: application/json 403 Link: ;rel="index" 404 Link: ;rel="next" 406 { 407 "delegations": [ 408 "https://acme.ido.example/acme/delegation/ogfr8EcolOT", 409 "https://acme.ido.example/acme/delegation/wSi5Lbb61E4", 410 /* more URLs not shown for example brevity */ 411 "https://acme.ido.example/acme/delegation/gm0wfLYHBen" 412 ] 413 } 415 2.3.1.3. Delegation Objects 417 This profile extends the ACME resource model with a new read-only 418 delegation object that represents a delegation configuration that 419 applies to a given NDC. 421 A delegation object contains the CSR template (see Section 4) that 422 applies to that delegation, and optionally any related CNAME mapping 423 for the delegated identifiers. Its structure is as follows: 425 * csr-template (required, object): CSR template as defined in 426 Section 4. 427 * cname-map (optional, object): a map of FQDN pairs. In each pair, 428 the name is the delegated identifier, the value is the 429 corresponding NDC name that is aliased in the IdO's zone file to 430 redirect the resolvers to the delegated entity. Both names and 431 values MUST be FQDNs with a terminating '.'. This field is only 432 meaningful for identifiers of type "dns". 434 An example delegation object in JSON format is shown in Figure 3. 436 { 437 "csr-template": { 438 "keyTypes": [ 439 { 440 "PublicKeyType": "id-ecPublicKey", 441 "namedCurve": "secp256r1", 442 "SignatureType": "ecdsa-with-SHA256" 443 } 444 ], 445 "subject": { 446 "country": "CA", 447 "stateOrProvince": "**", 448 "locality": "**" 449 }, 450 "extensions": { 451 "subjectAltName": { 452 "DNS": [ 453 "abc.ido.example" 454 ] 455 }, 456 "keyUsage": [ 457 "digitalSignature" 458 ], 459 "extendedKeyUsage": [ 460 "serverAuth" 461 ] 462 } 463 }, 464 "cname-map": { 465 "abc.ido.example.": "abc.ndc.example." 466 } 467 } 469 Figure 3: Example Delegation Configuration object 471 In order to indicate which specific delegation applies to the 472 requested certificate a new "delegation" attribute is added to the 473 request object on the NDC-IdO side (see Figure 4 and Figure 7). The 474 value of this attribute is the URL pointing to the delegation 475 configuration object that is to be used for this certificate request. 476 If the "delegation" attribute in the Order object contains a URL that 477 does not correspond to a configuration available to the requesting 478 ACME account, the IdO MUST return an error response with status code 479 403 (Forbidden), providing a problem document [RFC7807] with type 480 "urn:ietf:params:acme:error:unknownDelegation". 482 2.3.2. Order Object Transmitted from NDC to IdO and to ACME Server 483 (STAR) 485 If the delegation is for a STAR certificate, the request object 486 created by the NDC: 488 * MUST have a "delegation" attribute indicating the preconfigured 489 delegation that applies to this Order; 490 * MUST have entries in the "identifiers" field for each delegated 491 name present in the configuration; 492 * MUST NOT contain the "notBefore" and "notAfter" fields; 493 * MUST contain an "auto-renewal" object and inside it, the fields 494 listed in Section 3.1.1 of [RFC8739]. In particular, the "allow- 495 certificate-get" attribute MUST be present and set to true. 497 POST /acme/new-order HTTP/1.1 498 Host: acme.ido.example 499 Content-Type: application/jose+json 501 { 502 "protected": base64url({ 503 "alg": "ES256", 504 "kid": "https://acme.ido.example/acme/acct/evOfKhNU60wg", 505 "nonce": "Alc00Ap6Rt7GMkEl3L1JX5", 506 "url": "https://acme.ido.example/acme/new-order" 507 }), 508 "payload": base64url({ 509 "identifiers": [ 510 { 511 "type": "dns", 512 "value": "abc.ido.example" 513 } 514 ], 515 "auto-renewal": { 516 "end-date": "2021-04-20T00:00:00Z", 517 "lifetime": 345600, // 4 days 518 "allow-certificate-get": true 519 }, 520 "delegation": 521 "https://acme.ido.example/acme/delegation/gm0wfLYHBen" 522 }), 523 "signature": "g454e3hdBlkT4AEw...nKePnUyZTjGtXZ6H" 524 } 526 Figure 4: New STAR Order from NDC 528 The Order object that is created on the IdO: 530 * MUST start in the "ready" state; 531 * MUST contain an "authorizations" array with zero elements; 532 * MUST contain the indicated "delegation" configuration; 533 * MUST contain the indicated "auto-renewal" settings; 534 * MUST NOT contain the "notBefore" and "notAfter" fields. 536 { 537 "status": "ready", 538 "expires": "2021-05-01T00:00:00Z", 540 "identifiers": [ 541 { 542 "type": "dns", 543 "value": "abc.ido.example" 544 } 545 ], 547 "auto-renewal": { 548 "end-date": "2021-04-20T00:00:00Z", 549 "lifetime": 345600, 550 "allow-certificate-get": true 551 }, 553 "delegation": 554 "https://acme.ido.example/acme/delegation/gm0wfLYHBen", 556 "authorizations": [], 558 "finalize": "https://acme.ido.example/acme/order/TO8rfgo/finalize" 559 } 561 Figure 5: STAR Order Resource Created on IdO 563 The Order is then finalized by the NDC supplying the CSR containing 564 the delegated identifiers. The IdO checks the provided CSR against 565 the template contained in the delegation object that applies to this 566 request, as described in Section 4.1. If the CSR fails validation 567 for any of the identifiers, the IdO MUST return an error response 568 with status code 403 (Forbidden) and an appropriate type, e.g., 569 "rejectedIdentifier" or "badCSR". The error response SHOULD contain 570 subproblems (Section 6.7.1 of [RFC8555]) for each failed identifier. 571 If the CSR is successfully validated, the Order object status moves 572 to "processing" and the twin ACME protocol instance is initiated on 573 the IdO-CA side. 575 The request object created by the IdO: 577 * MUST copy the identifiers sent by the NDC; 578 * MUST strip the "delegation" attribute; 579 * MUST carry a copy of the "auto-renewal" object sent by the NDC. 581 When the identifiers' authorization has been successfully completed 582 and the certificate has been issued by the CA, the IdO: 584 * MUST move its Order resource status to "valid"; 585 * MUST copy the "star-certificate" field from the STAR Order 586 returned by the CA into its Order resource. When dereferenced, 587 the "star-certificate" URL includes (via the Cert-Not-Before and 588 Cert-Not-After HTTP header fields) the renewal timers needed by 589 the NDC to inform its certificate reload logic. 591 { 592 "status": "valid", 593 "expires": "2021-05-01T00:00:00Z", 595 "identifiers": [ 596 { 597 "type": "dns", 598 "value": "abc.ido.example" 599 } 600 ], 602 "auto-renewal": { 603 "end-date": "2021-04-20T00:00:00Z", 604 "lifetime": 345600, 605 "allow-certificate-get": true 606 }, 608 "delegation": 609 "https://acme.ido.example/acme/delegation/gm0wfLYHBen", 611 "authorizations": [], 613 "finalize": "https://acme.ido.example/acme/order/TO8rfgo/finalize", 615 "star-certificate": "https://acme.ca.example/acme/order/yTr23sSDg9" 616 } 618 Figure 6: STAR Order Resource Updated on IdO 620 This delegation protocol is predicated on the NDC being able to fetch 621 certificates periodically using an unauthenticated HTTP GET, since in 622 general the NDC does not possess an account on the CA and therefore 623 cannot issue the standard POST-as-GET ACME request. Therefore, 624 before forwarding the Order request to the CA, the IdO SHOULD ensure 625 that the selected CA supports "unauthenticated GET" by inspecting the 626 relevant settings in the CA's "directory" object, as per Section 3.4 627 of [RFC8739]. If the CA does not support "unauthenticated GET" of 628 STAR certificates, the IdO MUST NOT forward the Order request. 629 Instead, it MUST move the Order status to "invalid" and set the 630 "allow-certificate-get" in the "auto-renewal" object to "false". The 631 same occurs in case the Order request is forwarded and the CA does 632 not reflect the "allow-certificate-get" setting in its Order 633 resource. The combination of "invalid" status and denied "allow- 634 certificate-get" in the Order resource at the IdO provides an 635 unambiguous (asynchronous) signal to the NDC about the failure 636 reason. 638 2.3.2.1. CNAME Installation 640 If an identifier object of type "dns" was included, the IdO can add 641 the CNAME records specified in the delegation object to its zone, 642 e.g.: 644 abc.ido.example. CNAME abc.ndc.example. 646 2.3.3. Order Object Transmitted from NDC to IdO and to ACME Server 647 (non-STAR) 649 If the delegation is for a non-STAR certificate, the request object 650 created by the NDC: 652 * MUST have a "delegation" attribute indicating the preconfigured 653 delegation that applies to this Order; 654 * MUST have entries in the "identifiers" field for each delegated 655 name present in the configuration; 656 * MUST have the "allow-certificate-get" attribute set to true. 658 POST /acme/new-order HTTP/1.1 659 Host: acme.ido.example 660 Content-Type: application/jose+json 662 { 663 "protected": base64url({ 664 "alg": "ES256", 665 "kid": "https://acme.ido.example/acme/acct/evOfKhNU60wg", 666 "nonce": "IYBkoQfaCS80UcCn9qH8Gt", 667 "url": "https://acme.ido.example/acme/new-order" 668 }), 669 "payload": base64url({ 670 "identifiers": [ 671 { 672 "type": "dns", 673 "value": "abc.ido.example" 674 } 675 ], 676 "delegation": 677 "https://acme.ido.example/acme/delegation/gm0wfLYHBen", 678 "allow-certificate-get": true 679 }), 680 "signature": "j9JBUvMigi4zodud...acYkEKaa8gqWyZ6H" 681 } 683 Figure 7: New Non-STAR Order from NDC 685 The Order object that is created on the IdO: 687 * MUST start in the "ready" state; 688 * MUST contain an "authorizations" array with zero elements; 689 * MUST contain the indicated "delegation" configuration; 690 * MUST contain the indicated "allow-certificate-get" setting. 692 { 693 "status": "ready", 694 "expires": "2021-05-01T00:00:00Z", 696 "identifiers": [ 697 { 698 "type": "dns", 699 "value": "abc.ido.example" 700 } 701 ], 703 "delegation": 704 "https://acme.ido.example/acme/delegation/gm0wfLYHBen", 706 "allow-certificate-get": true, 708 "authorizations": [], 710 "finalize": "https://acme.ido.example/acme/order/3ZDlhYy/finalize" 711 } 713 Figure 8: Non-STAR Order Resource Created on IdO 715 The Order finalization by the NDC and the subsequent validation of 716 the CSR by the IdO proceed in the same way as for the STAR case. If 717 the CSR is successfully validated, the Order object status moves to 718 "processing" and the twin ACME protocol instance is initiated on the 719 IdO-CA side. 721 The request object created by the IdO: 723 * MUST copy the identifiers sent by the NDC; 724 * MUST strip the "delegation" attribute; 725 * MUST copy the "allow-certificate-get" attribute. 727 When the identifiers' authorization has been successfully completed 728 and the certificate has been issued by the CA, the IdO: 730 * MUST move its Order resource status to "valid"; 731 * MUST copy the "certificate" field from the Order returned by the 732 CA into its Order resource, as well as "notBefore" and "notAfter" 733 if these fields exist. 735 { 736 "status": "valid", 737 "expires": "2021-05-01T00:00:00Z", 739 "identifiers": [ 740 { 741 "type": "dns", 742 "value": "abc.ido.example" 743 } 744 ], 746 "delegation": 747 "https://acme.ido.example/acme/delegation/gm0wfLYHBen", 749 "allow-certificate-get": true, 751 "authorizations": [], 753 "finalize": "https://acme.ido.example/acme/order/3ZDlhYy/finalize", 755 "certificate": "https://acme.ca.example/acme/order/YtR23SsdG9" 756 } 758 Figure 9: Non-STAR Order Resource Updated on IdO 760 At this point of the protocol flow, the same considerations as in 761 Section 2.3.2.1 apply. 763 Before forwarding the Order request to the CA, the IdO SHOULD ensure 764 that the selected CA supports "unauthenticated GET" by inspecting the 765 relevant settings in the CA's "directory" object, as per 766 Section 2.3.5. If the CA does not support "unauthenticated GET" of 767 certificate resources, the IdO MUST NOT forward the Order request. 768 Instead, it MUST move the Order status to "invalid" and set the 769 "allow-certificate-get" attribute to "false". The same occurs in 770 case the Order request is forwarded and the CA does not reflect the 771 "allow-certificate-get" setting in its Order resource. The 772 combination of "invalid" status and denied "allow-certificate-get" in 773 the Order resource at the IdO provides an unambiguous (asynchronous) 774 signal to the NDC about the failure reason. 776 2.3.4. Capability Discovery 778 In order to help a client to discover support for this profile, the 779 directory object of an ACME server (typically, one deployed by the 780 IdO) contains the following attribute in the "meta" field: 782 * delegation-enabled (optional, boolean): Boolean flag indicating 783 support for the profile specified in this memo. An ACME server 784 that supports this delegation profile MUST include this key, and 785 MUST set it to true. 787 The IdO MUST declare its support for delegation using "delegation- 788 enabled" regardless of whether it supports delegation of STAR 789 certificates, non-STAR certificates or both. 791 In order to help a client to discover support for certificate 792 fetching using unauthenticated HTTP GET, the directory object of an 793 ACME server (typically, one deployed by the CA) contains the 794 following attribute in the "meta" field: 796 * allow-certificate-get (optional, boolean): See Section 2.3.5. 798 2.3.5. Negotiating an Unauthenticated GET 800 In order to enable the name delegation of non-STAR certificates, this 801 document defines a mechanism that allows a server to advertise 802 support for accessing certificate resources via unauthenticated GET 803 (in addition to POST-as-GET), and a client to enable this service 804 with per-Order granularity. 806 It is worth pointing out that the protocol elements described in this 807 section have the same names and semantics as those introduced in 808 Section 3.4 of [RFC8739] for the STAR use case (except, of course, 809 they apply to the certificate resource rather than the star- 810 certificate resource). However, they differ in terms of their 811 position in the directory meta and order objects: rather than being 812 wrapped in an auto-renewal sub-object they are located at the top- 813 level. 815 A server states its availability to grant unauthenticated access to a 816 client's Order certificate by setting the "allow-certificate-get" 817 attribute to "true" in the "meta" field inside the directory object: 819 * allow-certificate-get (optional, boolean): If this field is 820 present and set to "true", the server allows GET (and HEAD) 821 requests to certificate URLs. 823 A client states its desire to access the issued certificate via 824 unauthenticated GET by adding an "allow-certificate-get" attribute to 825 the payload of its newOrder request and setting it to "true". 827 * allow-certificate-get (optional, boolean): If this field is 828 present and set to "true", the client requests the server to allow 829 unauthenticated GET (and HEAD) to the certificate associated with 830 this Order. 832 If the server accepts the request, it MUST reflect the attribute 833 setting in the resulting order object. 835 Note that even when the use of unauthenticated GET has been agreed 836 upon, the server MUST also allow POST-as-GET requests to the 837 certificate resource. 839 2.3.6. Terminating the Delegation 841 Identity delegation is terminated differently depending on whether 842 this is a STAR certificate or not. 844 2.3.6.1. By Cancellation (STAR) 846 The IdO can terminate the delegation of a STAR certificate by 847 requesting its cancellation (see Section 3.1.2 of [RFC8739]). 849 Cancellation of the ACME STAR certificate is a prerogative of the 850 IdO. The NDC does not own the relevant account key on the CA, 851 therefore it can't issue a cancellation request for the STAR 852 certificate. Potentially, since it holds the STAR certificate's 853 private key, it could request the revocation of a single STAR 854 certificate. However, STAR explicitly disables the revokeCert 855 interface. 857 Shortly after the automatic renewal process is stopped by the IdO, 858 the last issued STAR certificate expires and the delegation 859 terminates. 861 2.3.6.2. By Revocation (non-STAR) 863 The IdO can terminate the delegation of a non-STAR certificate by 864 requesting it to be revoked using the revokeCert URL exposed by the 865 CA. 867 According to Section 7.6 of [RFC8555], the revocation endpoint can be 868 used with either the account keypair, or the certificate keypair. In 869 other words, an NDC that learns the revokeCert URL of the CA (which 870 is publicly available via the CA's Directory object) would be able to 871 revoke the certificate using the associated private key. However, 872 given the trust relationship between NDC and IdO expected by the 873 delegation trust model (Section 7.1), as well as the lack of 874 incentives for the NDC to prematurely terminate the delegation, this 875 does not represent a significant security risk. 877 2.4. Proxy Behavior 879 There are cases where the ACME Delegation flow should be proxied, 880 such as the use case described in Section 5.1.2. This section 881 describes the behavior of such proxies. 883 An entity implementing the IdO server role - an "ACME Delegation 884 server" - may behave, on a per-identity case, either as a proxy into 885 another ACME Delegation server, or it may behave as an IdO and obtain 886 a certificate directly. The determining factor is whether it can 887 successfully be authorized by the next-hop ACME server for the 888 identity associated with the certificate request. 890 The identities supported by each server and the disposition for each 891 of them are preconfigured. 893 Following is the proxy's behavior for each of the messages exchanged 894 in the ACME Delegation process: 896 * New-order request: 897 - The complete "identifiers" object MUST be copied as-is. 898 - Similarly, the "auto-renewal" object MUST be copied as-is. 899 * New-order response: 900 - The "status", "expires", "authorizations", "identifiers" and 901 "auto-renewal" attributes/objects MUST be copied as-is. 902 - The "finalize" URL is rewritten, so that the "finalize" request 903 will be made to the proxy. 904 - Similarly, the "Location" header MUST be rewritten to point to 905 an Order object on the proxy. 906 - Any "Link" relations MUST be rewritten to point to the proxy. 907 * Get Order response: 908 - The "status", "expires", "authorizations", "identifiers" and 909 "auto-renewal" attributes/objects MUST be copied as-is. 910 - Similarly, the "star-certificate" URL (or the "certificate" URL 911 in case of non-STAR requests) MUST be copied as-is. 912 - The "finalize" URL is rewritten, so that the "finalize" request 913 will be made to the proxy. 915 - The "Location" header MUST be rewritten to point to an Order 916 object on the proxy. 917 - Any "Link" relations MUST be rewritten to point to the proxy. 918 * Finalize request: 919 - The CSR MUST be copied as-is. 920 * Finalize response: 921 - The "Location" header, "Link" relations and the "finalize" URLs 922 are rewritten as for Get Order. 924 We note that all the above messages are authenticated, and therefore 925 each proxy must be able to authenticate any subordinate server. 927 3. CA Behavior 929 Although most of this document, and in particular Section 2 is 930 focused on the protocol between the NDC and to IdO, the protocol does 931 affect the ACME server running in the CA. A CA that wishes to 932 support certificate delegation MUST also support unauthenticated 933 certificate fetching, which it declares using "allow-certificate-get" 934 (Section 2.3.5, Paragraph 3). 936 4. CSR Template 938 The CSR template is used to express and constrain the shape of the 939 CSR that the NDC uses to request the certificate. The CSR is used 940 for every certificate created under the same delegation. Its 941 validation by the IdO is a critical element in the security of the 942 whole delegation mechanism. 944 Instead of defining every possible CSR attribute, this document takes 945 a minimalist approach by declaring only the minimum attribute set and 946 deferring the registration of further, more specific, attributes to 947 future documents. 949 4.1. Template Syntax 951 The template is a JSON document. Each field (with the exception of 952 "keyTypes", see below) denotes one of: 954 * A mandatory field, where the template specifies the literal value 955 of that field. This is denoted by a literal string, such as 956 "abc.ido.example". 957 * A mandatory field, where the content of the field is defined by 958 the client. This is denoted by "**". 959 * An optional field, where the client decides whether the field is 960 included in the CSR and if so, what its value is. This is denoted 961 by "*". 963 The NDC MUST NOT include in the CSR any fields, including any 964 extensions, unless they are specified in the template. 966 The structure of the template object is defined by the CDDL [RFC8610] 967 document in Appendix B. An alternative, non-normative JSON Schema 968 syntax is given in Appendix C. While the CSR template must follow 969 the syntax defined here, neither the IdO nor the NDC are expected to 970 validate it at run-time. 972 The "subject" field and its subfields are mapped into the "subject" 973 field of the CSR, as per [RFC5280], Section 4.1.2.6. Other extension 974 fields of the CSR template are mapped into the CSR according to the 975 table in Section 6.5. 977 The "subjectAltName" field is currently defined for the following 978 identifiers: DNS names, email addresses, and URIs. New identifier 979 types may be added in the future by documents that extend this 980 specification. Each new identifier type SHALL have an associated 981 identifier validation challenge that the CA can use to obtain proof 982 of the requester's control over it. 984 The "keyTypes" property is not copied into the CSR. Instead, this 985 property constrains the "SubjectPublicKeyInfo" field of the CSR, 986 which MUST have the type/size defined by one of the array members of 987 the "keyTypes" property. 989 When the IdO receives the CSR, it MUST verify that the CSR is 990 consistent with the template contained in the "delegation" object 991 referenced in the Order. The IdO MAY enforce additional constraints, 992 e.g., by restricting field lengths. In this regard, note that a 993 "subjectAltName" of type "DNS" can be specified using the wildcard 994 notation, meaning that the NDC can be required ("**") or offered the 995 possibility ("*") to define the delegated domain name by itself. If 996 this is the case, the IdO MUST apply application-specific checks on 997 top of the control rules already provided by the CSR template to 998 ensure the requested domain name is legitimate according to its local 999 policy. 1001 4.2. Example 1003 The CSR template in Figure 10 represents one possible CSR template 1004 governing the delegation exchanges provided in the rest of this 1005 document. 1007 { 1008 "keyTypes": [ 1009 { 1010 "PublicKeyType": "rsaEncryption", 1011 "PublicKeyLength": 2048, 1012 "SignatureType": "sha256WithRSAEncryption" 1013 }, 1014 { 1015 "PublicKeyType": "id-ecPublicKey", 1016 "namedCurve": "secp256r1", 1017 "SignatureType": "ecdsa-with-SHA256" 1018 } 1019 ], 1020 "subject": { 1021 "country": "CA", 1022 "stateOrProvince": "**", 1023 "locality": "**" 1024 }, 1025 "extensions": { 1026 "subjectAltName": { 1027 "DNS": [ 1028 "abc.ido.example" 1029 ] 1030 }, 1031 "keyUsage": [ 1032 "digitalSignature" 1033 ], 1034 "extendedKeyUsage": [ 1035 "serverAuth", 1036 "clientAuth" 1037 ] 1038 } 1039 } 1041 Figure 10: Example CSR template 1043 5. Further Use Cases 1045 This non-normative section describes additional use cases that use 1046 STAR certificate delegation in non-trivial ways. 1048 5.1. CDN Interconnection (CDNI) 1050 [I-D.ietf-cdni-interfaces-https-delegation] discusses several 1051 solutions addressing different delegation requirements for the CDNI 1052 (CDN Interconnection) environment. This section discusses two of the 1053 stated requirements in the context of the STAR delegation workflow. 1055 This section uses specifically CDNI terminology, e.g., "uCDN" and 1056 "dCDN", as defined in [RFC7336]. 1058 5.1.1. Multiple Parallel Delegates 1060 In some cases the content owner (IdO) would like to delegate 1061 authority over a web site to multiple NDCs (CDNs). This could happen 1062 if the IdO has agreements in place with different regional CDNs for 1063 different geographical regions, or if a "backup" CDN is used to 1064 handle overflow traffic by temporarily altering some of the CNAME 1065 mappings in place. The STAR delegation flow enables this use case 1066 naturally, since each CDN can authenticate separately to the IdO (via 1067 its own separate account) specifying its CSR, and the IdO is free to 1068 allow or deny each certificate request according to its own policy. 1070 5.1.2. Chained Delegation 1072 In other cases, a content owner (IdO) delegates some domains to a 1073 large CDN (uCDN), which in turn delegates to a smaller regional CDN, 1074 dCDN. The IdO has a contractual relationship with uCDN, and uCDN has 1075 a similar relationship with dCDN. However IdO may not even know 1076 about dCDN. 1078 If needed, the STAR protocol can be chained to support this use case: 1079 uCDN could forward requests from dCDN to IdO, and forward responses 1080 back to dCDN. Whether such proxying is allowed is governed by policy 1081 and contracts between the parties. 1083 A mechanism is necessary at the interface between uCDN and dCDN by 1084 which the uCDN can advertise: 1086 * The names that the dCDN is allowed to use; 1087 * The policy for creating the key material (allowed algorithms, 1088 minimum key lengths, key usage, etc.) that the dCDN needs to 1089 satisfy. 1091 Note that such mechanism is provided by the CSR template. 1093 5.1.2.1. Two-Level Delegation in CDNI 1095 A User Agent (UA), browser or set-top-box, wants to fetch the video 1096 resource at the following URI: "https://video.cp.example/movie". 1097 Redirection between Content Provider (CP), upstream, and downstream 1098 CDNs is arranged as a CNAME-based aliasing chain as illustrated in 1099 Figure 11. 1101 .------------. 1102 video.cp.example ? | .-----. | 1103 .---------------------------------->| | | 1104 | (a) | | DNS | CP | 1105 | .-------------------------------+ | | 1106 | | CNAME video.ucdn.example | '-----' | 1107 | | '------------' 1108 | | 1109 | | 1110 .-----------|---v--. .------------. 1111 | .-----.-+-----. | video.ucdn.example ? | .-----. | 1112 | | | +----------------------------->| | | 1113 | UA | TLS | DNS | | (b) | | DNS | uCDN | 1114 | | | |<-----------------------------+ | | 1115 | '--+--'-----+-' | CNAME video.dcdn.example | '-----' | 1116 '------|----^---|--' '------------' 1117 | | | 1118 | | | 1119 | | | .------------. 1120 | | | video.dcdn.example ? | .-----. | 1121 | | '------------------------------>| | | 1122 | | (c) | | DNS | | 1123 | '-----------------------------------+ | | 1124 | A 192.0.2.1 | +-----+ dCDN | 1125 | | | | | 1126 '--------------------------------------->| TLS | | 1127 SNI: video.cp.example | | | | 1128 | '-----' | 1129 '------------' 1131 Figure 11: DNS Redirection 1133 Unlike HTTP-based redirection, where the original URL is supplanted 1134 by the one found in the Location header of the 302 response, DNS 1135 redirection is completely transparent to the User Agent. As a 1136 result, the TLS connection to the dCDN edge is done with a Server 1137 Name Indication (SNI) equal to the "host" in the original URI - in 1138 the example, "video.cp.example". So, in order to successfully 1139 complete the handshake, the landing dCDN node has to be configured 1140 with a certificate whose subjectAltName matches "video.cp.example", 1141 i.e., a Content Provider's name. 1143 Figure 12 illustrates the cascaded delegation flow that allows dCDN 1144 to obtain a STAR certificate that bears a name belonging to the 1145 Content Provider with a private key that is only known to the dCDN. 1147 .--------------------. 1148 | .------.------. | 1149 | | STAR | ACME |<-------------. 1150 | CP | dele | STAR | | | 1151 | | srv | cli +-----. | 1152 | '---+--'------' | | 6 1153 '---------|------^---' 5 | 1154 | | | .--|-------. 1155 | | | | .-+----. | 1156 7 | '---->| ACME | | 1157 | | | | STAR | C | 1158 | 4 | +------| A | 1159 | | | | HTTP | | 1160 | | | '----+-' | 1161 | .-' '--^--|----' 1162 .--------------v--|--. | | 1163 | .------.----+-. | | 10 1164 | | | STAR | | | | 1165 | uCDN | CDNI | dele | | | | 1166 | | | fwd | | | | 1167 | '----+-'-+----' | | | 1168 '-------^--|---|--^--' | | 1169 | | | | | | 1170 | 2 8 | | | 1171 1 | | 3 | | 1172 | | | | 9 | 1173 .-------|--v---v--|---------. | | 1174 | .-+----.----+-.------. | | | 1175 | | | STAR | +------------' | 1176 | dCDN | CDNI | dele | HTTP | | | 1177 | | | cli | |<--------------' 1178 | '------'------'------' | 1179 '---------------------------' 1181 Figure 12: Two levels delegation in CDNI 1183 uCDN is configured to delegate to dCDN, and CP is configured to 1184 delegate to uCDN, both as defined in Section 2.3.1. 1186 1. dCDN requests CDNI path metadata to uCDN; 1187 2. uCDN replies with, among other CDNI metadata, the STAR 1188 delegation configuration, which includes the delegated Content 1189 Provider's name; 1190 3. dCDN creates a key-pair and the CSR with the delegated name. It 1191 then places an order for the delegated name to uCDN; 1192 4. uCDN forwards the received order to the Content Provider (CP); 1193 5. CP creates an order for a STAR certificate and sends it to the 1194 CA. The order also requests unauthenticated access to the 1195 certificate resource; 1196 6. After all authorizations complete successfully, the STAR 1197 certificate is issued; 1198 7. CP notifies uCDN that the STAR certificate is available at the 1199 order's star-certificate URL; 1200 8. uCDN forwards the information to dCDN. At this point the ACME 1201 signalling is complete; 1202 9. dCDN requests the STAR certificate using unauthenticated GET 1203 from the CA; 1204 10. the CA returns the certificate. Now dCDN is fully configured to 1205 handle HTTPS traffic in-lieu of the Content Provider. 1207 Note that 9. and 10. repeat until the delegation expires or is 1208 terminated. 1210 5.2. Secure Telephone Identity Revisited (STIR) 1212 As a second use case, we consider the delegation of credentials in 1213 the STIR ecosystem [I-D.ietf-stir-cert-delegation]. 1215 This section uses STIR terminology. The term PASSPorT is defined in 1216 [RFC8225], and "TNAuthList" in [RFC8226]. 1218 In the STIR "delegated" mode, a service provider SP2 - the NDC - 1219 needs to sign PASSPorT's [RFC8225] for telephone numbers (e.g., 1220 TN=+123) belonging to another service provider, SP1 - the IdO. In 1221 order to do that, SP2 needs a STIR certificate, and private key, that 1222 includes TN=+123 in the TNAuthList [RFC8226] certificate extension. 1224 In details (Figure 13): 1226 1. SP1 and SP2 agree on the configuration of the delegation - in 1227 particular, the CSR template that applies; 1228 2. SP2 generates a private/public key-pair and sends a CSR to SP1 1229 requesting creation of a certificate with: SP1 name, SP2 public 1230 key, and a TNAuthList extension with the list of TNs that SP1 1231 delegates to SP2. (Note that the CSR sent by SP2 to SP1 needs to 1232 be validated against the CSR template agreed upon in step 1.); 1233 3. SP1 sends an order for the CSR to the CA. The order also 1234 requests unauthenticated access to the certificate resource; 1235 4. Subsequently, after the required TNAuthList authorizations are 1236 successfully completed, the CA moves the order to a "valid" 1237 state; at the same time the star-certificate endpoint is 1238 populated; 1239 5. The order contents are forwarded from SP1 to SP2 by means of the 1240 paired "delegation" order; 1242 6. SP2 dereferences the star-certificate URL in the order to fetch 1243 the rolling STAR certificate bearing the delegated identifiers; 1244 7. The STAR certificate is returned to SP2. 1246 .-------------------. 1247 | .------.------. | 1248 | | STAR | STAR |<--------------. 1249 .-->| SP1 | dele | dele | | | 1250 | | | srv | cli +-----. | 1251 | | '----+-'------' | | 4 1252 | '------^--|---------' 3 | 1253 | | | | .----|-----. 1254 | | 5 | | .---+--. | 1255 | | | '--->| ACME | | 1256 | | | | | STAR | C | 1257 1 | | | +------| A | 1258 | | | .--->| HTTP | | 1259 | 2 | | | '---+--' | 1260 | | | | '----|-----' 1261 | .------|--v---------. 6 | 1262 | | .-+----.------. | | 7 1263 | | | STAR | +-----' | 1264 '-->| SP2 | dele | HTTP | | | 1265 | | cli | |<--------------' 1266 | '----+-'-+----' | 1267 '-------------------' 1269 Figure 13: Delegation in STIR 1271 As shown, the STAR delegation profile described in this document 1272 applies straightforwardly, the only extra requirement being the 1273 ability to instruct the NDC about the allowed TNAuthList values. 1274 This can be achieved by a simple extension to the CSR template. 1276 6. IANA Considerations 1278 [[RFC Editor: please replace XXXX below by the RFC number.]] 1280 6.1. New Fields in the "meta" Object within a Directory Object 1282 This document adds the following entries to the ACME Directory 1283 Metadata Fields registry: 1285 +=======================+============+===========+ 1286 | Field Name | Field Type | Reference | 1287 +=======================+============+===========+ 1288 | delegation-enabled | boolean | RFC XXXX | 1289 +-----------------------+------------+-----------+ 1290 | allow-certificate-get | boolean | RFC XXXX | 1291 +-----------------------+------------+-----------+ 1293 Table 1 1295 6.2. New Fields in the Order Object 1297 This document adds the following entries to the ACME Order Object 1298 Fields registry: 1300 +=======================+============+==============+===========+ 1301 | Field Name | Field Type | Configurable | Reference | 1302 +=======================+============+==============+===========+ 1303 | allow-certificate-get | boolean | true | RFC XXXX | 1304 +-----------------------+------------+--------------+-----------+ 1305 | delegation | string | true | RFC XXXX | 1306 +-----------------------+------------+--------------+-----------+ 1308 Table 2 1310 6.3. New Fields in the Account Object 1312 This document adds the following entries to the ACME Account Object 1313 Fields registry: 1315 +=============+============+==========+===========+ 1316 | Field Name | Field Type | Requests | Reference | 1317 +=============+============+==========+===========+ 1318 | delegations | string | none | RFC XXXX | 1319 +-------------+------------+----------+-----------+ 1321 Table 3 1323 Note that the "delegations" field is only reported by ACME servers 1324 that have "delegation-enabled" set to true in their meta Object. 1326 6.4. New Error Types 1328 This document adds the following entries to the ACME Error Type 1329 registry: 1331 +===================+================================+===========+ 1332 | Type | Description | Reference | 1333 +===================+================================+===========+ 1334 | unknownDelegation | An unknown configuration is | RFC XXXX | 1335 | | listed in the "delegations" | | 1336 | | attribute of the request Order | | 1337 +-------------------+--------------------------------+-----------+ 1339 Table 4 1341 6.5. CSR Template Extensions 1343 IANA is requested to establish a registry "STAR Delegation CSR 1344 Template Extensions", with "Specification Required" as its 1345 registration procedure. 1347 Each extension registered must specify: 1349 * An extension name. 1350 * An extension syntax, as a reference to a CDDL document that 1351 defines this extension. 1352 * The extension's mapping into an X.509 certificate extension. 1354 The initial contents of this registry are the extensions defined by 1355 the CDDL in Appendix B. 1357 +==================+===========+===============================+ 1358 | Extension Name | Extension | Mapping to X.509 Certificate | 1359 | | Syntax | Extension | 1360 +==================+===========+===============================+ 1361 | keyUsage | See | [RFC5280], Section 4.2.1.3 | 1362 | | Appendix | | 1363 | | B | | 1364 +------------------+-----------+-------------------------------+ 1365 | extendedKeyUsage | See | [RFC5280], Section 4.2.1.12 | 1366 | | Appendix | | 1367 | | B | | 1368 +------------------+-----------+-------------------------------+ 1369 | subjectAltName | See | [RFC5280], Section 4.2.1.6 | 1370 | | Appendix | (note that only specific name | 1371 | | B | formats are allowed: URI, DNS | 1372 | | | name, email address) | 1373 +------------------+-----------+-------------------------------+ 1375 Table 5 1377 When evaluating a request for an assignment in this registry, the 1378 designated expert should follow this guidance: 1380 * The definition must include a full CDDL definition, which the 1381 expert will validate. 1382 * The definition must include both positive and negative test cases. 1383 * Additional requirements that are not captured by the CDDL 1384 definition are allowed but must be explicitly specified. 1386 7. Security Considerations 1388 7.1. Trust Model 1390 The ACME trust model needs to be extended to include the trust 1391 relationship between NDC and IdO. Note that once this trust link is 1392 established, it potentially becomes recursive. Therefore, there has 1393 to be a trust relationship between each of the nodes in the 1394 delegation chain; for example, in case of cascading CDNs this is 1395 contractually defined. Note that using standard [RFC6125] identity 1396 verification there are no mechanisms available to the IdO to restrict 1397 the use of the delegated name once the name has been handed over to 1398 the first NDC. It is therefore expected that contractual measures 1399 are in place to get some assurance that re-delegation is not being 1400 performed. 1402 7.2. Delegation Security Goal 1404 Delegation introduces a new security goal: only an NDC that has been 1405 authorised by the IdO, either directly or transitively, can obtain a 1406 certificate with an IdO identity. 1408 From a security point of view, the delegation process has five 1409 separate parts: 1411 1. Enabling a specific third party (the intended NDC) to submit 1412 requests for delegated certificates; 1413 2. Making sure that any request for a delegated certificate matches 1414 the intended "shape" in terms of delegated identities as well as 1415 any other certificate metadata, e.g., key length, x.509 1416 extensions, etc.; 1417 3. Serving the certificate back to the NDC; 1418 4. A process for handling revocation of the delegation; 1419 5. A process for handling revocation of the certificate itself. 1421 The first part is covered by the NDC's ACME account that is 1422 administered by the IdO, whose security relies on the correct 1423 handling of the associated key pair. When a compromise of the 1424 private key is detected, the delegate MUST use the account 1425 deactivation procedures defined in Section 7.3.6 of [RFC8555]. 1427 The second part is covered by the act of checking an NDC's 1428 certificate request against the intended CSR template. The steps of 1429 shaping the CSR template correctly, selecting the right CSR template 1430 to check against the presented CSR, and making sure that the 1431 presented CSR matches the selected CSR template are all security 1432 relevant. 1434 The third part builds on the trust relationship between NDC and IdO 1435 that is responsible for correctly forwarding the certificate URL from 1436 the Order returned by the CA. 1438 The fourth part is associated with the ability of the IdO to 1439 unilaterally remove the delegation object associated with the revoked 1440 identity, therefore disabling any further NDC requests for such 1441 identity. Note that, in more extreme circumstances, the IdO might 1442 decide to disable the NDC account thus entirely blocking any further 1443 interaction. 1445 The fifth is covered by two different mechanisms, depending on the 1446 nature of the certificate. For STAR, the IdO shall use the 1447 cancellation interface defined in Section 2.3 of [RFC8739]. For non- 1448 STAR, the certificate revocation interface defined in Section 7.6 of 1449 [RFC8555]) is used. 1451 The ACME account associated with the delegation plays a crucial role 1452 in the overall security of the presented protocol. This, in turn, 1453 means that in delegation scenarios the security requirements and 1454 verification associated with an ACME account may be more stringent 1455 than in traditional ACME, since the out-of-band configuration of 1456 delegations that an account is authorized to use, combined with 1457 account authentication, takes the place of the normal ACME 1458 authorization challenge procedures. Therefore, the IdO MUST ensure 1459 that each account is associated with the exact policies (via their 1460 matching "delegation" objects) that define which domain names can be 1461 delegated to the account and how. The IdO is expected to use out of 1462 band means to pre-register each NDC to the corresponding account. 1464 7.3. New ACME Channels 1466 Using the model established in Section 10.1 of [RFC8555], we can 1467 decompose the interactions of the basic delegation workflow as shown 1468 in Figure 14. 1470 .-----. ACME Channel .--------. 1471 | NDC +------------->| IdO | 1472 '--+--' | server | 1473 | '--o-----' 1474 | | 1475 | | ACME Channel 1476 | | .------------>-------------. 1477 | | | | 1478 | .--o--+--. .--+---. 1479 | | IdO | | CA | 1480 | | client | '--+-+-' 1481 | '-----+--' | | 1482 | '-----------<--------------' | 1483 | Validation Channel | 1484 '-------------------->-------------------------------' 1485 (subset of) ACME Channel [1] 1487 [1] Unauthenticated certificate fetch and non-STAR certificate 1488 revocation. 1490 Figure 14: Delegation Channels Topology 1492 The considerations regarding the security of the ACME Channel and 1493 Validation Channel discussed in [RFC8555] apply verbatim to the IdO- 1494 CA leg. The same can be said for the ACME channel on the NDC-IdO 1495 leg. A slightly different set of considerations apply to the ACME 1496 Channel between NDC and CA, which consists of a subset of the ACME 1497 interface comprising two API endpoints: the unauthenticated 1498 certificate retrieval and, potentially, non-STAR revocation via 1499 certificate private key. No specific security considerations apply 1500 to the former, but the privacy considerations in Section 6.3 of 1501 [RFC8739] do. With regards to the latter, it should be noted that 1502 there is currently no means for an IdO to disable authorising 1503 revocation based on certificate private keys. So, in theory, an NDC 1504 could use the revocation API directly with the CA, therefore 1505 bypassing the IdO. The NDC SHOULD NOT directly use the revocation 1506 interface exposed by the CA unless failing to do so would compromise 1507 the overall security, for example if the certificate private key is 1508 compromised and the IdO is not currently reachable. 1510 All other security considerations from [RFC8555] and [RFC8739] apply 1511 as-is to the delegation topology. 1513 7.4. Restricting CDNs to the Delegation Mechanism 1515 When a web site is delegated to a CDN, the CDN can in principle 1516 modify the web site at will, create and remove pages. This means 1517 that a malicious or breached CDN can pass the ACME (as well as common 1518 non-ACME) HTTPS-based validation challenges and generate a 1519 certificate for the site. This is true regardless of whether the 1520 CNAME mechanisms defined in the current document is used or not. 1522 In some cases, this is the desired behavior: the domain holder trusts 1523 the CDN to have full control of the cryptographic credentials for the 1524 site. The current document however assumes a scenario where the 1525 domain holder only wants to delegate restricted control, and wishes 1526 to retain the capability to cancel the CDN's credentials at a short 1527 notice. 1529 The following is a possible mitigation when the IdO wishes to ensure 1530 that a rogue CDN cannot issue unauthorized certificates: 1532 * The domain holder makes sure that the CDN cannot modify the DNS 1533 records for the domain. The domain holder should ensure it is the 1534 only entity authorized to modify the DNS zone. Typically, it 1535 establishes a CNAME resource record from a subdomain into a CDN- 1536 managed domain. 1537 * The domain holder uses a CAA record [RFC8659] to restrict 1538 certificate issuance for the domain to specific CAs that comply 1539 with ACME and are known to implement [RFC8657]. 1540 * The domain holder uses the ACME-specific CAA mechanism [RFC8657] 1541 to restrict issuance to a specific account key which is controlled 1542 by it, and MUST require "dns-01" as the sole validation method. 1544 We note that the above solution may need to be tweaked depending on 1545 the exact capabilities and authorisation flows supported by the 1546 selected CA. In addition, this mitigation may be bypassed if a 1547 malicious or misconfigured CA does not comply with CAA restrictions. 1549 8. Acknowledgments 1551 We would like to thank the following people who contributed 1552 significantly to this document with their review comments and design 1553 proposals: Richard Barnes, Carsten Bormann, Roman Danyliw, Lars 1554 Eggert, Frédéric Fieau, Russ Housley, Ben Kaduk, Eric Kline, Sanjay 1555 Mishra, Francesca Palombini, Jon Peterson, Ryan Sleevi, Emile 1556 Stephan, Éric Vyncke. 1558 This work is partially supported by the European Commission under 1559 Horizon 2020 grant agreement no. 688421 Measurement and Architecture 1560 for a Middleboxed Internet (MAMI). This support does not imply 1561 endorsement. 1563 9. References 1565 9.1. Normative References 1567 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1568 Requirement Levels", BCP 14, RFC 2119, 1569 DOI 10.17487/RFC2119, March 1997, 1570 . 1572 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 1573 Request Syntax Specification Version 1.7", RFC 2986, 1574 DOI 10.17487/RFC2986, November 2000, 1575 . 1577 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1578 Housley, R., and W. Polk, "Internet X.509 Public Key 1579 Infrastructure Certificate and Certificate Revocation List 1580 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1581 . 1583 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1584 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1585 . 1587 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1588 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1589 May 2017, . 1591 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 1592 Kasten, "Automatic Certificate Management Environment 1593 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 1594 . 1596 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1597 Definition Language (CDDL): A Notational Convention to 1598 Express Concise Binary Object Representation (CBOR) and 1599 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1600 June 2019, . 1602 [RFC8739] Sheffer, Y., Lopez, D., Gonzalez de Dios, O., Pastor 1603 Perales, A., and T. Fossati, "Support for Short-Term, 1604 Automatically Renewed (STAR) Certificates in the Automated 1605 Certificate Management Environment (ACME)", RFC 8739, 1606 DOI 10.17487/RFC8739, March 2020, 1607 . 1609 9.2. Informative References 1611 [I-D.ietf-acme-authority-token-tnauthlist] 1612 Wendt, C., Hancock, D., Barnes, M., and J. Peterson, 1613 "TNAuthList profile of ACME Authority Token", Work in 1614 Progress, Internet-Draft, draft-ietf-acme-authority-token- 1615 tnauthlist-08, 27 March 2021, 1616 . 1619 [I-D.ietf-cdni-interfaces-https-delegation] 1620 Fieau, F., Stephan, E., and S. Mishra, "CDNI extensions 1621 for HTTPS delegation", Work in Progress, Internet-Draft, 1622 draft-ietf-cdni-interfaces-https-delegation-05, 12 March 1623 2021, . 1626 [I-D.ietf-stir-cert-delegation] 1627 Peterson, J., "STIR Certificate Delegation", Work in 1628 Progress, Internet-Draft, draft-ietf-stir-cert-delegation- 1629 04, 22 February 2021, . 1632 [I-D.ietf-tls-subcerts] 1633 Barnes, R., Iyengar, S., Sullivan, N., and E. Rescorla, 1634 "Delegated Credentials for TLS", Work in Progress, 1635 Internet-Draft, draft-ietf-tls-subcerts-10, 24 January 1636 2021, . 1639 [I-D.mglt-lurk-tls13] 1640 Migault, D., "LURK Extension version 1 for (D)TLS 1.3 1641 Authentication", Work in Progress, Internet-Draft, draft- 1642 mglt-lurk-tls13-04, 25 January 2021, 1643 . 1646 [json-schema-07] 1647 Wright, A., Andrews, H., and G. Luff, "JSON Schema 1648 Validation: A Vocabulary for Structural Validation of 1649 JSON", 2018, . 1652 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1653 Verification of Domain-Based Application Service Identity 1654 within Internet Public Key Infrastructure Using X.509 1655 (PKIX) Certificates in the Context of Transport Layer 1656 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 1657 2011, . 1659 [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, Ed., 1660 "Framework for Content Distribution Network 1661 Interconnection (CDNI)", RFC 7336, DOI 10.17487/RFC7336, 1662 August 2014, . 1664 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 1665 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 1666 . 1668 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 1669 Credentials: Certificates", RFC 8226, 1670 DOI 10.17487/RFC8226, February 2018, 1671 . 1673 [RFC8657] Landau, H., "Certification Authority Authorization (CAA) 1674 Record Extensions for Account URI and Automatic 1675 Certificate Management Environment (ACME) Method Binding", 1676 RFC 8657, DOI 10.17487/RFC8657, November 2019, 1677 . 1679 [RFC8659] Hallam-Baker, P., Stradling, R., and J. Hoffman-Andrews, 1680 "DNS Certification Authority Authorization (CAA) Resource 1681 Record", RFC 8659, DOI 10.17487/RFC8659, November 2019, 1682 . 1684 Appendix A. Document History 1686 [[Note to RFC Editor: please remove before publication.]] 1688 A.1. draft-ietf-acme-star-delegation-09 1690 * A few remaining comments by Ben Kaduk. 1692 A.2. draft-ietf-acme-star-delegation-08 1694 Extensive reviews by multiple IETF contributors and IESG members 1695 (many thanks to all involved, your names are in the Acknowledgments). 1696 Specifically: 1698 * More clarity in the Terminology, and correct distinction between 1699 CA and ACME server. 1700 * Explicit description of "delegations list", the object returned by 1701 the "delegations" URL. 1702 * The "delegation" is no longer part of the identifier, rather it is 1703 a property of the order. 1704 * Clarified the negotiation of unauthenticated GET for fetching 1705 certificates. This includes some normative changes. 1706 * Explicit description of the changes required on the CA: support 1707 for unauthenticated GET. 1708 * Some changes to IANA registrations and a change to the 1709 registration policy of a new registry. 1710 * More detail about security considerations related to pre- 1711 registration of the NDC as an ACME account on IdO. 1712 * Minor changes to the CSR Template schemas. 1713 * Many editorial changes. 1715 A.3. draft-ietf-acme-star-delegation-07 1717 * SecDir comments by Russ Housley. 1718 * In particular, reorganized some parts of the document to clarify 1719 handling of non-STAR certificates. 1720 * And changed the document's title accordingly. 1722 A.4. draft-ietf-acme-star-delegation-06 1724 * CDDL schema to address Roman's remaining comments. 1726 A.5. draft-ietf-acme-star-delegation-05 1728 * Detailed AD review by Roman Danyliw. 1729 * Some comments that were left unaddressed in Ryan Sleevi's review. 1730 * Numerous other edits for clarity and consistency. 1732 A.6. draft-ietf-acme-star-delegation-04 1734 * Delegation of non-STAR certificates. 1735 * More IANA clarity, specifically on certificate extensions. 1736 * Add delegation configuration object and extend account and order 1737 objects accordingly. 1738 * A lot more depth on Security Considerations. 1740 A.7. draft-ietf-acme-star-delegation-03 1742 * Consistency with the latest changes in the base ACME STAR 1743 document, e.g. star-delegation-enabled capability renamed and 1744 moved. 1745 * Proxy use cases (recursive delegation) and the definition of proxy 1746 behavior. 1747 * More detailed analysis of the CDNI and STIR use cases, including 1748 sequence diagrams. 1750 A.8. draft-ietf-acme-star-delegation-02 1752 * Security considerations: review by Ryan Sleevi. 1753 * CSR template simplified: instead of being a JSON Schema document 1754 itself, it is now a simple JSON document which validates to a JSON 1755 Schema. 1757 A.9. draft-ietf-acme-star-delegation-01 1759 * Refinement of the CDNI use case. 1760 * Addition of the CSR template (partial, more work required). 1761 * Further security considerations (work in progress). 1763 A.10. draft-ietf-acme-star-delegation-00 1765 * Republished as a working group draft. 1767 A.11. draft-sheffer-acme-star-delegation-01 1769 * Added security considerations about disallowing CDNs from issuing 1770 certificates for a delegated domain. 1772 A.12. draft-sheffer-acme-star-delegation-00 1774 * Initial version, some text extracted from draft-sheffer-acme-star- 1775 requests-02 1777 Appendix B. CSR Template: CDDL 1779 Following is the normative definition of the CSR template, using CDDL 1780 [RFC8610]. The CSR template MUST be a valid JSON document, compliant 1781 with the syntax defined here. 1783 There are additional constraints not expressed in CDDL that MUST be 1784 validated by the recipient, including: 1786 * The value of each "subjectAltName" entry is compatible with its 1787 type; 1789 * The parameters in each "keyTypes" entry form an acceptable 1790 combination. 1792 csr-template-schema = { 1793 keyTypes: [ + $keyType ] 1794 ? subject: non-empty 1795 extensions: extensions 1796 } 1798 non-empty = (M) .and ({ + any => any }) 1800 mandatory-wildcard = "**" 1801 optional-wildcard = "*" 1802 wildcard = mandatory-wildcard / optional-wildcard 1804 ; regtext matches all text strings but "*" and "**" 1805 regtext = text .regexp "([^\*].*)|([\*][^\*].*)|([\*][\*].+)" 1807 regtext-or-wildcard = regtext / wildcard 1809 distinguishedName = { 1810 ? country: regtext-or-wildcard 1811 ? stateOrProvince: regtext-or-wildcard 1812 ? locality: regtext-or-wildcard 1813 ? organization: regtext-or-wildcard 1814 ? organizationalUnit: regtext-or-wildcard 1815 ? emailAddress: regtext-or-wildcard 1816 ? commonName: regtext-or-wildcard 1817 } 1819 $keyType /= rsaKeyType 1820 $keyType /= ecdsaKeyType 1822 rsaKeyType = { 1823 PublicKeyType: "rsaEncryption" ; OID: 1.2.840.113549.1.1.1 1824 PublicKeyLength: rsaKeySize 1825 SignatureType: $rsaSignatureType 1826 } 1828 rsaKeySize = uint 1830 ; RSASSA-PKCS1-v1_5 with SHA-256 1831 $rsaSignatureType /= "sha256WithRSAEncryption" 1832 ; RSASSA-PCKS1-v1_5 with SHA-384 1833 $rsaSignatureType /= "sha384WithRSAEncryption" 1834 ; RSASSA-PCKS1-v1_5 with SHA-512 1835 $rsaSignatureType /= "sha512WithRSAEncryption" 1836 ; RSASSA-PSS with SHA-256, MGF-1 with SHA-256, and a 32 byte salt 1837 $rsaSignatureType /= "sha256WithRSAandMGF1" 1838 ; RSASSA-PSS with SHA-384, MGF-1 with SHA-384, and a 48 byte salt 1839 $rsaSignatureType /= "sha384WithRSAandMGF1" 1840 ; RSASSA-PSS with SHA-512, MGF-1 with SHA-512, and a 64 byte salt 1841 $rsaSignatureType /= "sha512WithRSAandMGF1" 1843 ecdsaKeyType = { 1844 PublicKeyType: "id-ecPublicKey" ; OID: 1.2.840.10045.2.1 1845 namedCurve: $ecdsaCurve 1846 SignatureType: $ecdsaSignatureType 1847 } 1849 $ecdsaCurve /= "secp256r1" ; OID: 1.2.840.10045.3.1.7 1850 $ecdsaCurve /= "secp384r1" ; OID: 1.3.132.0.34 1851 $ecdsaCurve /= "secp521r1" ; OID: 1.3.132.0.3 1853 $ecdsaSignatureType /= "ecdsa-with-SHA256" ; paired with secp256r1 1854 $ecdsaSignatureType /= "ecdsa-with-SHA384" ; paired with secp384r1 1855 $ecdsaSignatureType /= "ecdsa-with-SHA512" ; paired with secp521r1 1857 subjectaltname = { 1858 ? DNS: [ + regtext-or-wildcard ] 1859 ? Email: [ + regtext ] 1860 ? URI: [ + regtext ] 1861 * $$subjectaltname-extension 1862 } 1864 extensions = { 1865 ? keyUsage: [ + keyUsageType ] 1866 ? extendedKeyUsage: [ + extendedKeyUsageType ] 1867 subjectAltName: non-empty 1868 } 1870 keyUsageType /= "digitalSignature" 1871 keyUsageType /= "nonRepudiation" 1872 keyUsageType /= "keyEncipherment" 1873 keyUsageType /= "dataEncipherment" 1874 keyUsageType /= "keyAgreement" 1875 keyUsageType /= "keyCertSign" 1876 keyUsageType /= "cRLSign" 1877 keyUsageType /= "encipherOnly" 1878 keyUsageType /= "decipherOnly" 1880 extendedKeyUsageType /= "serverAuth" 1881 extendedKeyUsageType /= "clientAuth" 1882 extendedKeyUsageType /= "codeSigning" 1883 extendedKeyUsageType /= "emailProtection" 1884 extendedKeyUsageType /= "timeStamping" 1885 extendedKeyUsageType /= "OCSPSigning" 1886 extendedKeyUsageType /= oid 1888 oid = text .regexp "([0-2])((\.0)|(\.[1-9][0-9]*))*" 1890 Appendix C. CSR Template: JSON Schema 1892 This appendix includes an alternative, non-normative, JSON Schema 1893 definition of the CSR template. The syntax used is that of draft 7 1894 of JSON Schema, which is documented in [json-schema-07]. Note that 1895 later versions of this (now expired) draft describe later versions of 1896 the JSON Schema syntax. At the time of writing, a stable reference 1897 for this syntax is not yet available, and we have chosen to use the 1898 draft version which is currently best supported by tool 1899 implementations. 1901 The same considerations about additional constraints checking 1902 discussed in Appendix B apply here as well. 1904 { 1905 "title": "JSON Schema for the STAR Delegation CSR template", 1906 "$schema": "http://json-schema.org/draft-07/schema#", 1907 "$id": "http://ietf.org/acme/drafts/star-delegation/csr-template", 1908 "$defs": { 1909 "distinguished-name": { 1910 "$id": "#distinguished-name", 1911 "type": "object", 1912 "minProperties": 1, 1913 "properties": { 1914 "country": { 1915 "type": "string" 1916 }, 1917 "stateOrProvince": { 1918 "type": "string" 1919 }, 1920 "locality": { 1921 "type": "string" 1922 }, 1923 "organization": { 1924 "type": "string" 1925 }, 1926 "organizationalUnit": { 1927 "type": "string" 1928 }, 1929 "emailAddress": { 1930 "type": "string" 1931 }, 1932 "commonName": { 1933 "type": "string" 1934 } 1935 }, 1936 "additionalProperties": false 1937 }, 1938 "rsaKeyType": { 1939 "$id": "#rsaKeyType", 1940 "type": "object", 1941 "properties": { 1942 "PublicKeyType": { 1943 "type": "string", 1944 "const": "rsaEncryption" 1945 }, 1946 "PublicKeyLength": { 1947 "type": "integer" 1948 }, 1949 "SignatureType": { 1950 "type": "string", 1951 "enum": [ 1952 "sha256WithRSAEncryption", 1953 "sha384WithRSAEncryption", 1954 "sha512WithRSAEncryption", 1955 "sha256WithRSAandMGF1", 1956 "sha384WithRSAandMGF1", 1957 "sha512WithRSAandMGF1" 1958 ] 1959 } 1960 }, 1961 "required": [ 1962 "PublicKeyType", 1963 "PublicKeyLength", 1964 "SignatureType" 1965 ], 1966 "additionalProperties": false 1967 }, 1968 "ecdsaKeyType": { 1969 "$id": "#ecdsaKeyType", 1970 "type": "object", 1971 "properties": { 1972 "PublicKeyType": { 1973 "type": "string", 1974 "const": "id-ecPublicKey" 1975 }, 1976 "namedCurve": { 1977 "type": "string", 1978 "enum": [ 1979 "secp256r1", 1980 "secp384r1", 1981 "secp521r1" 1982 ] 1983 }, 1984 "SignatureType": { 1985 "type": "string", 1986 "enum": [ 1987 "ecdsa-with-SHA256", 1988 "ecdsa-with-SHA384", 1989 "ecdsa-with-SHA512" 1990 ] 1991 } 1992 }, 1993 "required": [ 1994 "PublicKeyType", 1995 "namedCurve", 1996 "SignatureType" 1997 ], 1998 "additionalProperties": false 1999 } 2000 }, 2001 "type": "object", 2002 "properties": { 2003 "keyTypes": { 2004 "type": "array", 2005 "minItems": 1, 2006 "items": { 2007 "anyOf": [ 2008 { 2009 "$ref": "#rsaKeyType" 2010 }, 2011 { 2012 "$ref": "#ecdsaKeyType" 2013 } 2014 ] 2015 } 2016 }, 2017 "subject": { 2018 "$ref": "#distinguished-name" 2019 }, 2020 "extensions": { 2021 "type": "object", 2022 "properties": { 2023 "keyUsage": { 2024 "type": "array", 2025 "minItems": 1, 2026 "items": { 2027 "type": "string", 2028 "enum": [ 2029 "digitalSignature", 2030 "nonRepudiation", 2031 "keyEncipherment", 2032 "dataEncipherment", 2033 "keyAgreement", 2034 "keyCertSign", 2035 "cRLSign", 2036 "encipherOnly", 2037 "decipherOnly" 2038 ] 2039 } 2040 }, 2041 "extendedKeyUsage": { 2042 "type": "array", 2043 "minItems": 1, 2044 "items": { 2045 "anyOf": [ 2046 { 2047 "type": "string", 2048 "enum": [ 2049 "serverAuth", 2050 "clientAuth", 2051 "codeSigning", 2052 "emailProtection", 2053 "timeStamping", 2054 "OCSPSigning" 2055 ] 2056 }, 2057 { 2058 "type": "string", 2059 "pattern": "^([0-2])((\\.0)|(\\.[1-9][0-9]*))*$", 2060 "description": "Used for OID values" 2061 } 2062 ] 2063 } 2064 }, 2065 "subjectAltName": { 2066 "type": "object", 2067 "minProperties": 1, 2068 "properties": { 2069 "DNS": { 2070 "type": "array", 2071 "minItems": 1, 2072 "items": { 2073 "anyOf": [ 2074 { 2075 "type": "string", 2076 "enum": [ 2077 "*", 2078 "**" 2079 ] 2080 }, 2081 { 2082 "type": "string", 2083 "format": "hostname" 2084 } 2085 ] 2086 } 2087 }, 2088 "Email": { 2089 "type": "array", 2090 "minItems": 1, 2091 "items": { 2092 "type": "string", 2093 "format": "email" 2094 } 2095 }, 2096 "URI": { 2097 "type": "array", 2098 "minItems": 1, 2099 "items": { 2100 "type": "string", 2101 "format": "uri" 2102 } 2103 } 2104 }, 2105 "additionalProperties": false 2106 } 2107 }, 2108 "required": [ 2109 "subjectAltName" 2110 ], 2111 "additionalProperties": false 2112 } 2113 }, 2114 "required": [ 2115 "extensions", 2116 "keyTypes" 2117 ], 2118 "additionalProperties": false 2119 } 2121 Authors' Addresses 2122 Yaron Sheffer 2123 Intuit 2125 Email: yaronf.ietf@gmail.com 2127 Diego López 2128 Telefonica I+D 2130 Email: diego.r.lopez@telefonica.com 2132 Antonio Agustín Pastor Perales 2133 Telefonica I+D 2135 Email: antonio.pastorperales@telefonica.com 2137 Thomas Fossati 2138 ARM 2140 Email: thomas.fossati@arm.com