idnits 2.17.1 draft-sheffer-acme-star-request-02.txt: 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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 29, 2018) is 2128 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-18) exists of draft-ietf-acme-acme-12 == Outdated reference: A later version (-11) exists of draft-ietf-acme-star-03 ** Downref: Normative reference to an Informational RFC: RFC 2986 ** Obsolete normative reference: RFC 7807 (Obsoleted by RFC 9457) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). 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. Lopez 5 Expires: December 31, 2018 O. Gonzalez de Dios 6 A. Pastor Perales 7 Telefonica I+D 8 T. Fossati 9 Nokia 10 June 29, 2018 12 Generating Certificate Requests for Short-Term, Automatically-Renewed 13 (STAR) Certificates 14 draft-sheffer-acme-star-request-02 16 Abstract 18 This memo proposes a protocol that allows a domain name owner to 19 delegate to a third party (such as a CDN) control over a certificate 20 that bears one or more names in that domain. Specifically the third 21 party creates a Certificate Signing Request for the domain, which can 22 then be used by the domain owner to request a short term and 23 automatically renewed (STAR) certificate. 25 This is a component in a solution where a third-party such as a CDN 26 can terminate TLS sessions on behalf of a domain name owner (e.g., a 27 content provider), and the domain owner can cancel this delegation at 28 any time without having to rely on certificate revocation mechanisms. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on December 31, 2018. 47 Copyright Notice 49 Copyright (c) 2018 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.2. Conventions used in this document . . . . . . . . . . . . 4 67 2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2.1. Preconditions . . . . . . . . . . . . . . . . . . . . . . 4 69 2.2. Bootstrap . . . . . . . . . . . . . . . . . . . . . . . . 4 70 2.3. Refresh . . . . . . . . . . . . . . . . . . . . . . . . . 6 71 2.4. Termination . . . . . . . . . . . . . . . . . . . . . . . 7 72 3. Protocol Details . . . . . . . . . . . . . . . . . . . . . . 8 73 3.1. STAR API . . . . . . . . . . . . . . . . . . . . . . . . 8 74 3.1.1. Creating a Delegation Request . . . . . . . . . . . . 8 75 3.1.2. Polling the Delegation Request . . . . . . . . . . . 10 76 3.2. Transport Security for the STAR Protocol . . . . . . . . 11 77 4. CDNI Use Cases . . . . . . . . . . . . . . . . . . . . . . . 11 78 4.1. Multiple Parallel Delegates . . . . . . . . . . . . . . . 11 79 4.2. Chained Delegation . . . . . . . . . . . . . . . . . . . 11 80 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 81 5.1. STAR Protocol Authentication . . . . . . . . . . . . . . 12 82 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 12 85 7.2. Informative References . . . . . . . . . . . . . . . . . 13 86 Appendix A. Document History . . . . . . . . . . . . . . . . . . 14 87 A.1. draft-sheffer-acme-star-request-02 . . . . . . . . . . . 14 88 A.2. draft-sheffer-acme-star-request-01 . . . . . . . . . . . 14 89 A.3. draft-sheffer-acme-star-request-00 . . . . . . . . . . . 14 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 92 1. Introduction 94 This document is a companion document to [I-D.ietf-acme-star]. To 95 avoid duplication, we give here a bare-bones description of the 96 motivation for this solution. For more details and further use 97 cases, please refer to the introductory sections of 98 [I-D.ietf-acme-star]. 100 A content provider (referred to in this document as Domain Name 101 Owner, DNO, or more generally as Identity Owner, IdO) has agreements 102 in place with one or more Content Delivery Networks (CDNs) that are 103 contracted to serve its content over HTTPS. The CDN terminates the 104 HTTPS connection at one of its edge cache servers and needs to 105 present its clients (browsers, set-top-boxes) a certificate whose 106 name matches the authority of the URL that is requested, i.e. that of 107 the DNO. However, many DNOs balk at sharing their long-term private 108 keys with another organization and, equally, delegates (henceforth 109 referred to as NDC, Name Delegation Consumer) would rather not have 110 to handle other parties' long-term secrets. 112 This document describes a protocol where the IdO and the NDC agree on 113 a CSR template and the NDC generates a CSR for a private key that it 114 holds. The IdO then uses the ACME protocol (as extended in 115 [I-D.ietf-acme-star]) to issue the STAR certificate. 117 The generated short-term certificate is automatically renewed by an 118 ACME Certification Authority (CA) [I-D.ietf-acme-acme] and 119 periodically fetched into the NDC and used for HTTPS connections. 120 The IdO can end the delegation at any time by simply instructing the 121 CA to stop the automatic renewal and letting the certificate expire 122 shortly thereafter. 124 1.1. Terminology 126 IdO Identity Owner, the owner of an identity (e.g., a domain name) 127 that needs to be delegated. 128 DNO Domain Name Owner, a specific kind of IdO whose identity is a 129 domain name. 130 NDC Name Delegation Consumer, the entity to which the domain name is 131 delegated for a limited time. This is often a CDN (in fact, 132 readers may note the similarity of the two acronyms). 133 CDN Content Delivery Network, a widely distributed network that 134 serves the domain's web content to a wide audience at high 135 performance. 136 STAR Short-Term, Automatically Renewed X.509 certificates. 137 ACME The IETF Automated Certificate Management Environment, a 138 certificate management protocol. 139 CA A Certificate Authority that implements the ACME protocol. 141 1.2. Conventions used in this document 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 145 "OPTIONAL" in this document are to be interpreted as described in 146 [RFC2119]. 148 2. Protocol Flow 150 This section presents the protocol flow. For completeness, we 151 include the STAR Interface proposed in this draft, as well as the 152 extended ACME protocol as described in [I-D.ietf-acme-star]. 154 2.1. Preconditions 156 The protocol assumes the following preconditions are met: 158 o A mutually authenticated channel between NDC and IdO pre-exists. 159 This is called "STAR channel" and all STAR protocol exchanges 160 between NDC and IdO are run over it. It provides the guarantee 161 that requests and responses are authentic. 162 o NDC and IdO have agreed on a "CSR template" to use, including at a 163 minimum: 165 - Subject name (e.g., "somesite.example.com"), 166 - Requested algorithms, 167 - Key length, 168 - Key usage. 170 The NDC is required to use this template for every CSR created 171 under the same delegation. 172 o IdO has registered through the ACME interface exposed by the 173 Certificate Authority (CA) using the usual ACME registration 174 procedure. In ACME terms, the IdO has an Account on the server 175 and is ready to issue Orders. 177 2.2. Bootstrap 179 The NDC (STAR Client) generates a key-pair, wraps it into a 180 Certificate Signing Request (CSR) according to the agreed upon CSR 181 template, and sends it to the IdO (STAR Proxy) over the pre- 182 established STAR channel. The IdO uses the NDC identity provided on 183 the STAR channel to look up the CSR template that applies to the 184 requesting NDC and decides whether or not to accept the request. 185 Assuming everything is in order, it then "forwards" the NDC request 186 to the ACME CA by means of the usual ACME application procedure. 187 Specifically, the IdO, in its role as an ACME client, requests the CA 188 to issue a STAR certificate, i.e., one that: 190 o Has a short validity (e.g., 24 to 72 hours); 191 o Is automatically renewed by the CA for a certain period of time; 192 o Is downloadable from a (highly available) public link without 193 requiring any special authorization. 195 Other than that, the ACME protocol flows as normal between IdO and 196 CA, in particular IdO is responsible for satisfying the requested 197 ACME challenges until the CA is willing to issue the requested 198 certificate. Per normal ACME processing, the IdO is given back an 199 Order ID for the issued STAR certificate to be used in subsequent 200 interaction with the CA (e.g., if the certificate needs to be 201 terminated.) 203 Concurrently, a response is sent back to the NDC with an endpoint to 204 poll for completion of the certificate generation process. 206 The bootstrap phase ends when the IdO obtains the OK from the ACME CA 207 and posts the certificate's URL to the "completion endpoint" where 208 the NDC can retrieve it. 210 ........................... 211 STAR : STAR Proxy / : ACME/STAR 212 Client : ACME Client : Server 213 | : | | : | 214 | : | | ACME registration | 215 +-------. : | |<--------------------->| 216 | | : | | STAR capabilities | 217 | generate CSR : | | : | 218 | | : | | : | 219 |<------' : | | : | 220 | : | | : | 221 | Request new : | | : | 222 +---------------------->| | : | 223 | cert for CSR : | | : | 224 | : +-------. | : | 225 | : | | | : | 226 | : | Verify CSR | : | 227 | : | | | : | 228 | : +<------' | : | 229 | Accepted, poll at | | : | 230 |<----------------------+ | : | 231 | "completion URL" |- - - - - - - >| Application for | 232 | : | +---------------------->| 233 | : | | STAR certificate | 234 | : | | : | 235 | GET "completion URL" | | : Challenge | 236 |<--------------------->| |<--------------------->| 237 | in progress : | | : Response | 238 | : | | : | 239 | : | | Finalize/Certificate | 240 | : | |<----------------------+ 241 | GET "completion URL" |< - - - - - - -| : + Order Id | 242 +---------------------->| | : | 243 | : | | : | 244 | 200, certificate URL | | : | 245 |<----------------------+ | : | 246 | and other metadata | | : | 247 | : | | : | 248 `.........................' 250 Figure 1: Bootstrap 252 2.3. Refresh 254 The CA automatically re-issues the certificate (using the same CSR) 255 before it expires and publishes it to the URL that the NDC has come 256 to know at the end of the bootstrap phase. The NDC downloads and 257 installs it. This process goes on until either: 259 o IdO terminates the delegation, or 260 o Automatic renewal expires. 262 STAR ACME/STAR 263 Client Server 264 | Retrieve cert | [...] 265 |<--------------------->| | 266 | +------. / 267 | | | / 268 | | Automatic renewal : 269 | | | \ 270 | |<-----' \ 271 | Retrieve cert | | 272 |<--------------------->| 72 hours 273 | | | 274 | +------. / 275 | | | / 276 | | Automatic renewal : 277 | | | \ 278 | |<-----' \ 279 | Retrieve cert | | 280 |<--------------------->| 72 hours 281 | | | 282 | +------. / 283 | | | / 284 | | Automatic renewal : 285 | | | \ 286 | |<-----' \ 287 | | | 288 | [...] | [...] 290 Figure 2: Auto renewal 292 2.4. Termination 294 The IdO may request early termination of the STAR certificate by 295 including the Order ID in a certificate termination request to the 296 ACME interface, defined below. After the CA receives and verifies 297 the request, it shall: 299 o Cancel the automatic renewal process for the STAR certificate; 300 o Change the certificate publication resource to return an error 301 indicating the termination of the delegation to external clients, 302 including the NDC. 304 Note that it is not necessary to explicitly revoke the short-term 305 certificate. 307 STAR STAR ACME/STAR 308 Client Proxy Server 309 | | | 310 | | Terminate Order ID | 311 | +---------------------->| 312 | | +-------. 313 | | | | 314 | | | End auto renewal 315 | | | Remove cert link 316 | | | etc. 317 | | | | 318 | | Done |<------' 319 | |<----------------------+ 320 | | | 321 | | 322 | Retrieve cert | 323 +---------------------------------------------->| 324 | Error: terminated | 325 |<----------------------------------------------+ 326 | | 328 Figure 3: Termination 330 No facility is provided for the NDC to directly initiate the 331 termination of a STAR certificate. 333 3. Protocol Details 335 This section describes the STAR API between the STAR Client and the 336 STAR Proxy. 338 3.1. STAR API 340 This API allows an IdO (STAR Proxy) to control the long-term 341 delegation of one of its names to an authorized third-party (STAR 342 Client). 344 3.1.1. Creating a Delegation Request 346 To create a new delegation request, the client wraps the following 347 parameters in a POST to the '/star/delegation' path: 349 o csr (required, string): A CSR encoding the parameters for the 350 certificate being requested [RFC2986]. The CSR is sent in the 351 base64url-encoded version of the DER format. (Note: Because this 352 field uses base64url, and does not include headers, it is 353 different from PEM.) 355 o duration (optional, integer): How long the delegation should last 356 (in seconds). If not specified, a local default applies. 357 o certificate-lifetime (optional, integer): How long each short-term 358 certificate should last (in seconds). If not specified, a local 359 default applies. 361 Note that the STAR Proxy MAY treat both "duration" and "certificate- 362 lifetime" as hints, and MAY update any of them due to local policy 363 decisions or as a result of the interaction with the ACME server. 365 POST /star/delegation 366 Host: star-proxy.example.net 367 Content-Type: application/json 369 { 370 "csr": "jcRf4uXra7FGYW5ZMewvV...rhlnznwy8YbpMGqwidEXfE", 371 "duration": 31536000, 372 "certificate-lifetime": 604800 373 } 375 On success, the service returns a 201 Created status with the URL of 376 the newly generated delegation order in the Location header field. 377 The current state of the delegation order is returned in the body of 378 the response in JSON format: 380 HTTP/1.1 201 Created 381 Content-Type: application/json 382 Location: http://example.net/star/delegation/567 384 { 385 "id": "567", 386 "certificate-lifetime": 604800, 387 "duration": 31536000, 388 "status": "new" 389 } 391 If an error occurs, an error response (4XX or 5XX) is generated with 392 an appropriate problem detail [RFC7807] body, e.g.: 394 HTTP/1.1 400 Bad Request 395 Content-Type: application/problem+json 397 { 398 "type": "https://example.net/validation-error", 399 "title": "Your request parameters didn't validate.", 400 "invalid-params": [ { 401 "name": "csr", 402 "reason": "missing mandatory parameter" 403 } ] 404 } 406 3.1.2. Polling the Delegation Request 408 The returned delegation order URL can be polled until the dialog 409 between the STAR Proxy and the ACME server is complete (i.e., the 410 "status" attribute changes from "new" or "pending" to one of "failed" 411 or "success"): 413 GET /star/delegation/567 414 Host: star-proxy.example.net 416 In responding to poll requests while the validation is still in 417 progress, the server MUST return a 200 (OK) response and MAY include 418 a Retry-After header field to suggest a polling interval to the 419 client. The Retry-After value MUST be expressed in seconds. If the 420 Retry-After header is present, in order to avoid surprising 421 interactions with heuristic expiration times, a max-age Cache-Control 422 SHOULD also be present and set to a value slightly smaller than the 423 Retry-After value: 425 HTTP/1.1 200 OK 426 Content-Type: application/json 427 Retry-After: 10 428 Cache-Control: max-age=9 430 { 431 "id": "5", 432 "certificate-lifetime": 604800, 433 "creation-date": "2017-11-12T01:38:09Z", 434 "duration": 31536000, 435 "status": "pending" 436 } 438 When the operation is successfully completed, the ACME Proxy returns: 440 HTTP/1.1 200 OK 442 { 443 "status": "success", // or "failed" 444 "lifetime": 365, // lifetime of the registration in days, 445 // possibly less than requested 446 "certificates": "https://ca.example.org/certificates/A51A3" 447 } 449 The "certificates" attribute contains a URL of the certificate pull 450 endpoint, received from the ACME Server. 452 If the registration fails for any reason, the server returns a "200 453 OK" response, with the status as "failed" and a "reason" attribute 454 containing a human readable error message. 456 3.2. Transport Security for the STAR Protocol 458 Traffic between the STAR Client and the STAR Proxy MUST be protected 459 with HTTPS. For interoperability, all implementations MUST support 460 HTTP Basic Authentication [RFC7617]. However some deployments MAY 461 prefer mutually-authenticated HTTPS or two-legged OAUTH. 463 4. CDNI Use Cases 465 Members of the IETF CDNI (Content Delivery Network Interconnection) 466 working group are interested in delegating authority over web content 467 to CDNs. Their requirements are described in a draft 468 [I-D.fieau-cdni-https-delegation] that compares several solutions. 469 This section discusses two particular requirements in the context of 470 the STAR protocol. 472 4.1. Multiple Parallel Delegates 474 In some cases the DNO would like to delegate authority over a web 475 site to multiple CDNs. This could happen if the DNO has agreements 476 in place with different regional CDNs for different geographical 477 regions. STAR enables this use case naturally, since each CDN can 478 authenticate separately to the DNO specifying its CSR, and the DNO is 479 free to allow or deny each certificate request according to its own 480 policy. 482 4.2. Chained Delegation 484 In other cases, a content owner (DNO) delegates some domains to a 485 large CDN (CDN1), which in turn delegates to a smaller regional CDN, 486 CDN2. The DNO has a contractual relationship with CDN1, and CDN1 has 487 a similar relationship with CDN2. However DNO may not even know 488 about CDN2. 490 The STAR protocol does not prevent this use case, although there is 491 no special support for it. CDN1 can forward requests from CDN2 to 492 DNO, and forward responses back to CDN2. Whether such proxying is 493 allowed is governed by policy and contracts between the parties. 495 5. Security Considerations 497 5.1. STAR Protocol Authentication 499 The STAR protocol allows its client to obtain certificates bearing 500 the IdO's identity. Therefore strong client authentication is 501 mandatory. 503 When multiple NDCs may connect to the same IdO, the STAR protocol's 504 authentication MUST allow the IdO to distinguish between different 505 NDCs, and the IdO MUST associate different Registration objects to 506 different clients. Among other benefits, this allows the IdO to 507 cancel a STAR registration for one of its clients instead of all of 508 them. 510 6. Acknowledgments 512 This work is partially supported by the European Commission under 513 Horizon 2020 grant agreement no. 688421 Measurement and Architecture 514 for a Middleboxed Internet (MAMI). This support does not imply 515 endorsement. 517 7. References 519 7.1. Normative References 521 [I-D.ietf-acme-acme] 522 Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 523 Kasten, "Automatic Certificate Management Environment 524 (ACME)", draft-ietf-acme-acme-12 (work in progress), April 525 2018. 527 [I-D.ietf-acme-star] 528 Sheffer, Y., Lopez, D., Dios, O., Pastor, A., and T. 529 Fossati, "Support for Short-Term, Automatically-Renewed 530 (STAR) Certificates in Automated Certificate Management 531 Environment (ACME)", draft-ietf-acme-star-03 (work in 532 progress), March 2018. 534 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 535 Requirement Levels", BCP 14, RFC 2119, 536 DOI 10.17487/RFC2119, March 1997, 537 . 539 [RFC2986] Nystrom, M. and B. Kaliski, "PKCS #10: Certification 540 Request Syntax Specification Version 1.7", RFC 2986, 541 DOI 10.17487/RFC2986, November 2000, 542 . 544 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 545 RFC 7617, DOI 10.17487/RFC7617, September 2015, 546 . 548 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 549 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 550 . 552 7.2. Informative References 554 [I-D.fieau-cdni-https-delegation] 555 Fieau, F., Emile, S., and S. Mishra, "HTTPS delegation in 556 CDNI", draft-fieau-cdni-https-delegation-02 (work in 557 progress), July 2017. 559 Appendix A. Document History 561 [[Note to RFC Editor: please remove before publication.]] 563 A.1. draft-sheffer-acme-star-request-02 565 o Clarifications and minor changes based on implementation 566 experience. 567 o More detail on error cases. 569 A.2. draft-sheffer-acme-star-request-01 571 o Correct reference to WG draft. 573 A.3. draft-sheffer-acme-star-request-00 575 o Initial version, the STAR API extracted from draft-sheffer-acme- 576 star-02. 578 Authors' Addresses 580 Yaron Sheffer 581 Intuit 583 EMail: yaronf.ietf@gmail.com 585 Diego Lopez 586 Telefonica I+D 588 EMail: diego.r.lopez@telefonica.com 590 Oscar Gonzalez de Dios 591 Telefonica I+D 593 EMail: oscar.gonzalezdedios@telefonica.com 595 Antonio Agustin Pastor Perales 596 Telefonica I+D 598 EMail: antonio.pastorperales@telefonica.com 599 Thomas Fossati 600 Nokia 602 EMail: thomas.fossati@nokia.com