idnits 2.17.1 draft-ietf-acme-star-delegation-08.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 (10 May 2021) is 1081 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 1486 == Missing Reference: '0-2' is mentioned on line 2061, but not defined == Missing Reference: '1-9' is mentioned on line 2061, but not defined == Missing Reference: '0-9' is mentioned on line 2061, but not defined ** Downref: Normative reference to an Informational RFC: RFC 2986 ** Obsolete normative reference: RFC 7807 (Obsoleted by RFC 9457) ** Downref: Normative reference to an Informational RFC: RFC 8793 == 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: 4 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: 11 November 2021 A. Pastor Perales 6 Telefonica I+D 7 T. Fossati 8 ARM 9 10 May 2021 11 An ACME Profile for Generating Delegated Certificates 12 draft-ietf-acme-star-delegation-08 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 11 November 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 . . . . . . . . . . . . . . . . . . 39 105 A.1. draft-ietf-acme-star-delegation-08 . . . . . . . . . . . 39 106 A.2. draft-ietf-acme-star-delegation-07 . . . . . . . . . . . 39 107 A.3. draft-ietf-acme-star-delegation-06 . . . . . . . . . . . 39 108 A.4. draft-ietf-acme-star-delegation-05 . . . . . . . . . . . 39 109 A.5. draft-ietf-acme-star-delegation-04 . . . . . . . . . . . 39 110 A.6. draft-ietf-acme-star-delegation-03 . . . . . . . . . . . 40 111 A.7. draft-ietf-acme-star-delegation-02 . . . . . . . . . . . 40 112 A.8. draft-ietf-acme-star-delegation-01 . . . . . . . . . . . 40 113 A.9. draft-ietf-acme-star-delegation-00 . . . . . . . . . . . 40 114 A.10. draft-sheffer-acme-star-delegation-01 . . . . . . . . . . 40 115 A.11. draft-sheffer-acme-star-delegation-00 . . . . . . . . . . 40 116 Appendix B. CSR Template: CDDL . . . . . . . . . . . . . . . . . 40 117 Appendix C. CSR Template: JSON Schema . . . . . . . . . . . . . 43 118 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 120 1. Introduction 122 This document is related to [RFC8739], in that some important use 123 cases require both documents to be implemented. To avoid 124 duplication, we give here a bare-bones description of the motivation 125 for this solution. For more details, please refer to the 126 introductory sections of [RFC8739]. 128 An Identifier Owner (IdO) has agreements in place with one or more 129 NDC (Name Delegation Consumer) to use and attest its identity. 131 In the primary use case the IdO is a content provider, and we 132 consider a Content Delivery Network (CDN) provider contracted to 133 serve the content over HTTPS. The CDN terminates the HTTPS 134 connection at one of its edge cache servers and needs to present its 135 clients (browsers, mobile apps, set-top-boxes) a certificate whose 136 name matches the domain name of the URL that is requested, i.e., that 137 of the IdO. Understandably, some IdOs may balk at sharing their 138 long-term private keys with another organization and, equally, 139 delegates would rather not have to handle other parties' long-term 140 secrets. Other relevant use cases are discussed in Section 5. 142 This document describes a profile of the ACME protocol [RFC8555] that 143 allows the NDC to request from the IdO, acting as a profiled ACME 144 server, a certificate for a delegated identity - i.e., one belonging 145 to the IdO. The IdO then uses the ACME protocol (with the extensions 146 described in [RFC8739]) to request issuance of a Short-Term, 147 Automatically Renewed (STAR) certificate for the same delegated 148 identity. The generated short-term certificate is automatically 149 renewed by the ACME Certification Authority (CA), periodically 150 fetched by the NDC and used to terminate HTTPS connections in lieu of 151 the IdO. The IdO can end the delegation at any time by simply 152 instructing the CA to stop the automatic renewal and letting the 153 certificate expire shortly thereafter. 155 While the primary use case we address is delegation of STAR 156 certificates, the mechanism proposed here accommodates also long- 157 lived certificates managed with the ACME protocol. The most 158 noticeable difference between long-lived and STAR certificates is the 159 way the termination of the delegation is managed. In the case of 160 long-lived certificates, the IdO uses the revokeCert URL exposed by 161 the CA and waits for the explicit revocation based on Certificate 162 Revocation List (CRL) and Online Certificate Status Protocol (OCSP) 163 to propagate to the relying parties. 165 In case the delegated identity is a domain name, this document also 166 provides a way for the NDC to inform the IdO about the CNAME mappings 167 that need to be installed in the IdO's DNS zone to enable the 168 aliasing of the delegated name, thus allowing the complete name 169 delegation workflow to be handled using a single interface. 171 We note that other standardization efforts address the problem of 172 certificate delegation for TLS connections, specifically 173 [I-D.ietf-tls-subcerts] and [I-D.mglt-lurk-tls13]. The former 174 extends the TLS certificate chain with a customer-owned signing 175 certificate; the latter separates the server's private key into a 176 dedicated, more secure component. Compared to these other 177 approaches, the current document does not require changes to the TLS 178 network stack of the client or the server, nor does it introduce 179 additional latency to the TLS connection. 181 1.1. Terminology 183 IdO Identifier Owner, the holder (current owner) of an identifier 184 (e.g., a domain name) that needs to be delegated. Depending on 185 the context, the term IdO may also be used to designate the 186 (profiled) ACME server deployed by the Identifier Owner or the 187 ACME client used by the Identifier Owner to interact with the CA. 189 NDC Name Delegation Consumer, the entity to which the domain name is 190 delegated for a limited time. This is a CDN in the primary use 191 case (in fact, readers may note the similarity of the two 192 acronyms). Depending on the context, the term NDC may also be 193 used to designate the (profiled) ACME client used by the Name 194 Delegation Consumer. 196 CDN Content Delivery Network, a widely distributed network that 197 serves the domain's web content to a wide audience at high 198 performance. 200 STAR Short-Term, Automatically Renewed X.509 certificates. 202 ACME Automated Certificate Management Environment, a certificate 203 management protocol [RFC8555]. 205 CA A Certification Authority that implements the ACME protocol. In 206 this document, the term is synonymous with "ACME server deployed 207 by the Certification Authority". 209 CSR A PKCS#10 [RFC2986] Certificate Signing Request, as supported by 210 ACME. 212 FQDN Fully Qualified Domain Name. 214 1.2. Conventions used in this document 216 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 217 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 218 "OPTIONAL" in this document are to be interpreted as described in 219 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 220 capitals, as shown here. 222 2. Protocol Flow 224 This section presents the protocol flow. For completeness, we 225 include the ACME profile proposed in this document as well as the 226 ACME STAR protocol described in [RFC8739]. 228 2.1. Preconditions 230 The protocol assumes the following preconditions are met: 232 * The IdO exposes an ACME server interface to the NDC(s) comprising 233 the account management interface; 234 * The NDC has registered an ACME account with the IdO; 235 * NDC and IdO have agreed on a "CSR template" to use, including at a 236 minimum: subject name (e.g., "abc.ido.example"), requested 237 algorithms and key length, key usage, extensions. The NDC will 238 use this template for every CSR created under the same delegation; 239 * IdO has registered an ACME account with the Certification 240 Authority (CA) 242 Note that even if the IdO implements the ACME server role, it is not 243 acting as a CA: in fact, from the point of view of the certificate 244 issuance process, the IdO only works as a "policing" forwarder of the 245 NDC's key-pair and is responsible for completing the identity 246 verification process towards the CA. 248 2.2. Overview 250 For clarity, the protocol overview presented here covers the main use 251 case of this protocol, namely delegation of STAR certificates. 252 Protocol behavior for non-STAR certificates is similar, and the 253 detailed differences are listed in the following sections. 255 The interaction between the NDC and the IdO is governed by the 256 profiled ACME workflow detailed in Section 2.3. The interaction 257 between the IdO and the CA is ruled by ACME [RFC8555], ACME STAR 258 [RFC8739] as well as any other ACME extension that applies (e.g., 259 [I-D.ietf-acme-authority-token-tnauthlist] for STIR). 261 The outline of the combined protocol for STAR certificates is as 262 follow (Figure 1): 264 * NDC sends an order Order1 for the delegated identifier to IdO; 265 * IdO creates an Order1 resource in state "ready" with a "finalize" 266 URL; 267 * NDC immediately sends a finalize request (which includes the CSR) 268 to the IdO; 269 * IdO verifies the CSR according to the agreed upon CSR template; 270 * If the CSR verification fails, Order1 is moved to an "invalid" 271 state and everything stops; 272 * If the CSR verification is successful, IdO moves Order1 to state 273 "processing", and sends a new Order2 (using its own account) for 274 the delegated identifier to the CA; 275 * If the ACME STAR protocol fails, Order2 moves to "invalid" and the 276 same state is reflected in Order1 (i.e., the NDC Order); 277 * If the ACME STAR run is successful (i.e., Order2 is "valid"), IdO 278 copies the "star-certificate" URL from Order2 to Order1 and 279 updates the Order1 state to "valid". 281 The NDC can now download, install and use the short-term certificate 282 bearing the name delegated by the IdO. This can continue until the 283 STAR certificate expires or the IdO decides to cancel the automatic 284 renewal process with the CA. 286 Note that the interactive identifier authorization phase described in 287 Section 7.5 of [RFC8555] is suppressed on the NDC-IdO side because 288 the delegated identity contained in the CSR presented to the IdO is 289 validated against the configured CSR template (Section 4.1). 290 Therefore, the NDC sends the finalize request, including the CSR, to 291 the IdO immediately after Order1 has been acknowledged. The IdO 292 SHALL buffer a (valid) CSR until the Validation phase completes 293 successfully. 295 Also note that the successful negotiation of the "unauthenticated 296 GET" (Section 3.4 of [RFC8793]) is required in order to allow the NDC 297 to access the "star-certificate" URL on the CA. 299 .------. .---------------. .------. 300 | NDC | | IdO | | ACME | 301 +--------+ +--------+--------+ +--------+ 302 | Client | | Server | Client | | Server | 303 '---+----' '----+---+---+----' '----+---' 304 | | | | 305 | Order1 | | | 306 | Signature | | | 307 o------------------->| | | 308 | | | | 309 | [ No identity ] | | | 310 | [ validation via ] | | | 311 | [ authorizations ] | | | 312 | | | | 313 | CSR | | | 314 | Signature | | | 315 o------------------->| | | 316 | Acknowledgement | | Order2 | 317 |<-------------------o | Signature | 318 | | o------------------->| 319 | | | Required | 320 | | | Authorizations | 321 | | |<-------------------o 322 | | | Responses | 323 | | | Signature | 324 | | o------------------->| 325 | | | | 326 | | |<~~~~Validation~~~~>| 327 | | | | 328 | | | CSR | 329 | | | Signature | 330 | | o------------------->| 331 | | | Acknowledgement | 332 | | |<-------------------o 333 | | | | 334 |<~~Await issuance~->| |<~~Await issuance~~>| 335 | | 336 | (unauthenticated) GET STAR certificate | 337 o------------------------------------------------>| 338 | Certificate #1 | 339 |<------------------------------------------------o 340 | (unauthenticated) GET STAR certificate | 341 o------------------------------------------------>| 342 | Certificate #2 | 343 |<------------------------------------------------o 344 | [...] | 345 | (unauthenticated) GET STAR certificate | 346 o------------------------------------------------>| 347 | Certificate #n | 348 |<------------------------------------------------o 350 Figure 1: End to end STAR delegation flow 352 2.3. Delegated Identity Profile 354 This section defines a profile of the ACME protocol, to be used 355 between the NDC and IdO. 357 2.3.1. Delegation Configuration 359 The IdO must be preconfigured to recognize one or more NDCs, and 360 present them with details about certificate delegations that apply to 361 each one. 363 2.3.1.1. Account Object Extensions 365 An NDC identifies itself to the IdO as an ACME account. The IdO can 366 delegate multiple names to a NDC, and these configurations are 367 described through "delegation" objects associated with the NDC's 368 Account object on the IdO. 370 As shown in Figure 2, the ACME account resource on the IdO is 371 extended with a new "delegations" attribute: 373 * delegations (required, string): A URL from which a list of 374 delegations configured for this account (Section 2.3.1.3) can be 375 fetched via a POST-as-GET request. 377 { 378 "status": "valid", 379 "contact": [ 380 "mailto:delegation-admin@ido.example" 381 ], 382 "termsOfServiceAgreed": true, 383 "orders": "https://example.com/acme/orders/saHpfB", 384 "delegations": "https://acme.ido.example/acme/delegations/adFqoz" 385 } 387 Figure 2: Example Account object with delegations 389 2.3.1.2. Delegation Lists 391 Each account object includes a "delegations" URL from which a list of 392 delegation configurations created by the IdO can be fetched via POST- 393 as-GET request. The result of the request MUST be a JSON object 394 whose "delegations" field is an array of URLs, each identifying a 395 delegation configuration made available to the NDC account 396 (Section 2.3.1.3). The server MAY return an incomplete list, along 397 with a Link header field with a "next" link relation indicating where 398 further entries can be acquired. 400 HTTP/1.1 200 OK 401 Content-Type: application/json 402 Link: ;rel="index" 403 Link: ;rel="next" 405 { 406 "delegations": [ 407 "https://acme.ido.example/acme/delegation/ogfr8EcolOT", 408 "https://acme.ido.example/acme/delegation/wSi5Lbb61E4", 409 /* more URLs not shown for example brevity */ 410 "https://acme.ido.example/acme/delegation/gm0wfLYHBen" 411 ] 412 } 414 2.3.1.3. Delegation Objects 416 This profile extends the ACME resource model with a new read-only 417 delegation object that represents a delegation configuration that 418 applies to a given NDC. 420 A delegation object contains the CSR template (see Section 4) that 421 applies to that delegation, and optionally any related CNAME mapping 422 for the delegated identifiers. Its structure is as follows: 424 * csr-template (required, object): CSR template as defined in 425 Section 4. 426 * cname-map (optional, object): a map of FQDN pairs. In each pair, 427 the name is the delegated identifier, the value is the 428 corresponding NDC name that is aliased in the IdO's zone file to 429 redirect the resolvers to the delegated entity. Both names and 430 values MUST be FQDNs with a terminating '.'. This field is only 431 meaningful for identifiers of type "dns". 433 An example delegation object in JSON format is shown in Figure 3. 435 { 436 "csr-template": { 437 "keyTypes": [ 438 { 439 "PublicKeyType": "id-ecPublicKey", 440 "namedCurve": "secp256r1", 441 "SignatureType": "ecdsa-with-SHA256" 442 } 443 ], 444 "subject": { 445 "country": "CA", 446 "stateOrProvince": "**", 447 "locality": "**" 448 }, 449 "extensions": { 450 "subjectAltName": { 451 "DNS": [ 452 "abc.ido.example" 453 ] 454 }, 455 "keyUsage": [ 456 "digitalSignature" 457 ], 458 "extendedKeyUsage": [ 459 "serverAuth" 460 ] 461 } 462 }, 463 "cname-map": { 464 "abc.ido.example.": "abc.ndc.example." 465 } 466 } 468 Figure 3: Example Delegation Configuration object 470 In order to indicate which specific delegation applies to the 471 requested certificate a new "delegation" attribute is added to the 472 Order object on the NDC-IdO side (see Figure 4). The value of this 473 attribute is the URL pointing to the delegation configuration object 474 that is to be used for this certificate request. If the "delegation" 475 attribute in the Order object contains a URL that does not correspond 476 to a configuration available to the requesting ACME account, the IdO 477 MUST return an error response with status code 403 (Forbidden), 478 providing a problem document [RFC7807] with type 479 "urn:ietf:params:acme:error:unknownDelegation". 481 2.3.2. Order Object Transmitted from NDC to IdO and to ACME Server 482 (STAR) 484 If the delegation is for a STAR certificate, the request object 485 created by the NDC: 487 * MUST have a "delegation" attribute indicating the preconfigured 488 delegation that applies to this Order; 489 * MUST have entries in the "identifiers" field for each delegated 490 name present in the configuration; 491 * MUST NOT contain the "notBefore" and "notAfter" fields; 492 * MUST contain an "auto-renewal" object and inside it, the fields 493 listed in Section 3.1.1 of [RFC8739]. In particular, the "allow- 494 certificate-get" attribute MUST be present and set to true. 496 POST /acme/new-order HTTP/1.1 497 Host: acme.ido.example 498 Content-Type: application/jose+json 500 { 501 "protected": base64url({ 502 "alg": "ES256", 503 "kid": "https://acme.ido.example/acme/acct/evOfKhNU60wg", 504 "nonce": "Alc00Ap6Rt7GMkEl3L1JX5", 505 "url": "https://acme.ido.example/acme/new-order" 506 }), 507 "payload": base64url({ 508 "identifiers": [ 509 { 510 "type": "dns", 511 "value": "abc.ido.example" 512 } 513 ], 514 "auto-renewal": { 515 "end-date": "2021-04-20T00:00:00Z", 516 "lifetime": 345600, // 4 days 517 "allow-certificate-get": true 518 }, 519 "delegation": 520 "https://acme.ido.example/acme/delegations/adFqoz/2" 521 }), 522 "signature": "g454e3hdBlkT4AEw...nKePnUyZTjGtXZ6H" 523 } 525 Figure 4: New STAR Order from NDC 527 The Order object that is created on the IdO: 529 * MUST start in the "ready" state; 530 * MUST contain an "authorizations" array with zero elements; 531 * MUST contain the indicated "delegation" configuration; 532 * MUST contain the indicated "auto-renewal" settings; 533 * MUST NOT contain the "notBefore" and "notAfter" fields. 535 { 536 "status": "ready", 537 "expires": "2021-05-01T00:00:00Z", 539 "identifiers": [ 540 { 541 "type": "dns", 542 "value": "abc.ido.example" 543 } 544 ], 546 "auto-renewal": { 547 "end-date": "2021-04-20T00:00:00Z", 548 "lifetime": 345600, 549 "allow-certificate-get": true 550 }, 552 "delegation": 553 "https://acme.ido.example/acme/delegations/adFqoz/2", 555 "authorizations": [], 557 "finalize": "https://acme.ido.example/acme/order/TO8rfgo/finalize" 558 } 560 Figure 5: STAR Order Resource Created on IdO 562 The Order is then finalized by the NDC supplying the CSR containing 563 the delegated identifiers. The IdO checks the provided CSR against 564 the template contained in the delegation object that applies to this 565 request, as described in Section 4.1. If the CSR fails validation 566 for any of the identifiers, the IdO MUST return an error response 567 with status code 403 (Forbidden) and an appropriate type, e.g., 568 "rejectedIdentifier" or "badCSR". The error response SHOULD contain 569 subproblems (Section 6.7.1 of [RFC8555]) for each failed identifier. 570 If the CSR is successfully validated, the Order object status moves 571 to "processing" and the twin ACME protocol instance is initiated on 572 the IdO-CA side. 574 The request object created by the IdO: 576 * MUST copy the identifiers sent by the NDC; 577 * MUST strip the "delegation" attribute; 578 * MUST carry a copy of the "auto-renewal" object sent by the NDC. 580 When the identifiers' authorization has been successfully completed 581 and the certificate has been issued by the CA, the IdO: 583 * MUST move its Order resource status to "valid"; 584 * MUST copy the "star-certificate" field from the STAR Order 585 returned by the CA into its Order resource. When dereferenced, 586 the "star-certificate" URL includes (via the Cert-Not-Before and 587 Cert-Not-After HTTP header fields) the renewal timers needed by 588 the NDC to inform its certificate reload logic. 590 { 591 "status": "valid", 592 "expires": "2021-05-01T00:00:00Z", 594 "identifiers": [ 595 { 596 "type": "dns", 597 "value": "abc.ido.example" 598 } 599 ], 601 "auto-renewal": { 602 "end-date": "2021-04-20T00:00:00Z", 603 "lifetime": 345600, 604 "allow-certificate-get": true 605 }, 607 "delegation": 608 "https://acme.ido.example/acme/delegations/adFqoz/2", 610 "authorizations": [], 612 "finalize": "https://acme.ido.example/acme/order/TO8rfgo/finalize", 614 "star-certificate": "https://acme.ca.example/acme/order/yTr23sSDg9" 615 } 617 Figure 6: STAR Order Resource Updated on IdO 619 This delegation protocol is predicated on the NDC being able to fetch 620 certificates periodically using an unauthenticated HTTP GET, since in 621 general the NDC does not possess an account on the CA and therefore 622 cannot issue the standard POST-as-GET ACME request. Therefore, 623 before forwarding the Order request to the CA, the IdO SHOULD ensure 624 that the selected CA supports "unauthenticated GET" by inspecting the 625 relevant settings in the CA's "directory" object, as per Section 3.4 626 of [RFC8739]. If the CA does not support "unauthenticated GET" of 627 STAR certificates, the IdO MUST NOT forward the Order request. 628 Instead, it MUST move the Order status to "invalid" and set the 629 "allow-certificate-get" in the "auto-renewal" object to "false". The 630 same occurs in case the Order request is forwarded and the CA does 631 not reflect the "allow-certificate-get" setting in its Order 632 resource. The combination of "invalid" status and denied "allow- 633 certificate-get" in the Order resource at the IdO provides an 634 unambiguous (asynchronous) signal to the NDC about the failure 635 reason. 637 2.3.2.1. CNAME Installation 639 If an identifier object of type "dns" was included, the IdO can add 640 the CNAME records specified in the delegation object to its zone, 641 e.g.: 643 abc.ido.example. CNAME abc.ndc.example. 645 2.3.3. Order Object Transmitted from NDC to IdO and to ACME Server 646 (non-STAR) 648 If the delegation is for a non-STAR certificate, the request object 649 created by the NDC: 651 * MUST have a "delegation" attribute indicating the preconfigured 652 delegation that applies to this Order; 653 * MUST have entries in the "identifiers" field for each delegated 654 name present in the configuration; 655 * MUST have the "allow-certificate-get" attribute set to true. 657 POST /acme/new-order HTTP/1.1 658 Host: acme.ido.example 659 Content-Type: application/jose+json 661 { 662 "protected": base64url({ 663 "alg": "ES256", 664 "kid": "https://acme.ido.example/acme/acct/evOfKhNU60wg", 665 "nonce": "IYBkoQfaCS80UcCn9qH8Gt", 666 "url": "https://acme.ido.example/acme/new-order" 667 }), 668 "payload": base64url({ 669 "identifiers": [ 670 { 671 "type": "dns", 672 "value": "abc.ido.example" 673 } 674 ], 675 "delegation": 676 "https://acme.ido.example/acme/delegations/adFqoz/2", 677 "allow-certificate-get": true 678 }), 679 "signature": "j9JBUvMigi4zodud...acYkEKaa8gqWyZ6H" 680 } 682 Figure 7: New Non-STAR Order from NDC 684 The Order object that is created on the IdO: 686 * MUST start in the "ready" state; 687 * MUST contain an "authorizations" array with zero elements; 688 * MUST contain the indicated "delegation" configuration; 689 * MUST contain the indicated "allow-certificate-get" setting. 691 { 692 "status": "ready", 693 "expires": "2021-05-01T00:00:00Z", 695 "identifiers": [ 696 { 697 "type": "dns", 698 "value": "abc.ido.example" 699 } 700 ], 702 "delegation": 703 "https://acme.ido.example/acme/delegations/adFqoz/2", 705 "allow-certificate-get": true, 707 "authorizations": [], 709 "finalize": "https://acme.ido.example/acme/order/3ZDlhYy/finalize" 710 } 712 Figure 8: Non-STAR Order Resource Created on IdO 714 The Order finalization by the NDC and the subsequent validation of 715 the CSR by the IdO proceed in the same way as for the STAR case. If 716 the CSR is successfully validated, the Order object status moves to 717 "processing" and the twin ACME protocol instance is initiated on the 718 IdO-CA side. 720 The request object created by the IdO: 722 * MUST copy the identifiers sent by the NDC; 723 * MUST strip the "delegation" attribute; 724 * MUST copy the "allow-certificate-get" attribute. 726 When the identifiers' authorization has been successfully completed 727 and the certificate has been issued by the CA, the IdO: 729 * MUST move its Order resource status to "valid"; 730 * MUST copy the "certificate" field from the Order returned by the 731 CA into its Order resource, as well as "notBefore" and "notAfter" 732 if these fields exist. 734 { 735 "status": "valid", 736 "expires": "2021-05-01T00:00:00Z", 738 "identifiers": [ 739 { 740 "type": "dns", 741 "value": "abc.ido.example" 742 } 743 ], 745 "delegation": 746 "https://acme.ido.example/acme/delegations/adFqoz/2", 748 "allow-certificate-get": true, 750 "authorizations": [], 752 "finalize": "https://acme.ido.example/acme/order/3ZDlhYy/finalize", 754 "certificate": "https://acme.ca.example/acme/order/YtR23SsdG9" 755 } 757 Figure 9: Non-STAR Order Resource Updated on IdO 759 At this point of the protocol flow, the same considerations as in 760 Section 2.3.2.1 apply. 762 Before forwarding the Order request to the CA, the IdO SHOULD ensure 763 that the selected CA supports "unauthenticated GET" by inspecting the 764 relevant settings in the CA's "directory" object, as per 765 Section 2.3.5. If the CA does not support "unauthenticated GET" of 766 certificate resources, the IdO MUST NOT forward the Order request. 767 Instead, it MUST move the Order status to "invalid" and set the 768 "allow-certificate-get" attribute to "false". The same occurs in 769 case the Order request is forwarded and the CA does not reflect the 770 "allow-certificate-get" setting in its Order resource. The 771 combination of "invalid" status and denied "allow-certificate-get" in 772 the Order resource at the IdO provides an unambiguous (asynchronous) 773 signal to the NDC about the failure reason. 775 2.3.4. Capability Discovery 777 In order to help a client to discover support for this profile, the 778 directory object of an ACME server (typically, one deployed by the 779 IdO) contains the following attribute in the "meta" field: 781 * delegation-enabled (optional, boolean): Boolean flag indicating 782 support for the profile specified in this memo. An ACME server 783 that supports this delegation profile MUST include this key, and 784 MUST set it to true. 786 The IdO MUST declare its support for delegation using "delegation- 787 enabled" regardless of whether it supports delegation of STAR 788 certificates, non-STAR certificates or both. 790 In order to help a client to discover support for certificate 791 fetching using unauthenticated HTTP GET, the directory object of an 792 ACME server (typically, one deployed by the CA) contains the 793 following attribute in the "meta" field: 795 * allow-certificate-get (optional, boolean): See Section 2.3.5. 797 2.3.5. Negotiating an Unauthenticated GET 799 In order to enable the name delegation of non-STAR certificates, this 800 document defines a mechanism that allows a server to advertise 801 support for accessing certificate resources via unauthenticated GET 802 (in addition to POST-as-GET), and a client to enable this service 803 with per-Order granularity. 805 It is worth pointing out that the protocol elements described in this 806 section have the same names and semantics as those introduced in 807 Section 3.4 of [RFC8739] for the STAR use case (except, of course, 808 they apply to the certificate resource rather than the star- 809 certificate resource). However, they differ in terms of their 810 position in the directory meta and order objects: rather than being 811 wrapped in an auto-renewal sub-object they are located at the top- 812 level. 814 A server states its availability to grant unauthenticated access to a 815 client's Order certificate by setting the "allow-certificate-get" 816 attribute to "true" in the "meta" field inside the directory object: 818 * allow-certificate-get (optional, boolean): If this field is 819 present and set to "true", the server allows GET (and HEAD) 820 requests to certificate URLs. 822 A client states its desire to access the issued certificate via 823 unauthenticated GET by adding an "allow-certificate-get" attribute to 824 the payload of its newOrder request and setting it to "true". 826 * allow-certificate-get (optional, boolean): If this field is 827 present and set to "true", the client requests the server to allow 828 unauthenticated GET (and HEAD) to the certificate associated with 829 this Order. 831 If the server accepts the request, it MUST reflect the attribute 832 setting in the resulting order object. 834 Note that even when the use of unauthenticated GET has been agreed 835 upon, the server MUST also allow POST-as-GET requests to the 836 certificate resource. 838 2.3.6. Terminating the Delegation 840 Identity delegation is terminated differently depending on whether 841 this is a STAR certificate or not. 843 2.3.6.1. By Cancellation (STAR) 845 The IdO can terminate the delegation of a STAR certificate by 846 requesting its cancellation (see Section 3.1.2 of [RFC8739]). 848 Cancellation of the ACME STAR certificate is a prerogative of the 849 IdO. The NDC does not own the relevant account key on the CA, 850 therefore it can't issue a cancellation request for the STAR 851 certificate. Potentially, since it holds the STAR certificate's 852 private key, it could request the revocation of a single STAR 853 certificate. However, STAR explicitly disables the revokeCert 854 interface. 856 Shortly after the automatic renewal process is stopped by the IdO, 857 the last issued STAR certificate expires and the delegation 858 terminates. 860 2.3.6.2. By Revocation (non-STAR) 862 The IdO can terminate the delegation of a non-STAR certificate by 863 requesting it to be revoked using the revokeCert URL exposed by the 864 CA. 866 According to Section 7.6 of [RFC8555], the revocation endpoint can be 867 used with either the account keypair, or the certificate keypair. In 868 other words, an NDC that learns the revokeCert URL of the CA (which 869 is publicly available via the CA's Directory object) would be able to 870 revoke the certificate using the associated private key. However, 871 given the trust relationship between NDC and IdO expected by the 872 delegation trust model (Section 7.1), as well as the lack of 873 incentives for the NDC to prematurely terminate the delegation, this 874 does not represent a significant security risk. 876 2.4. Proxy Behavior 878 There are cases where the ACME Delegation flow should be proxied, 879 such as the use case described in Section 5.1.2. This section 880 describes the behavior of such proxies. 882 An entity implementing the IdO server role - an "ACME Delegation 883 server" - can decide, on a per-identity case, whether to act as a 884 proxy into another ACME Delegation server, or to behave as an IdO and 885 obtain a certificate directly. The determining factor is whether it 886 can successfully be authorized by the next-hop ACME server for the 887 identity associated with the certificate request. 889 The identities supported by each server and the disposition for each 890 of them are preconfigured. 892 Following is the proxy's behavior for each of the messages exchanged 893 in the ACME Delegation process: 895 * New-order request: 896 - The complete "identifiers" object MUST be copied as-is. 897 - Similarly, the "auto-renewal" object MUST be copied as-is. 898 * New-order response: 899 - The "status", "expires", "authorizations", "identifiers" and 900 "auto-renewal" attributes/objects MUST be copied as-is. 901 - The "finalize" URL is rewritten, so that the "finalize" request 902 will be made to the proxy. 903 - Similarly, the "Location" header MUST be rewritten to point to 904 an Order object on the proxy. 905 - Any "Link" relations MUST be rewritten to point to the proxy. 906 * Get Order response: 907 - The "status", "expires", "authorizations", "identifiers" and 908 "auto-renewal" attributes/objects MUST be copied as-is. 909 - Similarly, the "star-certificate" URL (or the "certificate" URL 910 in case of non-STAR requests) MUST be copied as-is. 911 - The "finalize" URL is rewritten, so that the "finalize" request 912 will be made to the proxy. 914 - The "Location" header MUST be rewritten to point to an Order 915 object on the proxy. 916 - Any "Link" relations MUST be rewritten to point to the proxy. 917 * Finalize request: 918 - The CSR MUST be copied as-is. 919 * Finalize response: 920 - The "Location" header, "Link" relations and the "finalize" URLs 921 are rewritten as for Get Order. 923 We note that all the above messages are authenticated, and therefore 924 each proxy must be able to authenticate any subordinate server. 926 3. CA Behavior 928 Although most of this document, and in particular Section 2 is 929 focused on the protocol between the NDC and to IdO, the protocol does 930 affect the ACME server running in the CA. A CA that wishes to 931 support certificate delegation MUST also support unauthenticated 932 certificate fetching, which it declares using "allow-certificate-get" 933 (Section 2.3.5, Paragraph 3). 935 4. CSR Template 937 The CSR template is used to express and constrain the shape of the 938 CSR that the NDC uses to request the certificate. The CSR is used 939 for every certificate created under the same delegation. Its 940 validation by the IdO is a critical element in the security of the 941 whole delegation mechanism. 943 Instead of defining every possible CSR attribute, this document takes 944 a minimalist approach by declaring only the minimum attribute set and 945 deferring the registration of further, more specific, attributes to 946 future documents. 948 4.1. Template Syntax 950 The template is a JSON document. Each field (with the exception of 951 "keyTypes", see below) denotes one of: 953 * A mandatory field, where the template specifies the literal value 954 of that field. This is denoted by a literal string, such as 955 "abc.ido.example". 956 * A mandatory field, where the content of the field is defined by 957 the client. This is denoted by "**". 958 * An optional field, where the client decides whether the field is 959 included in the CSR and if so, what its value is. This is denoted 960 by "*". 962 The NDC MUST NOT include in the CSR any fields, including any 963 extensions, unless they are specified in the template. 965 The structure of the template object is defined by the CDDL [RFC8610] 966 document in Appendix B. An alternative, non-normative JSON Schema 967 syntax is given in Appendix C. While the CSR template must follow 968 the syntax defined here, neither the IdO nor the NDC are expected to 969 validate it at run-time. 971 The "subject" field and its subfields are mapped into the "subject" 972 field of the CSR, as per [RFC5280], Section 4.1.2.6. Other extension 973 fields of the CSR template are mapped into the CSR according to the 974 table in Section 6.5. 976 The "subjectAltName" field is currently defined for the following 977 identifiers: DNS names, email addresses, and URIs. New identifier 978 types may be added in the future by documents that extend this 979 specification. Each new identifier type SHALL have an associated 980 identifier validation challenge that the CA can use to obtain proof 981 of the requester's control over it. 983 The "keyTypes" property is not copied into the CSR. Instead, this 984 property constrains the "SubjectPublicKeyInfo" field of the CSR, 985 which MUST have the type/size defined by one of the array members of 986 the "keyTypes" property. 988 When the IdO receives the CSR, it MUST verify that the CSR is 989 consistent with the template contained in the "delegation" object 990 referenced in the Order. The IdO MAY enforce additional constraints, 991 e.g., by restricting field lengths. In this regard, note that a 992 "subjectAltName" of type "DNS" can be specified using the wildcard 993 notation, meaning that the NDC can be required ("**") or offered the 994 possibility ("*") to define the delegated domain name by itself. If 995 this is the case, the IdO MUST apply application-specific checks on 996 top of the control rules already provided by the CSR template to 997 ensure the requested domain name is legitimate according to its local 998 policy. 1000 4.2. Example 1002 The CSR template in Figure 10 represents one possible CSR template 1003 governing the delegation exchanges provided in the rest of this 1004 document. 1006 { 1007 "keyTypes": [ 1008 { 1009 "PublicKeyType": "rsaEncryption", 1010 "PublicKeyLength": 2048, 1011 "SignatureType": "sha256WithRSAEncryption" 1012 }, 1013 { 1014 "PublicKeyType": "id-ecPublicKey", 1015 "namedCurve": "secp256r1", 1016 "SignatureType": "ecdsa-with-SHA256" 1017 } 1018 ], 1019 "subject": { 1020 "country": "CA", 1021 "stateOrProvince": "**", 1022 "locality": "**" 1023 }, 1024 "extensions": { 1025 "subjectAltName": { 1026 "DNS": [ 1027 "abc.ido.example" 1028 ] 1029 }, 1030 "keyUsage": [ 1031 "digitalSignature" 1032 ], 1033 "extendedKeyUsage": [ 1034 "serverAuth", 1035 "clientAuth" 1036 ] 1037 } 1038 } 1040 Figure 10: Example CSR template 1042 5. Further Use Cases 1044 This non-normative section describes additional use cases that use 1045 STAR certificate delegation in non-trivial ways. 1047 5.1. CDN Interconnection (CDNI) 1049 [I-D.ietf-cdni-interfaces-https-delegation] discusses several 1050 solutions addressing different delegation requirements for the CDNI 1051 (CDN Interconnection) environment. This section discusses two of the 1052 stated requirements in the context of the STAR delegation workflow. 1054 This section uses specifically CDNI terminology, e.g., "uCDN" and 1055 "dCDN", as defined in [RFC7336]. 1057 5.1.1. Multiple Parallel Delegates 1059 In some cases the content owner (IdO) would like to delegate 1060 authority over a web site to multiple NDCs (CDNs). This could happen 1061 if the IdO has agreements in place with different regional CDNs for 1062 different geographical regions, or if a "backup" CDN is used to 1063 handle overflow traffic by temporarily altering some of the CNAME 1064 mappings in place. The STAR delegation flow enables this use case 1065 naturally, since each CDN can authenticate separately to the IdO (via 1066 its own separate account) specifying its CSR, and the IdO is free to 1067 allow or deny each certificate request according to its own policy. 1069 5.1.2. Chained Delegation 1071 In other cases, a content owner (IdO) delegates some domains to a 1072 large CDN (uCDN), which in turn delegates to a smaller regional CDN, 1073 dCDN. The IdO has a contractual relationship with uCDN, and uCDN has 1074 a similar relationship with dCDN. However IdO may not even know 1075 about dCDN. 1077 If needed, the STAR protocol can be chained to support this use case: 1078 uCDN could forward requests from dCDN to IdO, and forward responses 1079 back to dCDN. Whether such proxying is allowed is governed by policy 1080 and contracts between the parties. 1082 A mechanism is necessary at the interface between uCDN and dCDN by 1083 which the uCDN can advertise: 1085 * The names that the dCDN is allowed to use; 1086 * The policy for creating the key material (allowed algorithms, 1087 minimum key lengths, key usage, etc.) that the dCDN needs to 1088 satisfy. 1090 Note that such mechanism is provided by the CSR template. 1092 5.1.2.1. Two-Level Delegation in CDNI 1094 A User Agent (UA), browser or set-top-box, wants to fetch the video 1095 resource at the following URI: "https://video.cp.example/movie". 1096 Redirection between Content Provider (CP), upstream, and downstream 1097 CDNs is arranged as a CNAME-based aliasing chain as illustrated in 1098 Figure 11. 1100 .------------. 1101 video.cp.example ? | .-----. | 1102 .---------------------------------->| | | 1103 | (a) | | DNS | CP | 1104 | .-------------------------------+ | | 1105 | | CNAME video.ucdn.example | '-----' | 1106 | | '------------' 1107 | | 1108 | | 1109 .-----------|---v--. .------------. 1110 | .-----.-+-----. | video.ucdn.example ? | .-----. | 1111 | | | +----------------------------->| | | 1112 | UA | TLS | DNS | | (b) | | DNS | uCDN | 1113 | | | |<-----------------------------+ | | 1114 | '--+--'-----+-' | CNAME video.dcdn.example | '-----' | 1115 '------|----^---|--' '------------' 1116 | | | 1117 | | | 1118 | | | .------------. 1119 | | | video.dcdn.example ? | .-----. | 1120 | | '------------------------------>| | | 1121 | | (c) | | DNS | | 1122 | '-----------------------------------+ | | 1123 | A 192.0.2.1 | +-----+ dCDN | 1124 | | | | | 1125 '--------------------------------------->| TLS | | 1126 SNI: video.cp.example | | | | 1127 | '-----' | 1128 '------------' 1130 Figure 11: DNS Redirection 1132 Unlike HTTP-based redirection, where the original URL is supplanted 1133 by the one found in the Location header of the 302 response, DNS 1134 redirection is completely transparent to the User Agent. As a 1135 result, the TLS connection to the dCDN edge is done with a Server 1136 Name Indication (SNI) equal to the "host" in the original URI - in 1137 the example, "video.cp.example". So, in order to successfully 1138 complete the handshake, the landing dCDN node has to be configured 1139 with a certificate whose subjectAltName matches "video.cp.example", 1140 i.e., a Content Provider's name. 1142 Figure 12 illustrates the cascaded delegation flow that allows dCDN 1143 to obtain a STAR certificate that bears a name belonging to the 1144 Content Provider with a private key that is only known to the dCDN. 1146 .--------------------. 1147 | .------.------. | 1148 | | STAR | ACME |<-------------. 1149 | CP | dele | STAR | | | 1150 | | srv | cli +-----. | 1151 | '---+--'------' | | 6 1152 '---------|------^---' 5 | 1153 | | | .--|-------. 1154 | | | | .-+----. | 1155 7 | '---->| ACME | | 1156 | | | | STAR | C | 1157 | 4 | +------| A | 1158 | | | | HTTP | | 1159 | | | '----+-' | 1160 | .-' '--^--|----' 1161 .--------------v--|--. | | 1162 | .------.----+-. | | 10 1163 | | | STAR | | | | 1164 | uCDN | CDNI | dele | | | | 1165 | | | fwd | | | | 1166 | '----+-'-+----' | | | 1167 '-------^--|---|--^--' | | 1168 | | | | | | 1169 | 2 8 | | | 1170 1 | | 3 | | 1171 | | | | 9 | 1172 .-------|--v---v--|---------. | | 1173 | .-+----.----+-.------. | | | 1174 | | | STAR | +------------' | 1175 | dCDN | CDNI | dele | HTTP | | | 1176 | | | cli | |<--------------' 1177 | '------'------'------' | 1178 '---------------------------' 1180 Figure 12: Two levels delegation in CDNI 1182 uCDN is configured to delegate to dCDN, and CP is configured to 1183 delegate to uCDN, both as defined in Section 2.3.1. 1185 1. dCDN requests CDNI path metadata to uCDN; 1186 2. uCDN replies with, among other CDNI metadata, the STAR 1187 delegation configuration, which includes the delegated Content 1188 Provider's name; 1189 3. dCDN creates a key-pair and the CSR with the delegated name. It 1190 then places an order for the delegated name to uCDN; 1191 4. uCDN forwards the received order to the Content Provider (CP); 1192 5. CP creates an order for a STAR certificate and sends it to the 1193 CA. The order also requests unauthenticated access to the 1194 certificate resource; 1195 6. After all authorizations complete successfully, the STAR 1196 certificate is issued; 1197 7. CP notifies uCDN that the STAR certificate is available at the 1198 order's star-certificate URL; 1199 8. uCDN forwards the information to dCDN. At this point the ACME 1200 signalling is complete; 1201 9. dCDN requests the STAR certificate using unauthenticated GET 1202 from the CA; 1203 10. the CA returns the certificate. Now dCDN is fully configured to 1204 handle HTTPS traffic in-lieu of the Content Provider. 1206 Note that 9. and 10. repeat until the delegation expires or is 1207 terminated. 1209 5.2. Secure Telephone Identity Revisited (STIR) 1211 As a second use case, we consider the delegation of credentials in 1212 the STIR ecosystem [I-D.ietf-stir-cert-delegation]. 1214 This section uses STIR terminology. The term PASSPorT is defined in 1215 [RFC8225], and "TNAuthList" in [RFC8226]. 1217 In the STIR "delegated" mode, a service provider SP2 - the NDC - 1218 needs to sign PASSPorT's [RFC8225] for telephone numbers (e.g., 1219 TN=+123) belonging to another service provider, SP1 - the IdO. In 1220 order to do that, SP2 needs a STIR certificate, and private key, that 1221 includes TN=+123 in the TNAuthList [RFC8226] certificate extension. 1223 In details (Figure 13): 1225 1. SP1 and SP2 agree on the configuration of the delegation - in 1226 particular, the CSR template that applies; 1227 2. SP2 generates a private/public key-pair and sends a CSR to SP1 1228 requesting creation of a certificate with: SP1 name, SP2 public 1229 key, and a TNAuthList extension with the list of TNs that SP1 1230 delegates to SP2. (Note that the CSR sent by SP2 to SP1 needs to 1231 be validated against the CSR template agreed upon in step 1.); 1232 3. SP1 sends an order for the CSR to the CA. The order also 1233 requests unauthenticated access to the certificate resource; 1234 4. Subsequently, after the required TNAuthList authorizations are 1235 successfully completed, the CA moves the order to a "valid" 1236 state; at the same time the star-certificate endpoint is 1237 populated; 1238 5. The order contents are forwarded from SP1 to SP2 by means of the 1239 paired "delegation" order; 1241 6. SP2 dereferences the star-certificate URL in the order to fetch 1242 the rolling STAR certificate bearing the delegated identifiers; 1243 7. The STAR certificate is returned to SP2. 1245 .-------------------. 1246 | .------.------. | 1247 | | STAR | STAR |<--------------. 1248 .-->| SP1 | dele | dele | | | 1249 | | | srv | cli +-----. | 1250 | | '----+-'------' | | 4 1251 | '------^--|---------' 3 | 1252 | | | | .----|-----. 1253 | | 5 | | .---+--. | 1254 | | | '--->| ACME | | 1255 | | | | | STAR | C | 1256 1 | | | +------| A | 1257 | | | .--->| HTTP | | 1258 | 2 | | | '---+--' | 1259 | | | | '----|-----' 1260 | .------|--v---------. 6 | 1261 | | .-+----.------. | | 7 1262 | | | STAR | +-----' | 1263 '-->| SP2 | dele | HTTP | | | 1264 | | cli | |<--------------' 1265 | '----+-'-+----' | 1266 '-------------------' 1268 Figure 13: Delegation in STIR 1270 As shown, the STAR delegation profile described in this document 1271 applies straightforwardly, the only extra requirement being the 1272 ability to instruct the NDC about the allowed TNAuthList values. 1273 This can be achieved by a simple extension to the CSR template. 1275 6. IANA Considerations 1277 [[RFC Editor: please replace XXXX below by the RFC number.]] 1279 6.1. New Fields in the "meta" Object within a Directory Object 1281 This document adds the following entries to the ACME Directory 1282 Metadata Fields registry: 1284 +=======================+============+===========+ 1285 | Field Name | Field Type | Reference | 1286 +=======================+============+===========+ 1287 | delegation-enabled | boolean | RFC XXXX | 1288 +-----------------------+------------+-----------+ 1289 | allow-certificate-get | boolean | RFC XXXX | 1290 +-----------------------+------------+-----------+ 1292 Table 1 1294 6.2. New Fields in the Order Object 1296 This document adds the following entries to the ACME Order Object 1297 Fields registry: 1299 +=======================+============+==============+===========+ 1300 | Field Name | Field Type | Configurable | Reference | 1301 +=======================+============+==============+===========+ 1302 | allow-certificate-get | boolean | true | RFC XXXX | 1303 +-----------------------+------------+--------------+-----------+ 1304 | delegation | string | true | RFC XXXX | 1305 +-----------------------+------------+--------------+-----------+ 1307 Table 2 1309 6.3. New Fields in the Account Object 1311 This document adds the following entries to the ACME Account Object 1312 Fields registry: 1314 +=============+============+==========+===========+ 1315 | Field Name | Field Type | Requests | Reference | 1316 +=============+============+==========+===========+ 1317 | delegations | string | none | RFC XXXX | 1318 +-------------+------------+----------+-----------+ 1320 Table 3 1322 Note that the "delegations" field is only reported by ACME servers 1323 that have "delegation-enabled" set to true in their meta Object. 1325 6.4. New Error Types 1327 This document adds the following entries to the ACME Error Type 1328 registry: 1330 +===================+================================+===========+ 1331 | Type | Description | Reference | 1332 +===================+================================+===========+ 1333 | unknownDelegation | An unknown configuration is | RFC XXXX | 1334 | | listed in the "delegations" | | 1335 | | attribute of the request Order | | 1336 +-------------------+--------------------------------+-----------+ 1338 Table 4 1340 6.5. CSR Template Extensions 1342 IANA is requested to establish a registry "STAR Delegation CSR 1343 Template Extensions", with "Specification Required" as its 1344 registration procedure. 1346 Each extension registered must specify: 1348 * An extension name. 1349 * An extension syntax, as a reference to a CDDL document that 1350 defines this extension. 1351 * The extension's mapping into an X.509 certificate extension. 1353 The initial contents of this registry are the extensions defined by 1354 the CDDL in Appendix B. 1356 +==================+===========+===============================+ 1357 | Extension Name | Extension | Mapping to X.509 Certificate | 1358 | | Syntax | Extension | 1359 +==================+===========+===============================+ 1360 | keyUsage | See | [RFC5280], Section 4.2.1.3 | 1361 | | Appendix | | 1362 | | B | | 1363 +------------------+-----------+-------------------------------+ 1364 | extendedKeyUsage | See | [RFC5280], Section 4.2.1.12 | 1365 | | Appendix | | 1366 | | B | | 1367 +------------------+-----------+-------------------------------+ 1368 | subjectAltName | See | [RFC5280], Section 4.2.1.6 | 1369 | | Appendix | (note that only specific name | 1370 | | B | formats are allowed: URI, DNS | 1371 | | | name, email address) | 1372 +------------------+-----------+-------------------------------+ 1374 Table 5 1376 When evaluating a request for an assignment in this registry, the 1377 designated expert should follow this guidance: 1379 * The definition must include a full CDDL definition, which the 1380 expert will validate. 1381 * The definition must include both positive and negative test cases. 1382 * Additional requirements that are not captured by the CDDL 1383 definition are allowed but must be explicitly specified. 1385 7. Security Considerations 1387 7.1. Trust Model 1389 The ACME trust model needs to be extended to include the trust 1390 relationship between NDC and IdO. Note that once this trust link is 1391 established, it potentially becomes recursive. Therefore, there has 1392 to be a trust relationship between each of the nodes in the 1393 delegation chain; for example, in case of cascading CDNs this is 1394 contractually defined. Note that using standard [RFC6125] identity 1395 verification there are no mechanisms available to the IdO to restrict 1396 the use of the delegated name once the name has been handed over to 1397 the first NDC. It is therefore expected that contractual measures 1398 are in place to get some assurance that re-delegation is not being 1399 performed. 1401 7.2. Delegation Security Goal 1403 Delegation introduces a new security goal: only an NDC that has been 1404 authorised by the IdO, either directly or transitively, can obtain a 1405 certificate with an IdO identity. 1407 From a security point of view, the delegation process has five 1408 separate parts: 1410 1. Enabling a specific third party (the intended NDC) to submit 1411 requests for delegated certificates; 1412 2. Making sure that any request for a delegated certificate matches 1413 the intended "shape" in terms of delegated identities as well as 1414 any other certificate metadata, e.g., key length, x.509 1415 extensions, etc.; 1416 3. Serving the certificate back to the NDC; 1417 4. A process for handling revocation of the delegation; 1418 5. A process for handling revocation of the certificate itself. 1420 The first part is covered by the NDC's ACME account that is 1421 administered by the IdO, whose security relies on the correct 1422 handling of the associated key pair. When a compromise of the 1423 private key is detected, the delegate MUST use the account 1424 deactivation procedures defined in Section 7.3.6 of [RFC8555]. 1426 The second part is covered by the act of checking an NDC's 1427 certificate request against the intended CSR template. The steps of 1428 shaping the CSR template correctly, selecting the right CSR template 1429 to check against the presented CSR, and making sure that the 1430 presented CSR matches the selected CSR template are all security 1431 relevant. 1433 The third part builds on the trust relationship between NDC and IdO 1434 that is responsible for correctly forwarding the certificate URL from 1435 the Order returned by the CA. 1437 The fourth part is associated with the ability of the IdO to 1438 unilaterally remove the delegation object associated with the revoked 1439 identity, therefore disabling any further NDC requests for such 1440 identity. Note that, in more extreme circumstances, the IdO might 1441 decide to disable the NDC account thus entirely blocking any further 1442 interaction. 1444 The fifth is covered by two different mechanisms, depending on the 1445 nature of the certificate. For STAR, the IdO shall use the 1446 cancellation interface defined in Section 2.3 of [RFC8739]. For non- 1447 STAR, the certificate revocation interface defined in Section 7.6 of 1448 [RFC8555]) is used. 1450 The ACME account associated with the delegation plays a crucial role 1451 in the overall security of the presented protocol. This, in turn, 1452 means that in delegation scenarios the security requirements and 1453 verification associated with an ACME account may be more stringent 1454 than in traditional ACME, since the out-of-band configuration of 1455 delegations that an account is authorized to use, combined with 1456 account authentication, takes the place of the normal ACME 1457 authorization challenge procedures. Therefore, the IdO MUST ensure 1458 that each account is associated with the exact policy (via a 1459 "delegation" object) that defines which domain names can be delegated 1460 to the account and how. The IdO is expected to use out of band means 1461 to pre-register each NDC to the corresponding account. 1463 7.3. New ACME Channels 1465 Using the model established in Section 10.1 of [RFC8555], we can 1466 decompose the interactions of the basic delegation workflow as shown 1467 in Figure 14. 1469 .-----. ACME Channel .--------. 1470 | NDC +------------->| IdO | 1471 '--+--' | server | 1472 | '--o-----' 1473 | | 1474 | | ACME Channel 1475 | | .------------>-------------. 1476 | | | | 1477 | .--o--+--. .--+---. 1478 | | IdO | | CA | 1479 | | client | '--+-+-' 1480 | '-----+--' | | 1481 | '-----------<--------------' | 1482 | Validation Channel | 1483 '-------------------->-------------------------------' 1484 (subset of) ACME Channel [1] 1486 [1] Unauthenticated certificate fetch and non-STAR certificate 1487 revocation. 1489 Figure 14: Delegation Channels Topology 1491 The considerations regarding the security of the ACME Channel and 1492 Validation Channel discussed in [RFC8555] apply verbatim to the IdO- 1493 CA leg. The same can be said for the ACME channel on the NDC-IdO 1494 leg. A slightly different set of considerations apply to the ACME 1495 Channel between NDC and CA, which consists of a subset of the ACME 1496 interface comprising two API endpoints: the unauthenticated 1497 certificate retrieval and, potentially, non-STAR revocation via 1498 certificate private key. No specific security considerations apply 1499 to the former, but the privacy considerations in Section 6.3 of 1500 [RFC8739] do. With regards to the latter, it should be noted that 1501 there is currently no means for an IdO to disable authorising 1502 revocation based on certificate private keys. So, in theory, an NDC 1503 could use the revocation API directly with the CA, therefore 1504 bypassing the IdO. The NDC SHOULD NOT directly use the revocation 1505 interface exposed by the CA unless failing to do so would compromise 1506 the overall security, for example if the certificate private key is 1507 compromised and the IdO is not currently reachable. 1509 All other security considerations from [RFC8555] and [RFC8739] apply 1510 as-is to the delegation topology. 1512 7.4. Restricting CDNs to the Delegation Mechanism 1514 When a web site is delegated to a CDN, the CDN can in principle 1515 modify the web site at will, create and remove pages. This means 1516 that a malicious or breached CDN can pass the ACME (as well as common 1517 non-ACME) HTTPS-based validation challenges and generate a 1518 certificate for the site. This is true regardless of whether the 1519 CNAME mechanisms defined in the current document is used or not. 1521 In some cases, this is the desired behavior: the domain holder trusts 1522 the CDN to have full control of the cryptographic credentials for the 1523 site. The current document however assumes a scenario where the 1524 domain holder only wants to delegate restricted control, and wishes 1525 to retain the capability to cancel the CDN's credentials at a short 1526 notice. 1528 The following is a possible mitigation when the IdO wishes to ensure 1529 that a rogue CDN cannot issue unauthorized certificates: 1531 * The domain holder makes sure that the CDN cannot modify the DNS 1532 records for the domain. The domain holder should ensure it is the 1533 only entity authorized to modify the DNS zone. Typically, it 1534 establishes a CNAME resource record from a subdomain into a CDN- 1535 managed domain. 1536 * The domain holder uses a CAA record [RFC8659] to restrict 1537 certificate issuance for the domain to specific CAs that comply 1538 with ACME and are known to implement [RFC8657]. 1539 * The domain holder uses the ACME-specific CAA mechanism [RFC8657] 1540 to restrict issuance to a specific account key which is controlled 1541 by it, and MUST require "dns-01" as the sole validation method. 1543 We note that the above solution may need to be tweaked depending on 1544 the exact capabilities and authorisation flows supported by the 1545 selected CA. In addition, this mitigation may be bypassed if a 1546 malicious or misconfigured CA does not comply with CAA restrictions. 1548 8. Acknowledgments 1550 We would like to thank the following people who contributed 1551 significantly to this document with their review comments and design 1552 proposals: Richard Barnes, Carsten Bormann, Roman Danyliw, Lars 1553 Eggert, Frédéric Fieau, Russ Housley, Ben Kaduk, Eric Kline, Sanjay 1554 Mishra, Francesca Palombini, Jon Peterson, Ryan Sleevi, Emile 1555 Stephan, Éric Vyncke. 1557 This work is partially supported by the European Commission under 1558 Horizon 2020 grant agreement no. 688421 Measurement and Architecture 1559 for a Middleboxed Internet (MAMI). This support does not imply 1560 endorsement. 1562 9. References 1564 9.1. Normative References 1566 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1567 Requirement Levels", BCP 14, RFC 2119, 1568 DOI 10.17487/RFC2119, March 1997, 1569 . 1571 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 1572 Request Syntax Specification Version 1.7", RFC 2986, 1573 DOI 10.17487/RFC2986, November 2000, 1574 . 1576 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1577 Housley, R., and W. Polk, "Internet X.509 Public Key 1578 Infrastructure Certificate and Certificate Revocation List 1579 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1580 . 1582 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1583 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1584 . 1586 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1587 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1588 May 2017, . 1590 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 1591 Kasten, "Automatic Certificate Management Environment 1592 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 1593 . 1595 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1596 Definition Language (CDDL): A Notational Convention to 1597 Express Concise Binary Object Representation (CBOR) and 1598 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1599 June 2019, . 1601 [RFC8739] Sheffer, Y., Lopez, D., Gonzalez de Dios, O., Pastor 1602 Perales, A., and T. Fossati, "Support for Short-Term, 1603 Automatically Renewed (STAR) Certificates in the Automated 1604 Certificate Management Environment (ACME)", RFC 8739, 1605 DOI 10.17487/RFC8739, March 2020, 1606 . 1608 [RFC8793] Wissingh, B., Wood, C., Afanasyev, A., Zhang, L., Oran, 1609 D., and C. Tschudin, "Information-Centric Networking 1610 (ICN): Content-Centric Networking (CCNx) and Named Data 1611 Networking (NDN) Terminology", RFC 8793, 1612 DOI 10.17487/RFC8793, June 2020, 1613 . 1615 9.2. Informative References 1617 [I-D.ietf-acme-authority-token-tnauthlist] 1618 Wendt, C., Hancock, D., Barnes, M., and J. Peterson, 1619 "TNAuthList profile of ACME Authority Token", Work in 1620 Progress, Internet-Draft, draft-ietf-acme-authority-token- 1621 tnauthlist-08, 27 March 2021, 1622 . 1625 [I-D.ietf-cdni-interfaces-https-delegation] 1626 Fieau, F., Stephan, E., and S. Mishra, "CDNI extensions 1627 for HTTPS delegation", Work in Progress, Internet-Draft, 1628 draft-ietf-cdni-interfaces-https-delegation-05, 12 March 1629 2021, . 1632 [I-D.ietf-stir-cert-delegation] 1633 Peterson, J., "STIR Certificate Delegation", Work in 1634 Progress, Internet-Draft, draft-ietf-stir-cert-delegation- 1635 04, 22 February 2021, . 1638 [I-D.ietf-tls-subcerts] 1639 Barnes, R., Iyengar, S., Sullivan, N., and E. Rescorla, 1640 "Delegated Credentials for TLS", Work in Progress, 1641 Internet-Draft, draft-ietf-tls-subcerts-10, 24 January 1642 2021, . 1645 [I-D.mglt-lurk-tls13] 1646 Migault, D., "LURK Extension version 1 for (D)TLS 1.3 1647 Authentication", Work in Progress, Internet-Draft, draft- 1648 mglt-lurk-tls13-04, 25 January 2021, 1649 . 1652 [json-schema-07] 1653 Wright, A., Andrews, H., and G. Luff, "JSON Schema 1654 Validation: A Vocabulary for Structural Validation of 1655 JSON", 2018, . 1658 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1659 Verification of Domain-Based Application Service Identity 1660 within Internet Public Key Infrastructure Using X.509 1661 (PKIX) Certificates in the Context of Transport Layer 1662 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 1663 2011, . 1665 [RFC7336] Peterson, L., Davie, B., and R. van Brandenburg, Ed., 1666 "Framework for Content Distribution Network 1667 Interconnection (CDNI)", RFC 7336, DOI 10.17487/RFC7336, 1668 August 2014, . 1670 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 1671 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 1672 . 1674 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 1675 Credentials: Certificates", RFC 8226, 1676 DOI 10.17487/RFC8226, February 2018, 1677 . 1679 [RFC8657] Landau, H., "Certification Authority Authorization (CAA) 1680 Record Extensions for Account URI and Automatic 1681 Certificate Management Environment (ACME) Method Binding", 1682 RFC 8657, DOI 10.17487/RFC8657, November 2019, 1683 . 1685 [RFC8659] Hallam-Baker, P., Stradling, R., and J. Hoffman-Andrews, 1686 "DNS Certification Authority Authorization (CAA) Resource 1687 Record", RFC 8659, DOI 10.17487/RFC8659, November 2019, 1688 . 1690 Appendix A. Document History 1692 [[Note to RFC Editor: please remove before publication.]] 1694 A.1. draft-ietf-acme-star-delegation-08 1696 Extensive reviews by multiple IETF contributors and IESG members 1697 (many thanks to all involved, your names are in the Acknowledgments). 1698 Specifically: 1700 * More clarity in the Terminology, and correct distinction between 1701 CA and ACME server. 1702 * Explicit description of "delegations list", the object returned by 1703 the "delegations" URL. 1704 * The "delegation" is no longer part of the identifier, rather it is 1705 a property of the order. 1706 * Clarified the negotiation of unauthenticated GET for fetching 1707 certificates. This includes some normative changes. 1708 * Explicit description of the changes required on the CA: support 1709 for unauthenticated GET. 1710 * Some changes to IANA registrations and a change to the 1711 registration policy of a new registry. 1712 * More detail about security considerations related to pre- 1713 registration of the NDC as an ACME account on IdO. 1714 * Minor changes to the CSR Template schemas. 1715 * Many editorial changes. 1717 A.2. draft-ietf-acme-star-delegation-07 1719 * SecDir comments by Russ Housley. 1720 * In particular, reorganized some parts of the document to clarify 1721 handling of non-STAR certificates. 1722 * And changed the document's title accordingly. 1724 A.3. draft-ietf-acme-star-delegation-06 1726 * CDDL schema to address Roman's remaining comments. 1728 A.4. draft-ietf-acme-star-delegation-05 1730 * Detailed AD review by Roman Danyliw. 1731 * Some comments that were left unaddressed in Ryan Sleevi's review. 1732 * Numerous other edits for clarity and consistency. 1734 A.5. draft-ietf-acme-star-delegation-04 1736 * Delegation of non-STAR certificates. 1737 * More IANA clarity, specifically on certificate extensions. 1739 * Add delegation configuration object and extend account and order 1740 objects accordingly. 1741 * A lot more depth on Security Considerations. 1743 A.6. draft-ietf-acme-star-delegation-03 1745 * Consistency with the latest changes in the base ACME STAR 1746 document, e.g. star-delegation-enabled capability renamed and 1747 moved. 1748 * Proxy use cases (recursive delegation) and the definition of proxy 1749 behavior. 1750 * More detailed analysis of the CDNI and STIR use cases, including 1751 sequence diagrams. 1753 A.7. draft-ietf-acme-star-delegation-02 1755 * Security considerations: review by Ryan Sleevi. 1756 * CSR template simplified: instead of being a JSON Schema document 1757 itself, it is now a simple JSON document which validates to a JSON 1758 Schema. 1760 A.8. draft-ietf-acme-star-delegation-01 1762 * Refinement of the CDNI use case. 1763 * Addition of the CSR template (partial, more work required). 1764 * Further security considerations (work in progress). 1766 A.9. draft-ietf-acme-star-delegation-00 1768 * Republished as a working group draft. 1770 A.10. draft-sheffer-acme-star-delegation-01 1772 * Added security considerations about disallowing CDNs from issuing 1773 certificates for a delegated domain. 1775 A.11. draft-sheffer-acme-star-delegation-00 1777 * Initial version, some text extracted from draft-sheffer-acme-star- 1778 requests-02 1780 Appendix B. CSR Template: CDDL 1782 Following is the normative definition of the CSR template, using CDDL 1783 [RFC8610]. The CSR template MUST be a valid JSON document, compliant 1784 with the syntax defined here. 1786 There are additional constraints not expressed in CDDL that MUST be 1787 validated by the recipient, including: 1789 * The value of each "subjectAltName" entry is compatible with its 1790 type; 1791 * The parameters in each "keyTypes" entry form an acceptable 1792 combination. 1794 csr-template-schema = { 1795 keyTypes: [ + $keyType ] 1796 ? subject: non-empty 1797 extensions: extensions 1798 } 1800 non-empty = (M) .and ({ + any => any }) 1802 mandatory-wildcard = "**" 1803 optional-wildcard = "*" 1804 wildcard = mandatory-wildcard / optional-wildcard 1806 ; regtext matches all text strings but "*" and "**" 1807 regtext = text .regexp "([^\*].*)|([\*][^\*].*)|([\*][\*].+)" 1809 regtext-or-wildcard = regtext / wildcard 1811 distinguishedName = { 1812 ? country: regtext-or-wildcard 1813 ? stateOrProvince: regtext-or-wildcard 1814 ? locality: regtext-or-wildcard 1815 ? organization: regtext-or-wildcard 1816 ? organizationalUnit: regtext-or-wildcard 1817 ? emailAddress: regtext-or-wildcard 1818 ? commonName: regtext-or-wildcard 1819 } 1821 $keyType /= rsaKeyType 1822 $keyType /= ecdsaKeyType 1824 rsaKeyType = { 1825 PublicKeyType: "rsaEncryption" ; OID: 1.2.840.113549.1.1.1 1826 PublicKeyLength: rsaKeySize 1827 SignatureType: $rsaSignatureType 1828 } 1830 rsaKeySize = uint 1832 ; RSASSA-PKCS1-v1_5 with SHA-256 1833 $rsaSignatureType /= "sha256WithRSAEncryption" 1834 ; RSASSA-PCKS1-v1_5 with SHA-384 1835 $rsaSignatureType /= "sha384WithRSAEncryption" 1836 ; RSASSA-PCKS1-v1_5 with SHA-512 1837 $rsaSignatureType /= "sha512WithRSAEncryption" 1838 ; RSASSA-PSS with SHA-256, MGF-1 with SHA-256, and a 32 byte salt 1839 $rsaSignatureType /= "sha256WithRSAandMGF1" 1840 ; RSASSA-PSS with SHA-384, MGF-1 with SHA-384, and a 48 byte salt 1841 $rsaSignatureType /= "sha384WithRSAandMGF1" 1842 ; RSASSA-PSS with SHA-512, MGF-1 with SHA-512, and a 64 byte salt 1843 $rsaSignatureType /= "sha512WithRSAandMGF1" 1845 ecdsaKeyType = { 1846 PublicKeyType: "id-ecPublicKey" ; OID: 1.2.840.10045.2.1 1847 namedCurve: $ecdsaCurve 1848 SignatureType: $ecdsaSignatureType 1849 } 1851 $ecdsaCurve /= "secp256r1" ; OID: 1.2.840.10045.3.1.7 1852 $ecdsaCurve /= "secp384r1" ; OID: 1.3.132.0.34 1853 $ecdsaCurve /= "secp521r1" ; OID: 1.3.132.0.3 1855 $ecdsaSignatureType /= "ecdsa-with-SHA256" ; paired with secp256r1 1856 $ecdsaSignatureType /= "ecdsa-with-SHA384" ; paired with secp384r1 1857 $ecdsaSignatureType /= "ecdsa-with-SHA512" ; paired with secp521r1 1859 subjectaltname = { 1860 ? DNS: [ + regtext-or-wildcard ] 1861 ? Email: [ + regtext ] 1862 ? URI: [ + regtext ] 1863 * $$subjectaltname-extension 1864 } 1866 extensions = { 1867 ? keyUsage: [ + keyUsageType ] 1868 ? extendedKeyUsage: [ + extendedKeyUsageType ] 1869 subjectAltName: non-empty 1870 } 1872 keyUsageType /= "digitalSignature" 1873 keyUsageType /= "nonRepudiation" 1874 keyUsageType /= "keyEncipherment" 1875 keyUsageType /= "dataEncipherment" 1876 keyUsageType /= "keyAgreement" 1877 keyUsageType /= "keyCertSign" 1878 keyUsageType /= "cRLSign" 1879 keyUsageType /= "encipherOnly" 1880 keyUsageType /= "decipherOnly" 1881 extendedKeyUsageType /= "serverAuth" 1882 extendedKeyUsageType /= "clientAuth" 1883 extendedKeyUsageType /= "codeSigning" 1884 extendedKeyUsageType /= "emailProtection" 1885 extendedKeyUsageType /= "timeStamping" 1886 extendedKeyUsageType /= "OCSPSigning" 1887 extendedKeyUsageType /= oid 1889 oid = text .regexp "([0-2])((\.0)|(\.[1-9][0-9]*))*" 1891 Appendix C. CSR Template: JSON Schema 1893 This appendix includes an alternative, non-normative, JSON Schema 1894 definition of the CSR template. The syntax used is that of draft 7 1895 of JSON Schema, which is documented in [json-schema-07]. Note that 1896 later versions of this (now expired) draft describe later versions of 1897 the JSON Schema syntax. At the time of writing, a stable reference 1898 for this syntax is not yet available, and we have chosen to use the 1899 draft version which is currently best supported by tool 1900 implementations. 1902 The same considerations about additional constraints checking 1903 discussed in Appendix B apply here as well. 1905 { 1906 "title": "JSON Schema for the STAR Delegation CSR template", 1907 "$schema": "http://json-schema.org/draft-07/schema#", 1908 "$id": "http://ietf.org/acme/drafts/star-delegation/csr-template", 1909 "$defs": { 1910 "distinguished-name": { 1911 "$id": "#distinguished-name", 1912 "type": "object", 1913 "minProperties": 1, 1914 "properties": { 1915 "country": { 1916 "type": "string" 1917 }, 1918 "stateOrProvince": { 1919 "type": "string" 1920 }, 1921 "locality": { 1922 "type": "string" 1923 }, 1924 "organization": { 1925 "type": "string" 1926 }, 1927 "organizationalUnit": { 1928 "type": "string" 1930 }, 1931 "emailAddress": { 1932 "type": "string" 1933 }, 1934 "commonName": { 1935 "type": "string" 1936 } 1937 }, 1938 "additionalProperties": false 1939 }, 1940 "rsaKeyType": { 1941 "$id": "#rsaKeyType", 1942 "type": "object", 1943 "properties": { 1944 "PublicKeyType": { 1945 "type": "string", 1946 "const": "rsaEncryption" 1947 }, 1948 "PublicKeyLength": { 1949 "type": "integer" 1950 }, 1951 "SignatureType": { 1952 "type": "string", 1953 "enum": [ 1954 "sha256WithRSAEncryption", 1955 "sha384WithRSAEncryption", 1956 "sha512WithRSAEncryption", 1957 "sha256WithRSAandMGF1", 1958 "sha384WithRSAandMGF1", 1959 "sha512WithRSAandMGF1" 1960 ] 1961 } 1962 }, 1963 "required": [ 1964 "PublicKeyType", 1965 "PublicKeyLength", 1966 "SignatureType" 1967 ], 1968 "additionalProperties": false 1969 }, 1970 "ecdsaKeyType": { 1971 "$id": "#ecdsaKeyType", 1972 "type": "object", 1973 "properties": { 1974 "PublicKeyType": { 1975 "type": "string", 1976 "const": "id-ecPublicKey" 1977 }, 1978 "namedCurve": { 1979 "type": "string", 1980 "enum": [ 1981 "secp256r1", 1982 "secp384r1", 1983 "secp521r1" 1984 ] 1985 }, 1986 "SignatureType": { 1987 "type": "string", 1988 "enum": [ 1989 "ecdsa-with-SHA256", 1990 "ecdsa-with-SHA384", 1991 "ecdsa-with-SHA512" 1992 ] 1993 } 1994 }, 1995 "required": [ 1996 "PublicKeyType", 1997 "namedCurve", 1998 "SignatureType" 1999 ], 2000 "additionalProperties": false 2001 } 2002 }, 2003 "type": "object", 2004 "properties": { 2005 "keyTypes": { 2006 "type": "array", 2007 "minItems": 1, 2008 "items": { 2009 "anyOf": [ 2010 { 2011 "$ref": "#rsaKeyType" 2012 }, 2013 { 2014 "$ref": "#ecdsaKeyType" 2015 } 2016 ] 2017 } 2018 }, 2019 "subject": { 2020 "$ref": "#distinguished-name" 2021 }, 2022 "extensions": { 2023 "type": "object", 2024 "properties": { 2025 "keyUsage": { 2026 "type": "array", 2027 "minItems": 1, 2028 "items": { 2029 "type": "string", 2030 "enum": [ 2031 "digitalSignature", 2032 "nonRepudiation", 2033 "keyEncipherment", 2034 "dataEncipherment", 2035 "keyAgreement", 2036 "keyCertSign", 2037 "cRLSign", 2038 "encipherOnly", 2039 "decipherOnly" 2040 ] 2041 } 2042 }, 2043 "extendedKeyUsage": { 2044 "type": "array", 2045 "minItems": 1, 2046 "items": { 2047 "anyOf": [ 2048 { 2049 "type": "string", 2050 "enum": [ 2051 "serverAuth", 2052 "clientAuth", 2053 "codeSigning", 2054 "emailProtection", 2055 "timeStamping", 2056 "OCSPSigning" 2057 ] 2058 }, 2059 { 2060 "type": "string", 2061 "pattern": "^([0-2])((\\.0)|(\\.[1-9][0-9]*))*$", 2062 "description": "Used for OID values" 2063 } 2064 ] 2065 } 2066 }, 2067 "subjectAltName": { 2068 "type": "object", 2069 "minProperties": 1, 2070 "properties": { 2071 "DNS": { 2072 "type": "array", 2073 "minItems": 1, 2074 "items": { 2075 "anyOf": [ 2076 { 2077 "type": "string", 2078 "enum": [ 2079 "*", 2080 "**" 2081 ] 2082 }, 2083 { 2084 "type": "string", 2085 "format": "hostname" 2086 } 2087 ] 2088 } 2089 }, 2090 "Email": { 2091 "type": "array", 2092 "minItems": 1, 2093 "items": { 2094 "type": "string", 2095 "format": "email" 2096 } 2097 }, 2098 "URI": { 2099 "type": "array", 2100 "minItems": 1, 2101 "items": { 2102 "type": "string", 2103 "format": "uri" 2104 } 2105 } 2106 }, 2107 "additionalProperties": false 2108 } 2109 }, 2110 "required": [ 2111 "subjectAltName" 2112 ], 2113 "additionalProperties": false 2114 } 2115 }, 2116 "required": [ 2117 "extensions", 2118 "keyTypes" 2119 ], 2120 "additionalProperties": false 2121 } 2123 Authors' Addresses 2125 Yaron Sheffer 2126 Intuit 2128 Email: yaronf.ietf@gmail.com 2130 Diego López 2131 Telefonica I+D 2133 Email: diego.r.lopez@telefonica.com 2135 Antonio Agustín Pastor Perales 2136 Telefonica I+D 2138 Email: antonio.pastorperales@telefonica.com 2140 Thomas Fossati 2141 ARM 2143 Email: thomas.fossati@arm.com