idnits 2.17.1 draft-ietf-acme-authority-token-06.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 : ---------------------------------------------------------------------------- ** There are 4 instances of too long lines in the document, the longest one being 13 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 12, 2021) is 1017 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) == Missing Reference: 'RFCThis' is mentioned on line 409, but not defined == Outdated reference: A later version (-13) exists of draft-ietf-acme-authority-token-tnauthlist-08 ** Downref: Normative reference to an Informational RFC: RFC 8396 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Peterson 3 Internet-Draft Neustar 4 Intended status: Standards Track M. Barnes 5 Expires: January 13, 2022 Independent 6 D. Hancock 7 C. Wendt 8 Comcast 9 July 12, 2021 11 ACME Challenges Using an Authority Token 12 draft-ietf-acme-authority-token-06 14 Abstract 16 Some proposed extensions to the Automated Certificate Management 17 Environment (ACME) rely on proving eligibility for certificates 18 through consulting an external authority that issues a token 19 according to a particular policy. This document specifies a generic 20 Authority Token challenge for ACME which supports subtype claims for 21 different identifiers or namespaces that can be defined separately 22 for specific applications. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on January 13, 2022. 41 Copyright Notice 43 Copyright (c) 2021 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. ACME Authority Token Challenge . . . . . . . . . . . . . . . 3 61 3.1. Token Type Requirements . . . . . . . . . . . . . . . . . 4 62 3.2. Authority Token Scope . . . . . . . . . . . . . . . . . . 4 63 3.3. Binding Challenges . . . . . . . . . . . . . . . . . . . 5 64 4. Authority Token Challenge tkauth-type Registration . . . . . 6 65 5. Acquiring a Token . . . . . . . . . . . . . . . . . . . . . . 7 66 5.1. Basic REST Interface . . . . . . . . . . . . . . . . . . 8 67 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 69 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 70 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 72 9.2. Informative References . . . . . . . . . . . . . . . . . 11 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 75 1. Introduction 77 ACME [RFC8555] is a mechanism for automating certificate management 78 on the Internet. It enables administrative entities to prove 79 effective control over resources like domain names, and automates the 80 process of generating and issuing certificates that attest control or 81 ownership of those resources. 83 In some cases, proving effective control over an identifier requires 84 an attestation from a third party who has authority over the 85 resource, for example, an external policy administrator for a 86 namespace other than the DNS application ACME was originally designed 87 to support. In order to automate the process of issuing certificates 88 for those resources, this specification defines a generic Authority 89 Token challenge that ACME servers can issue in order to require 90 clients to return such a token. The challenge contains a type 91 indication that tells the client what sort of token it needs to 92 acquire. It is expected that the Authority Token challenge will be 93 usable for a variety of identifier types. In particular, this 94 document describes an architecture for Authority Tokens, defines a 95 the Authority Token format along with a protocol for token 96 acquisition, and shows how to integrate these tokens into an ACME 97 challenge. 99 For example, the system of [I-D.ietf-acme-authority-token-tnauthlist] 100 provides a mechanism that allows service providers to acquire 101 certificates corresponding to a Service Provider Code (SPC) as 102 defined in [RFC8226] by consulting an external authority responsible 103 for those codes. Furthermore, Communications Service Providers 104 (CSPs) can delegate authority over numbers to their customers, and 105 those CSPs who support ACME can then help customers to acquire 106 certificates for those numbering resources with ACME. This can 107 permit number acquisition flows compatible with those shown in 108 [RFC8396]. 110 2. Terminology 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in BCP 115 14 [RFC2119] [RFC8174] when, and only when, they appear in all 116 capitals, as shown here. 118 3. ACME Authority Token Challenge 120 Proving that a device on the Internet has effective control over a 121 non-Internet resource is not as straightforward as proving control 122 over an Internet resources like a DNS zone or a web page. Provided 123 that the issuer of identifiers in a namespace, or someone acting on 124 the issuer's behalf, can implement a service that grants Authority 125 Tokens to the people to whom it has issued identifiers, a generic 126 token could be used as a response to an ACME challenge. This 127 specification, therefore, defines an Authority Token issued by an 128 authority over a namespace to an ACME client for delivery to a CA in 129 response to a challenge. Authority over a hierarchical namespace can 130 also be delegated, so that delegates of a root authority can 131 themselves act as Token Authorities for certain types of names. 133 This architecture assumes a trust relationship between CAs and Token 134 Authorities: that CAs are willing to accept the attestation of Token 135 Authorities for particular types of identifiers as sufficient proof 136 to issue a credential. It furthermore assumes that ACME clients have 137 a relationship with Token Authorities which permits them to 138 authenticate and authorize the issuance of Authority Tokens to the 139 proper entities. This ACME challenge has no applicability to 140 identifiers or authorities where those pre-associations cannot be 141 assumed. 143 The ACME Authority Token Challenge type, "tkauth-01", supports 144 different token subtypes. The token subtype is determined by a new 145 ACME challenge field, tkauth-type. An IANA registry is used to 146 manage the values of tkauth-type, see Section 7. Additionally, this 147 challenge also has a new "token-authority" field to designate a 148 location where a token can be acquired. 150 3.1. Token Type Requirements 152 The IANA will maintain a registry of tkauth-types under a policy of 153 Specification Required. In order to register a new tkauth-type, 154 specifications must address the following requirements; in cases 155 where a tkauth-type admits of its own subtypes, subtypes inherit 156 these requirements. 158 While Authority Token types do not need to be specific to a 159 namespace, every token must carry enough information for a CA to 160 determine the name that it will issue a certificate for. Some types 161 of Authority Token types might be reusable for a number of different 162 namespaces; other might be specific to a particular type of name. 163 Therefore, in defining tkauth-types, future specifications must 164 indicate how a token conveys to the CA the name(s) that the Token 165 Authority is attesting that the ACME client controls. 167 While nothing precludes use cases where an ACME client is itself a 168 Token Authority, an ACME client will typically need a protocol to 169 request and retrieve an Authority Token. The Token Authority will 170 require certain information from an ACME client in order to ascertain 171 that it is the right entity to request a certificate for a particular 172 name. The protocols used to request an Authority Token MUST convey 173 to the Token Authority the identifier type and value from or what 174 will be used in the ACME challenge, as well as the binding (see 175 Section 3.3), and those MUST be reflected in the Authority Token. A 176 baseline mechanism for how the Token Authority authenticates and 177 authorizes ACME clients to receive Authority Tokens is given in 178 Section 5. 180 Because the assignment of resources can change over time, 181 demonstrations of authority must be regularly refreshed. Definitions 182 of a tkauth-type MUST specify how they manage the freshness of 183 authority assignments. Typically, a CA will expect a regular 184 refreshing of the token. 186 3.2. Authority Token Scope 188 An Authority Token is used to answer a challenge from an ACME server, 189 upon a request for the issuance of a certificate. It could be that 190 the Authority Token is requested from the Token Authority after a 191 challenge has been received, or it could be that the Authority Token 192 was acquired prior to the initial ACME client request. A Token 193 Authority could grant to a client an Authority Token that has the 194 exact same scope as the requested certificate; alternatively, an 195 Authority Token could attest to all of the resources that the client 196 is eligible to receive certificates for, which could be a superset of 197 the scope of the requested certificate. 199 For example, imagine a case where an Authority for DNS names knows 200 that a client is eligible to receive certificates for "example.com" 201 and "example.net". The client asks an ACME server for a certificate 202 for "example.com", the server directs the client to acquire an 203 Authority Token from the Token Authority. When the client sends an 204 acquisition request (see Section 5) to the Token Authority, the Token 205 Authority could issue a token scoped just to "example.com", or a 206 token that attests the client is eligible to receive certificates for 207 both "example.com" or "example.net". The advantage of the latter is 208 that if, at a later time (but one within the expiry of the JWT), the 209 client wanted to acquire a certificate for "example.net", it would 210 not have to return to the Token Authority, as the Token effectively 211 pre-authorized the issuance of that certificate. 213 Applications of the Authority Token to different identifier types 214 might require different scopes, so registrations of tkauth-types 215 should be clear if and how a scope greater than that of the requested 216 certificate would be conveyed in a token. 218 3.3. Binding Challenges 220 Applications that use the Authority Token need a way to correlate 221 tokens issued by a Token Authority with the proper ACME client, to 222 prevent replay or cut-and-paste attacks using a token issued for a 223 different purpose. To mitigate this, Authority Tokens contain a 224 binding signed by a Token Authority; an ACME server can use the 225 binding to determine that a Token presented by a client was in fact 226 granted by the Token Authority based on a request from the client, 227 and not from some other entity. 229 Creating a binding from an Authority Token to a particular ACME 230 account entails that the Token could be reused up until its expiry 231 for multiple challenges issued by an ACME server. This might be a 232 desirable property when using short-lived certificates, for example, 233 or in any cases where the ACME server issues challenges more 234 frequently that an Authority Token can or should issue tokens, or in 235 cases where the Authority Token scope (see Section 3.2) is broad, so 236 certificates with a more narrow scope may periodically be issued. 238 For some identifier types, it may be more appropriate to bind the 239 Authority Token to a nonce specific to the challenge rather than to 240 an ACME account fingerprint. Any specification of the use of the 241 nonce for this purpose is left to the identifier type profile for the 242 Authority Token. 244 4. Authority Token Challenge tkauth-type Registration 246 This draft specifies a tkauth-type of "atc" which contains a standard 247 JWT token [RFC7519] using a JWS-defined signature string [RFC7515]. 248 The "atc" tkauth-type MAY be used for any number of different ACME 249 identifier types in the ACME challenge. 251 A new JWT claim, "atc", is defined below and lists the identifier 252 type used in this Authority Token. The "atc" tkauth-type is 253 restricted to the JWTs; if a non-JWT token format is desired for the 254 ACME Authority Token Challenge, a different tkauth-type should be 255 specified and registered in the "ACME Authority Token Challenge 256 Types" registry defined in Section 8. 258 For this ACME Authority Token usage of JWT, the payload of the JWT 259 OPTIONALLY contain an "iss" indicating the Token Authority that 260 generated the token, if the "x5u" element in the header does not 261 already convey that information; typically, this will be the same 262 location that appeared in the "token-authority" field of the ACME 263 challenge. In order to satisfy the requirement for replay prevention 264 the JWT MUST contain a "jti" element, and an "exp" claim; the "exp" 265 claim manages token freshness. In addition to helping to manage 266 replay, the "jti" provides a convenient way to reliably track with 267 the same "atc" Authority Token is being used for multiple challenges 268 over time within its set expiry. 270 The JWT payload MUST also contain a new JWT claim, "atc", for 271 Authority Token Challenge, which contains three mandatory elements in 272 an array: the ATC identifier type ("tktype"), the identifier value 273 ("tkvalue"), and the binding ("fingerprint"). The "tkvalue" 274 indicates the scope of the authority that the token, and its 275 semantics are outside the scope of this document. The identifier 276 type and value are those given in the ACME challenge and conveyed to 277 the Token Authority by the ACME client. 279 Following the example of [I-D.ietf-acme-authority-token-tnauthlist], 280 the "tkvalue" identifier type could be the TNAuthList, with a 281 "tkvalue" as defined in [RFC8226] that the Token Authority is 282 attesting. Practically speaking, that scope may comprise a list of 283 Service Provider Code elements, telephone number range elements, and/ 284 or individual telephone numbers. For the purposes of the "atc" 285 tkauth-type, the binding "fingerprint" is assumed to be a fingerprint 286 of the ACME credential for the account used to request the 287 certificate, but the specification of how the binding is generated is 288 left to the identifier type profile for the Authority Token. So for 289 example: 291 { 292 "protected": base64url({ 293 "typ":"JWT", 294 "alg":"ES256", 295 "x5u":"https://authority.example.org/cert" 296 }), 297 "payload": base64url({ 298 "iss":"https://authority.example.org/authz", 299 "exp":1300819380, 300 "jti":"id6098364921", 301 "atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==","fingerprint": 302 "SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:BA:B9:19:81:F8:50: 303 9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} 304 }), 305 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 306 } 308 Optionally, the "atc" claim may contain a fourth element, "ca". If 309 set to "true", the "ca" element indicates that the Token Authority is 310 granting permission to issue a certification authority certificate 311 rather than an end-entity certificate for the names in question. 312 This permits subordinate delegations from the issued certificate. If 313 the "ca" element is absent, the Token Authority is explicitly 314 withholding permission. The "atc" object in the example above would 315 then look like: 317 "atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==","ca":true, 318 "fingerprint":"SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:BA:B9:19:81:F8:50: 319 9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} } 321 Specifications of "tktype" identifier type may define additional 322 optional "atc" elements. 324 5. Acquiring a Token 326 The acquisition of an Authority Token requires a network interface, 327 apart from potential use cases where the entity that acts as an ACME 328 client itself also acts as a Token Authority trusted by the ACME 329 server. Implementations compliant with this specification MUST 330 support an HTTPS REST interface for Authority Token acquisition as 331 described below, though other interfaces MAY be supported as well. 333 5.1. Basic REST Interface 335 In order to request an Authority Token from a Token Authority, a 336 client sends an HTTPS POST request. This specification assumes that 337 Token Authority URIs are known to clients through preexisting 338 business relationships, and that credentials and related 339 authentication and authorization for Authority Token acquisition 340 encompassed in that relationship. Different services may organize 341 their web resources in domain-specific ways, but the resource locator 342 should specify the account of the client, an identifier for the 343 service provider, and finally a locator for the token. 345 POST /at/account/:id/token HTTP/1.1 346 Host: authority.example.com 347 Content-Type: application/json 349 The body of the POST request MUST contain the Authority Token 350 Challenge element that the client is requesting the Token Authority 351 generate. In the way, the client proposes the scope of the Authority 352 Token it would like to receive from the Token Authority. 354 In common use cases, the "tkvalue" in this request is asking that the 355 Token Authority issue a token that attests the entire scope of 356 authority to which the client is entitled. The client may also 357 request an Authority Token with some subset of its own authority via 358 the "tkvalue" element in the Authority Token Challenge object. The 359 way that "tkvalue" is defined will necessarily be specific to the 360 identifier type. For the TNAuthlist identifier type, for example, an 361 object requesting an Authority Token could request authority for only 362 a single telephone number in a way that is defined in the TNAuthList 363 specification. 365 Finally, the JSON object MAY also contain an optional boolean element 366 "ca" which signifies that the client is requesting that the Token 367 Authority issue an Authority Token with the "ca" flag set, as 368 described in Section 4. 370 After an HTTPS-level challenge (e.g. a 401 HTTP response code) to 371 verify the identity of the client and subsequently making an 372 authorization decision about whether the client should receive an 373 Authority Token with the requested scope, then in the success case, 374 the Token Authority MUST return a 200 OK with a body of type 375 "application/json" containing the Authority Token. 377 A full example of "atc" token acquisition using the HTTP interface, 378 with the "tktype" of "TNAuthList", is given in 379 [I-D.ietf-acme-authority-token-tnauthlist] Section 5.5. 381 6. Acknowledgements 383 We would like to Roman Danyliw for contributions to this problem 384 statement and framework. 386 7. IANA Considerations 388 This document requests that IANA populate a new ACME Validation 389 Method (again per [RFC8555]) for the label "tkauth-01", identifier 390 type "atc", an ACME value of "Y", and a reference pointing to 391 [RFCThis]. 393 Furthermore, this document asks IANA to populate a new claim in the 394 "JSON Web Token Claims" registry as defined in [RFC7519] as follows: 396 Claim name: atc 398 Claim Description: Authority Token Challenge 400 Change Controller: IESG 402 Specification document(s): [RFCThis] 404 This document further requests that the IANA create a new registry 405 for "ACME Authority Token Challenge Types" as used in these 406 challenges, under a policy of Specification Required and following 407 the requirements in Section 3.1, with two columns, Label and 408 Reference. The registry should be pre-populated with a Label of 409 "atc" per Section 4 with a Reference value of [RFCThis]. 411 8. Security Considerations 413 Per the guidance in [RFC8555], ACME transactions MUST use TLS, and 414 similarly the HTTPS REST transactions used to request and acquire 415 Authority Tokens MUST use TLS. These measures are intended to 416 prevent the capture of Authority Tokens by eavesdroppers. The 417 security considerations of [RFC8555] apply to the use of the 418 mechanism in this specification. 420 As described in Section 3.2, an Authority Token can either have a 421 scope that attests all of the resources which a client is eligible to 422 receive certificates for, or potentially a more limited scope that is 423 intended to capture only those resources for which a client will 424 receive a certificate from a particular certification authority. Any 425 certification authority that sees an Authority Token can learn 426 information about the resources a client can claim. In cases where 427 this incurs a privacy risk, Authority Token scopes should be limited 428 to only the resources that will be attested by the requested ACME 429 certificate. 431 In cases where a tkauth-type as defined in Section 4 admits of its 432 own subtypes, the security of features like binding challenges (see 433 Section 3.3) will depend on the subtype specification. 435 The capture of Authority Tokens by an adversary could enable an 436 attacker to acquire a certificate from a CA. Therefore, all 437 Authority Tokens MUST contain a field that identifies to the CA which 438 ACME client requested the token from the Token Authority; here that 439 is the fingerprint specified in Section 4). All Authority Tokens 440 must specify an expiry (of the token itself as proof for a CA, as 441 opposed to the expiry of the name), and for some application, it may 442 make sense of that expiry to be quite short. Any protocol used to 443 retrieve Authority Tokens from a Token Authority MUST use 444 confidentiality to prevent eavesdroppers from acquiring an Authority 445 Token. 447 9. References 449 9.1. Normative References 451 [I-D.ietf-acme-authority-token-tnauthlist] 452 Wendt, C., Hancock, D., Barnes, M., and J. Peterson, 453 "TNAuthList profile of ACME Authority Token", draft-ietf- 454 acme-authority-token-tnauthlist-08 (work in progress), 455 March 2021. 457 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 458 Requirement Levels", BCP 14, RFC 2119, 459 DOI 10.17487/RFC2119, March 1997, 460 . 462 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 463 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 464 2015, . 466 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 467 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 468 . 470 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 471 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 472 May 2017, . 474 [RFC8396] Peterson, J. and T. McGarry, "Managing, Ordering, 475 Distributing, Exposing, and Registering Telephone Numbers 476 (MODERN): Problem Statement, Use Cases, and Framework", 477 RFC 8396, DOI 10.17487/RFC8396, July 2018, 478 . 480 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 481 Kasten, "Automatic Certificate Management Environment 482 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 483 . 485 9.2. Informative References 487 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 488 Credentials: Certificates", RFC 8226, 489 DOI 10.17487/RFC8226, February 2018, 490 . 492 Authors' Addresses 494 Jon Peterson 495 Neustar, Inc. 496 1800 Sutter St Suite 570 497 Concord, CA 94520 498 US 500 Email: jon.peterson@team.neustar 502 Mary Barnes 503 Independent 505 Email: mary.ietf.barnes@gmail.com 507 David Hancock 508 Comcast 510 Email: davidhancock.ietf@gmail.com 512 Chris Wendt 513 Comcast 514 One Comcast Center 515 Philadelphia, PA 19103 516 USA 518 Email: chris-ietf@chriswendt.net