idnits 2.17.1 draft-sheffer-acme-star-request-01.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 16, 2017) is 2505 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-06 == Outdated reference: A later version (-11) exists of draft-ietf-acme-star-00 == Outdated reference: A later version (-02) exists of draft-fieau-cdni-https-delegation-01 Summary: 1 error (**), 0 flaws (~~), 4 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 18, 2017 O. Gonzalez de Dios 6 A. Pastor Perales 7 Telefonica I+D 8 T. Fossati 9 Nokia 10 June 16, 2017 12 Generating Certificate Requests for Short-Term, Automatically-Renewed 13 (STAR) Certificates 14 draft-sheffer-acme-star-request-01 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 http://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 18, 2017. 47 Copyright Notice 49 Copyright (c) 2017 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 (http://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 Registration . . . . . . . . . . . . . . . 8 75 3.1.2. Polling the Registration . . . . . . . . . . . . . . 9 76 3.2. Transport Security for the STAR Protocol . . . . . . . . 10 77 4. CDNI Use Cases . . . . . . . . . . . . . . . . . . . . . . . 10 78 4.1. Multiple Parallel Delegates . . . . . . . . . . . . . . . 10 79 4.2. Chained Delegation . . . . . . . . . . . . . . . . . . . 11 80 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 81 5.1. STAR Protocol Authentication . . . . . . . . . . . . . . 11 82 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 85 7.2. Informative References . . . . . . . . . . . . . . . . . 12 86 Appendix A. Document History . . . . . . . . . . . . . . . . . . 13 87 A.1. draft-sheffer-acme-star-request-01 . . . . . . . . . . . 13 88 A.2. draft-sheffer-acme-star-request-00 . . . . . . . . . . . 13 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 91 1. Introduction 93 This document is a companion document to [I-D.ietf-acme-star]. To 94 avoid duplication, we give here a barebones description of the 95 motivation for this solution. For more details and further use 96 cases, please refer to the introductory sections of 97 [I-D.ietf-acme-star]. 99 A content provider (referred to in this document as Domain Name 100 Owner, DNO) has agreements in place with one or more Content Delivery 101 Networks (CDNs) that are contracted to serve its content over HTTPS. 102 The CDN terminates the HTTPS connection at one of its edge cache 103 servers and needs to present its clients (browsers, set-top-boxes) a 104 certificate whose name matches the authority of the URL that is 105 requested, i.e. that of the DNO. However, many DNOs balk at sharing 106 their long-term private keys with another organization and, equally, 107 delegates (henceforth referred to as NDC, Name Delegation Consumer) 108 would rather not have to handle other parties' long-term secrets. 110 This document describes a protocol where the DNO and the NDC agree on 111 a CSR template and the NDC generates a CSR for a private key that it 112 holds. The DNO then uses the ACME protocol (as extended in 113 [I-D.ietf-acme-star] to issue the STAR certificate. 115 The generated short-term certificate is automatically renewed by an 116 ACME Certification Authority (CA) [I-D.ietf-acme-acme] and routinely 117 fetched into the NDC and used for HTTPS connections. The DNO can end 118 the delegation at any time by simply instructing the CA to stop the 119 automatic renewal and letting the certificate expire shortly 120 thereafter. 122 1.1. Terminology 124 DNO Domain Name Owner, the owner of a domain that needs to be 125 delegated. 126 NDC Name Delegation Consumer, the entity to which the domain name is 127 delegated for a limited time. This is often a CDN (in fact, 128 readers may note the similarity of the two acronyms). 129 CDN Content Delivery Network, a widely distributed network that 130 serves the domain's web content to a wide audience at high 131 performance. 132 STAR Short-Term, Automatically Renewed X.509 certificates. 133 ACME The IETF Automated Certificate Management Environment, a 134 certificate management protocol. 135 CA A Certificate Authority that implements the ACME protocol. 137 1.2. Conventions used in this document 139 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 140 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 141 "OPTIONAL" in this document are to be interpreted as described in 142 [RFC2119]. 144 2. Protocol Flow 146 This section presents the protocol flow. For completeness, we 147 include the STAR Interface proposed in this draft, as well as the 148 extended ACME protocol as described in [I-D.ietf-acme-star]. 150 2.1. Preconditions 152 The protocol assumes the following preconditions are met: 154 o A mutually authenticated channel between NDC and DNO pre-exists. 155 This is called "STAR channel" and all STAR protocol exchanges 156 between NDC and DNO are run over it. It provides the guarantee 157 that requests and responses are authentic. 158 o NDC and DNO have agreed on a "CSR template" to use, including at a 159 minimum: 161 - Subject name (e.g., "somesite.example.com"), 162 - Requested algorithms, 163 - Key length, 164 - Key usage. 166 The NDC is required to use this template for every CSR created 167 under the same delegation. 168 o DNO has registered through the ACME interface exposed by the 169 Certificate Authority (CA) using the usual ACME registration 170 procedure. In ACME terms, the DNO has an Account on the server 171 and is ready to issue Orders. 173 2.2. Bootstrap 175 The NDC (STAR Client) generates a key-pair, wraps it into a 176 Certificate Signing Request (CSR) according to the agreed upon CSR 177 template, and sends it to the DNO (STAR Proxy) over the pre- 178 established STAR channel. The DNO uses the NDC identity provided on 179 the STAR channel to look up the CSR template that applies to the 180 requesting NDC and decides whether or not to accept the request. 181 Assuming everything is in order, it then "forwards" the NDC request 182 to the ACME CA by means of the usual ACME application procedure. 183 Specifically, the DNO, in its role as an ACME client, requests the CA 184 to issue a STAR certificate, i.e., one that: 186 o Has a short validity (e.g., 24 to 72 hours); 187 o Is automatically renewed by the CA for a certain period of time; 188 o Is downloadable from a (highly available) public link without 189 requiring any special authorization. 191 Other than that, the ACME protocol flows as normal between DNO and 192 CA, in particular DNO is responsible for satisfying the requested 193 ACME challenges until the CA is willing to issue the requested 194 certificate. Per normal ACME processing, the DNO is given back an 195 Order ID for the issued STAR certificate to be used in subsequent 196 interaction with the CA (e.g., if the certificate needs to be 197 terminated.) 199 Concurrently, a response is sent back to the NDC with an endpoint to 200 poll for completion of the certificate generation process. 202 The bootstrap phase ends when the DNO obtains the OK from the ACME CA 203 and posts the certificate's URL to the "completion endpoint" where 204 the NDC can retrieve it. 206 ........................... 207 STAR : STAR Proxy / : ACME/STAR 208 Client : ACME Client : Server 209 | : | | : | 210 | : | | ACME registration | 211 +-------. : | |<--------------------->| 212 | | : | | STAR capabilities | 213 | generate CSR : | | : | 214 | | : | | : | 215 |<------' : | | : | 216 | : | | : | 217 | Request new : | | : | 218 +---------------------->| | : | 219 | cert for CSR : | | : | 220 | : +-------. | : | 221 | : | | | : | 222 | : | Verify CSR | : | 223 | : | | | : | 224 | : +<------' | : | 225 | Accepted, poll at | | : | 226 |<----------------------+ | : | 227 | "completion URL" |- - - - - - - >| Application for | 228 | : | +---------------------->| 229 | : | | STAR certificate | 230 | : | | : | 231 | GET "completion URL" | | : Challenge | 232 |<--------------------->| |<--------------------->| 233 | in progress : | | : Response | 234 | : | | : | 235 | : | | Finalize/Certificate | 236 | : | |<----------------------+ 237 | GET "completion URL" |< - - - - - - -| : + Order Id | 238 +---------------------->| | : | 239 | : | | : | 240 | 200, certificate URL | | : | 241 |<----------------------+ | : | 242 | and other metadata | | : | 243 | : | | : | 244 `.........................' 246 Figure 1: Bootstrap 248 2.3. Refresh 250 The CA automatically re-issues the certificate (using the same CSR) 251 before it expires and publishes it to the URL that the NDC has come 252 to know at the end of the bootstrap phase. The NDC downloads and 253 installs it. This process goes on until either: 255 o DNO terminates the delegation, or 256 o Automatic renewal expires. 258 STAR ACME/STAR 259 Client Server 260 | Retrieve cert | [...] 261 |<--------------------->| | 262 | +------. / 263 | | | / 264 | | Automatic renewal : 265 | | | \ 266 | |<-----' \ 267 | Retrieve cert | | 268 |<--------------------->| 72 hours 269 | | | 270 | +------. / 271 | | | / 272 | | Automatic renewal : 273 | | | \ 274 | |<-----' \ 275 | Retrieve cert | | 276 |<--------------------->| 72 hours 277 | | | 278 | +------. / 279 | | | / 280 | | Automatic renewal : 281 | | | \ 282 | |<-----' \ 283 | | | 284 | [...] | [...] 286 Figure 2: Auto renewal 288 2.4. Termination 290 The DNO may request early termination of the STAR certificate by 291 including the Order ID in a certificate termination request to the 292 ACME interface, defined below. After the CA receives and verifies 293 the request, it shall: 295 o Cancel the automatic renewal process for the STAR certificate; 296 o Change the certificate publication resource to return an error 297 indicating the termination of the delegation to external clients, 298 including the NDC. 300 Note that it is not necessary to explicitly revoke the short-term 301 certificate. 303 STAR STAR ACME/STAR 304 Client Proxy Server 305 | | | 306 | | Terminate Order ID | 307 | +---------------------->| 308 | | +-------. 309 | | | | 310 | | | End auto renewal 311 | | | Remove cert link 312 | | | etc. 313 | | | | 314 | | Done |<------' 315 | |<----------------------+ 316 | | | 317 | | 318 | Retrieve cert | 319 +---------------------------------------------->| 320 | Error: terminated | 321 |<----------------------------------------------+ 322 | | 324 Figure 3: Termination 326 3. Protocol Details 328 This section describes the STAR API between the STAR Client and the 329 STAR Proxy. 331 3.1. STAR API 333 This API allows the STAR Client to request a STAR certificate via the 334 STAR Proxy, using a previously agreed-upon CSR template. 336 The API consists of a single resource, "registration". A new 337 Registration is created with a POST request, and the Registration 338 instance is polled to obtain its details. 340 3.1.1. Creating a Registration 342 To create a registration, use: 344 POST /star/registration 345 Host: star-proxy.example.net 346 Content-Type: application/json 348 { 349 "csr": "...", // CSR in PEM format 350 "lifetime": 365, // requested registration lifetime in days, 351 // between 1 and 1095 352 "validity": 7 // requested certificate validity in days 353 } 355 The STAR Proxy MAY treat both "lifetime" and "validity" periods as 356 hints. Upon success, the call returns the new Registration resource. 358 HTTP/1.1 201 Created 359 Location: https://star-proxy.example.net/star/registration/567 361 3.1.2. Polling the Registration 363 The returned Registration can be polled until the information is 364 available from the ACME server. 366 GET /star/registration/567 367 Host: star-proxy.example.net 369 In responding to poll requests while the validation is still in 370 progress, the server MUST return a 200 (OK) response and MAY include 371 a Retry-After header field to suggest a polling interval to the 372 client. The Retry-After value MUST be expressed in seconds. If the 373 Retry-After header is present, in order to avoid surprising 374 interactions with heuristic expiration times, a max-age Cache-Control 375 SHOULD also be present and set to a value slightly smaller than the 376 Retry-After value. 378 HTTP/1.1 200 OK 379 Retry-After: 10 380 Cache-Control: max-age=9 382 { 383 "status": "pending" 384 } 386 When the operation is successfully completed, the ACME Proxy returns: 388 HTTP/1.1 200 OK 389 Expires: Sun, 09 Sep 2018 14:09:00 GMT 391 { 392 "status": "valid", // or "failed" 393 "lifetime": 365, // lifetime of the registration in days, 394 // possibly less than requested 395 "certificates": "https://acme-server.example.org/certificates/A51A3" 396 } 398 The Expires header applies to the Registration resource itself, and 399 may be as small as a few minutes. It is unrelated to the Order's 400 lifetime which is measured in days or longer. The "certificates" 401 attribute contains a URL of the certificate pull endpoint, received 402 from the ACME Server. 404 If the registration fails for any reason, the server returns a "200 405 OK" response, with the status as "failed" and a "reason" attribute 406 containing a human readable error message. 408 3.2. Transport Security for the STAR Protocol 410 Traffic between the STAR Client and the STAR Proxy MUST be protected 411 with HTTPS. For interoperability, all implementations MUST support 412 HTTP Basic Authentication [RFC7617]. However some deployments MAY 413 prefer mutually- authenticated HTTPS or two-legged OAUTH. 415 4. CDNI Use Cases 417 Members of the IETF CDNI (Content Delivery Network Interconnection) 418 working group are interested in delegating authority over web content 419 to CDNs. Their requirements are described in a draft 420 [I-D.fieau-cdni-https-delegation] that compares several solutions. 421 This section discusses two particular requirements in the context of 422 the STAR protocol. 424 4.1. Multiple Parallel Delegates 426 In some cases the DNO would like to delegate authority over a web 427 site to multiple CDNs. This could happen if the DNO has agreements 428 in place with different regional CDNs for different geographical 429 regions. STAR enables this use case naturally, since each CDN can 430 authenticate separately to the DNO specifying its CSR, and the DNO is 431 free to allow or deny each certificate request according to its own 432 policy. 434 4.2. Chained Delegation 436 In other cases, a content owner (DNO) delegates some domains to a 437 large CDN (CDN1), which in turn delegates to a smaller regional CDN, 438 CDN2. The DNO has a contractual relationship with CDN1, and CDN1 has 439 a similar relationship with CDN2. However DNO may not even know 440 about CDN2. 442 The STAR protocol does not prevent this use case, although there is 443 no special support for it. CDN1 can forward requests from CDN2 to 444 DNO, and forward responses back to CDN2. Whether such proxying is 445 allowed is governed by policy and contracts between the parties. 447 5. Security Considerations 449 5.1. STAR Protocol Authentication 451 The STAR protocol allows its client to obtain certificates bearing 452 the DNO's identity. Therefore strong client authentication is 453 mandatory. 455 When multiple NDCs may connect to the same DNO, the STAR protocol's 456 authentication MUST allow the DNO to distinguish between different 457 NDCs, and the DNO MUST associate different Registration objects to 458 different clients. Among other benefits, this allows the DNO to 459 cancel a STAR registration for one of its clients instead of all of 460 them. 462 6. Acknowledgments 464 This work is partially supported by the European Commission under 465 Horizon 2020 grant agreement no. 688421 Measurement and Architecture 466 for a Middleboxed Internet (MAMI). This support does not imply 467 endorsement. 469 7. References 471 7.1. Normative References 473 [I-D.ietf-acme-acme] 474 Barnes, R., Hoffman-Andrews, J., and J. Kasten, "Automatic 475 Certificate Management Environment (ACME)", draft-ietf- 476 acme-acme-06 (work in progress), March 2017. 478 [I-D.ietf-acme-star] 479 Sheffer, Y., Lopez, D., Dios, O., Pastor, A., and T. 480 Fossati, "Use of Short-Term, Automatically-Renewed (STAR) 481 Certificates to Delegate Authority over Web Sites", draft- 482 ietf-acme-star-00 (work in progress), June 2017. 484 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 485 Requirement Levels", BCP 14, RFC 2119, 486 DOI 10.17487/RFC2119, March 1997, 487 . 489 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 490 RFC 7617, DOI 10.17487/RFC7617, September 2015, 491 . 493 7.2. Informative References 495 [I-D.fieau-cdni-https-delegation] 496 Fieau, F., Emile, S., and S. Mishra, "HTTPS delegation in 497 CDNI", draft-fieau-cdni-https-delegation-01 (work in 498 progress), March 2017. 500 Appendix A. Document History 502 [[Note to RFC Editor: please remove before publication.]] 504 A.1. draft-sheffer-acme-star-request-01 506 o Correct reference to WG draft. 508 A.2. draft-sheffer-acme-star-request-00 510 o Initial version, the STAR API extracted from draft-sheffer-acme- 511 star-02. 513 Authors' Addresses 515 Yaron Sheffer 516 Intuit 518 EMail: yaronf.ietf@gmail.com 520 Diego Lopez 521 Telefonica I+D 523 EMail: diego.r.lopez@telefonica.com 525 Oscar Gonzalez de Dios 526 Telefonica I+D 528 EMail: oscar.gonzalezdedios@telefonica.com 530 Antonio Agustin Pastor Perales 531 Telefonica I+D 533 EMail: antonio.pastorperales@telefonica.com 535 Thomas Fossati 536 Nokia 538 EMail: thomas.fossati@nokia.com