idnits 2.17.1 draft-ietf-acme-authority-token-07.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 (October 25, 2021) is 914 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 425, but not defined == Outdated reference: A later version (-13) exists of draft-ietf-acme-authority-token-tnauthlist-08 Summary: 1 error (**), 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: April 28, 2022 Independent 6 D. Hancock 7 C. Wendt 8 Comcast 9 October 25, 2021 11 ACME Challenges Using an Authority Token 12 draft-ietf-acme-authority-token-07 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 April 28, 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 . . . . . . . . . . . . . . . . . . 5 63 3.3. Binding Challenges . . . . . . . . . . . . . . . . . . . 5 64 4. Authority Token Challenge tkauth-type Registration . . . . . 6 65 5. Acquiring a Token . . . . . . . . . . . . . . . . . . . . . . 8 66 5.1. Basic REST Interface . . . . . . . . . . . . . . . . . . 8 67 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 69 7.1. ACME Validation Method Registration . . . . . . . . . . . 9 70 7.2. JSON Web Token Claim Registration . . . . . . . . . . . . 9 71 7.3. Creation of ACME Authority Token Challenge Type Registry 9 72 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 73 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 75 9.2. Informative References . . . . . . . . . . . . . . . . . 11 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 78 1. Introduction 80 ACME [RFC8555] is a mechanism for automating certificate management 81 on the Internet. It enables administrative entities to prove 82 effective control over resources like domain names, and automates the 83 process of generating and issuing certificates that attest control or 84 ownership of those resources. 86 In some cases, proving effective control over an identifier requires 87 an attestation from a third party who has authority over the 88 resource, for example, an external policy administrator for a 89 namespace other than the DNS application ACME was originally designed 90 to support. In order to automate the process of issuing certificates 91 for those resources, this specification defines a generic Authority 92 Token challenge that ACME servers can issue in order to require 93 clients to return such a token. The challenge contains a type 94 indication that tells the client what sort of token it needs to 95 acquire. It is expected that the Authority Token challenge will be 96 usable for a variety of identifier types. In particular, this 97 document describes an architecture for Authority Tokens, defines a 98 the Authority Token format along with a protocol for token 99 acquisition, and shows how to integrate these tokens into an ACME 100 challenge. 102 For example, the system of [I-D.ietf-acme-authority-token-tnauthlist] 103 provides a mechanism that allows service providers to acquire 104 certificates corresponding to a Service Provider Code (SPC) as 105 defined in [RFC8226] by consulting an external authority responsible 106 for those codes. Furthermore, Communications Service Providers 107 (CSPs) can delegate authority over numbers to their customers, and 108 those CSPs who support ACME can then help customers to acquire 109 certificates for those numbering resources with ACME. This can 110 permit number acquisition flows compatible with those shown in 111 [RFC8396]. 113 2. Terminology 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 117 "OPTIONAL" in this document are to be interpreted as described in BCP 118 14 [RFC2119] [RFC8174] when, and only when, they appear in all 119 capitals, as shown here. 121 3. ACME Authority Token Challenge 123 Proving that a device on the Internet has effective control over a 124 non-Internet resource is not as straightforward as proving control 125 over an Internet resources like a DNS zone or a web page. Provided 126 that the issuer of identifiers in a namespace, or someone acting on 127 the issuer's behalf, can implement a service that grants Authority 128 Tokens to the people to whom it has issued identifiers, a generic 129 token could be used as a response to an ACME challenge. This 130 specification, therefore, defines an Authority Token issued by an 131 authority over a namespace to an ACME client for delivery to a CA in 132 response to a challenge. Authority over a hierarchical namespace can 133 also be delegated, so that delegates of a root authority can 134 themselves act as Token Authorities for certain types of names. 136 This architecture assumes a trust relationship between CAs and Token 137 Authorities: that CAs are willing to accept the attestation of Token 138 Authorities for particular types of identifiers as sufficient proof 139 to issue a credential. It furthermore assumes that ACME clients have 140 a relationship with Token Authorities which permits them to 141 authenticate and authorize the issuance of Authority Tokens to the 142 proper entities. This ACME challenge has no applicability to 143 identifiers or authorities where those pre-associations cannot be 144 assumed. 146 The ACME Authority Token Challenge type, "tkauth-01", is here 147 specified for use with the "TNAuthList" ACME Identifier Type 148 described in [I-D.ietf-acme-authority-token-tnauthlist]; in order to 149 use "tkauth-01" Validation Method with an ACME Identifier type other 150 than "TNAuthList," that identifier type would need to be registered 151 separately with IANA. "tkauth-01" furthermore supports different 152 token subtypes. The token subtype is determined by a new ACME 153 challenge field, tkauth-type. An IANA registry is used to manage the 154 values of tkauth-type, see Section 7.3. Additionally, this challenge 155 type also has a new "token-authority" field to designate a location 156 where a token can be acquired. 158 3.1. Token Type Requirements 160 The IANA will maintain a registry of tkauth-types under a policy of 161 Specification Required. In order to register a new tkauth-type, 162 specifications must address the following requirements; in cases 163 where a tkauth-type admits of its own subtypes, subtypes inherit 164 these requirements. 166 While Authority Token types do not need to be specific to a 167 namespace, every token must carry enough information for a CA to 168 determine the name that it will issue a certificate for. Some types 169 of Authority Token types might be reusable for a number of different 170 namespaces; other might be specific to a particular type of name. 171 Therefore, in defining tkauth-types, future specifications must 172 indicate how a token conveys to the CA the name(s) that the Token 173 Authority is attesting that the ACME client controls. 175 While nothing precludes use cases where an ACME client is itself a 176 Token Authority, an ACME client will typically need a protocol to 177 request and retrieve an Authority Token. The Token Authority will 178 require certain information from an ACME client in order to ascertain 179 that it is the right entity to request a certificate for a particular 180 name. The protocols used to request an Authority Token MUST convey 181 to the Token Authority the identifier type and value from or what 182 will be used in the ACME challenge, as well as the binding (see 183 Section 3.3), and those MUST be reflected in the Authority Token. A 184 baseline mechanism for how the Token Authority authenticates and 185 authorizes ACME clients to receive Authority Tokens is given in 186 Section 5. 188 Because the assignment of resources can change over time, 189 demonstrations of authority must be regularly refreshed. Definitions 190 of a tkauth-type MUST specify how they manage the freshness of 191 authority assignments. Typically, a CA will expect a regular 192 refreshing of the token. 194 3.2. Authority Token Scope 196 An Authority Token is used to answer a challenge from an ACME server, 197 upon a request for the issuance of a certificate. It could be that 198 the Authority Token is requested from the Token Authority after a 199 challenge has been received, or it could be that the Authority Token 200 was acquired prior to the initial ACME client request. A Token 201 Authority could grant to a client an Authority Token that has the 202 exact same scope as the requested certificate; alternatively, an 203 Authority Token could attest to all of the resources that the client 204 is eligible to receive certificates for, which could be a superset of 205 the scope of the requested certificate. 207 For example, imagine a case where an Authority for DNS names knows 208 that a client is eligible to receive certificates for "example.com" 209 and "example.net". The client asks an ACME server for a certificate 210 for "example.com", the server directs the client to acquire an 211 Authority Token from the Token Authority. When the client sends an 212 acquisition request (see Section 5) to the Token Authority, the Token 213 Authority could issue a token scoped just to "example.com", or a 214 token that attests the client is eligible to receive certificates for 215 both "example.com" or "example.net". The advantage of the latter is 216 that if, at a later time (but one within the expiry of the JWT), the 217 client wanted to acquire a certificate for "example.net", it would 218 not have to return to the Token Authority, as the Token effectively 219 pre-authorized the issuance of that certificate. 221 Applications of the Authority Token to different identifier types 222 might require different scopes, so registrations of tkauth-types 223 should be clear if and how a scope greater than that of the requested 224 certificate would be conveyed in a token. 226 3.3. Binding Challenges 228 Applications that use the Authority Token need a way to correlate 229 tokens issued by a Token Authority with the proper ACME client, to 230 prevent replay or cut-and-paste attacks using a token issued for a 231 different purpose. To mitigate this, Authority Tokens contain a 232 binding signed by a Token Authority; an ACME server can use the 233 binding to determine that a Token presented by a client was in fact 234 granted by the Token Authority based on a request from the client, 235 and not from some other entity. 237 Creating a binding from an Authority Token to a particular ACME 238 account entails that the Token could be reused up until its expiry 239 for multiple challenges issued by an ACME server. This might be a 240 desirable property when using short-lived certificates, for example, 241 or in any cases where the ACME server issues challenges more 242 frequently that an Authority Token can or should issue tokens, or in 243 cases where the Authority Token scope (see Section 3.2) is broad, so 244 certificates with a more narrow scope may periodically be issued. 246 For some identifier types, it may be more appropriate to bind the 247 Authority Token to a nonce specific to the challenge rather than to 248 an ACME account fingerprint. Any specification of the use of the 249 nonce for this purpose is left to the identifier type profile for the 250 Authority Token. 252 4. Authority Token Challenge tkauth-type Registration 254 This draft specifies a tkauth-type of "atc" which contains a standard 255 JWT token [RFC7519] using a JWS-defined signature string [RFC7515]. 256 The "atc" tkauth-type MAY be used for any number of different ACME 257 identifier types in the ACME challenge. 259 A new JWT claim, "atc", is defined below and lists the identifier 260 type used in this Authority Token. The "atc" tkauth-type is 261 restricted to the JWTs; if a non-JWT token format is desired for the 262 ACME Authority Token Challenge, a different tkauth-type should be 263 specified and registered in the "ACME Authority Token Challenge 264 Types" registry defined in Section 8. 266 For this ACME Authority Token usage of JWT, the payload of the JWT 267 OPTIONALLY contain an "iss" indicating the Token Authority that 268 generated the token, if the "x5u" element in the header does not 269 already convey that information; typically, this will be the same 270 location that appeared in the "token-authority" field of the ACME 271 challenge. In order to satisfy the requirement for replay prevention 272 the JWT MUST contain a "jti" element, and an "exp" claim; the "exp" 273 claim manages token freshness. In addition to helping to manage 274 replay, the "jti" provides a convenient way to reliably track with 275 the same "atc" Authority Token is being used for multiple challenges 276 over time within its set expiry. 278 The JWT payload MUST also contain a new JWT claim, "atc", for 279 Authority Token Challenge, which contains three mandatory elements in 280 an array: the ATC identifier type ("tktype"), the identifier value 281 ("tkvalue"), and the binding ("fingerprint"). The use of "tktype" is 282 restricted to the values in the "ACME Identifier Types" registry as 283 defined by [RFC8555]. The "tkvalue" indicates the scope of the 284 authority that the token, and its semantics are outside the scope of 285 this document. The identifier type and value are those given in the 286 ACME challenge and conveyed to the Token Authority by the ACME 287 client. 289 Following the example of [I-D.ietf-acme-authority-token-tnauthlist], 290 the "tkvalue" identifier type could be the TNAuthList, with a 291 "tkvalue" as defined in [RFC8226] that the Token Authority is 292 attesting. Practically speaking, that scope may comprise a list of 293 Service Provider Code elements, telephone number range elements, and/ 294 or individual telephone numbers. For the purposes of the "atc" 295 tkauth-type, the binding "fingerprint" is assumed to be a fingerprint 296 of the ACME credential for the account used to request the 297 certificate, but the specification of how the binding is generated is 298 left to the identifier type profile for the Authority Token. So for 299 example: 301 { 302 "protected": base64url({ 303 "typ":"JWT", 304 "alg":"ES256", 305 "x5u":"https://authority.example.org/cert" 306 }), 307 "payload": base64url({ 308 "iss":"https://authority.example.org/authz", 309 "exp":1300819380, 310 "jti":"id6098364921", 311 "atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==","fingerprint": 312 "SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:BA:B9:19:81:F8:50: 313 9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} 314 }), 315 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 316 } 318 Optionally, the "atc" claim may contain a fourth element, "ca". If 319 set to "true", the "ca" element indicates that the Token Authority is 320 granting permission to issue a certification authority certificate 321 rather than an end-entity certificate for the names in question. 322 This permits subordinate delegations from the issued certificate. If 323 the "ca" element is absent, the Token Authority is explicitly 324 withholding permission. The "atc" object in the example above would 325 then look like: 327 "atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==","ca":true, 328 "fingerprint":"SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:BA:B9:19:81:F8:50: 329 9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} } 331 Specifications of "tktype" identifier types may define additional 332 optional "atc" elements. 334 5. Acquiring a Token 336 The acquisition of an Authority Token requires a network interface, 337 apart from potential use cases where the entity that acts as an ACME 338 client itself also acts as a Token Authority trusted by the ACME 339 server. Implementations compliant with this specification MUST 340 support an HTTPS REST interface for Authority Token acquisition as 341 described below, though other interfaces MAY be supported as well. 343 5.1. Basic REST Interface 345 In order to request an Authority Token from a Token Authority, a 346 client sends an HTTPS POST request. This specification assumes that 347 Token Authority URIs are known to clients through preexisting 348 business relationships, and that credentials and related 349 authentication and authorization for Authority Token acquisition 350 encompassed in that relationship. Different services may organize 351 their web resources in domain-specific ways, but the resource locator 352 should specify the account of the client, an identifier for the 353 service provider, and finally a locator for the token. 355 POST /at/account/:id/token HTTP/1.1 356 Host: authority.example.com 357 Content-Type: application/json 359 The body of the POST request MUST contain the Authority Token 360 Challenge element that the client is requesting the Token Authority 361 generate. In the way, the client proposes the scope of the Authority 362 Token it would like to receive from the Token Authority. 364 In common use cases, the "tkvalue" in this request is asking that the 365 Token Authority issue a token that attests the entire scope of 366 authority to which the client is entitled. The client may also 367 request an Authority Token with some subset of its own authority via 368 the "tkvalue" element in the Authority Token Challenge object. The 369 way that "tkvalue" is defined will necessarily be specific to the 370 identifier type. For the TNAuthlist identifier type, for example, an 371 object requesting an Authority Token could request authority for only 372 a single telephone number in a way that is defined in the TNAuthList 373 specification. 375 Finally, the JSON object MAY also contain an optional boolean element 376 "ca" which signifies that the client is requesting that the Token 377 Authority issue an Authority Token with the "ca" flag set, as 378 described in Section 4. 380 After an HTTPS-level challenge (e.g. a 401 HTTP response code) to 381 verify the identity of the client and subsequently making an 382 authorization decision about whether the client should receive an 383 Authority Token with the requested scope, then in the success case, 384 the Token Authority MUST return a 200 OK with a body of type 385 "application/json" containing the Authority Token. 387 A full example of "atc" token acquisition using the HTTP interface, 388 with the "tktype" of "TNAuthList", is given in 389 [I-D.ietf-acme-authority-token-tnauthlist] Section 5.5. 391 6. Acknowledgements 393 We would like to Roman Danyliw for contributions to this problem 394 statement and framework. 396 7. IANA Considerations 398 7.1. ACME Validation Method Registration 400 This document requests that IANA populate a new ACME Validation 401 Method (again per [RFC8555]) for the label "tkauth-01", identifier 402 type "TNAuthList", an ACME value of "Y", and a reference pointing to 403 [RFCThis]. 405 7.2. JSON Web Token Claim Registration 407 This document asks IANA to populate a new claim in the "JSON Web 408 Token Claims" registry as defined in [RFC7519] as follows: 410 Claim name: atc 412 Claim Description: Authority Token Challenge 414 Change Controller: IESG 416 Specification document(s): [RFCThis] 418 7.3. Creation of ACME Authority Token Challenge Type Registry 420 This document requests that the IANA create a new registry for "ACME 421 Authority Token Challenge Types" as used in these challenges, under a 422 policy of Specification Required and following the requirements in 423 Section 3.1, with two columns, Label and Reference. The registry 424 should be pre-populated with a Label of "atc" per Section 4 with a 425 Reference value of [RFCThis]. 427 8. Security Considerations 429 Per the guidance in [RFC8555], ACME transactions MUST use TLS, and 430 similarly the HTTPS REST transactions used to request and acquire 431 Authority Tokens MUST use TLS. These measures are intended to 432 prevent the capture of Authority Tokens by eavesdroppers. The 433 security considerations of [RFC8555] apply to the use of the 434 mechanism in this specification. 436 As described in Section 3.2, an Authority Token can either have a 437 scope that attests all of the resources which a client is eligible to 438 receive certificates for, or potentially a more limited scope that is 439 intended to capture only those resources for which a client will 440 receive a certificate from a particular certification authority. Any 441 certification authority that sees an Authority Token can learn 442 information about the resources a client can claim. In cases where 443 this incurs a privacy risk, Authority Token scopes should be limited 444 to only the resources that will be attested by the requested ACME 445 certificate. 447 In cases where a tkauth-type as defined in Section 4 admits of its 448 own subtypes, the security of features like binding challenges (see 449 Section 3.3) will depend on the subtype specification. 451 The capture of Authority Tokens by an adversary could enable an 452 attacker to acquire a certificate from a CA. Therefore, all 453 Authority Tokens MUST contain a field that identifies to the CA which 454 ACME client requested the token from the Token Authority; here that 455 is the fingerprint specified in Section 4). All Authority Tokens 456 must specify an expiry (of the token itself as proof for a CA, as 457 opposed to the expiry of the name), and for some application, it may 458 make sense of that expiry to be quite short. Any protocol used to 459 retrieve Authority Tokens from a Token Authority MUST use 460 confidentiality to prevent eavesdroppers from acquiring an Authority 461 Token. 463 9. References 465 9.1. Normative References 467 [I-D.ietf-acme-authority-token-tnauthlist] 468 Wendt, C., Hancock, D., Barnes, M., and J. Peterson, 469 "TNAuthList profile of ACME Authority Token", draft-ietf- 470 acme-authority-token-tnauthlist-08 (work in progress), 471 March 2021. 473 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 474 Requirement Levels", BCP 14, RFC 2119, 475 DOI 10.17487/RFC2119, March 1997, 476 . 478 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 479 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 480 2015, . 482 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 483 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 484 . 486 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 487 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 488 May 2017, . 490 [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 491 Kasten, "Automatic Certificate Management Environment 492 (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, 493 . 495 9.2. Informative References 497 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 498 Credentials: Certificates", RFC 8226, 499 DOI 10.17487/RFC8226, February 2018, 500 . 502 [RFC8396] Peterson, J. and T. McGarry, "Managing, Ordering, 503 Distributing, Exposing, and Registering Telephone Numbers 504 (MODERN): Problem Statement, Use Cases, and Framework", 505 RFC 8396, DOI 10.17487/RFC8396, July 2018, 506 . 508 Authors' Addresses 510 Jon Peterson 511 Neustar, Inc. 512 1800 Sutter St Suite 570 513 Concord, CA 94520 514 US 516 Email: jon.peterson@team.neustar 517 Mary Barnes 518 Independent 520 Email: mary.ietf.barnes@gmail.com 522 David Hancock 523 Comcast 525 Email: davidhancock.ietf@gmail.com 527 Chris Wendt 528 Comcast 529 One Comcast Center 530 Philadelphia, PA 19103 531 USA 533 Email: chris-ietf@chriswendt.net