idnits 2.17.1 draft-ietf-acme-authority-token-tnauthlist-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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 16 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 (March 11, 2019) is 1863 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) == Unused Reference: 'ATIS-1000074' is defined on line 539, but no explicit reference was found in the text == Outdated reference: A later version (-09) exists of draft-ietf-acme-authority-token-02 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Downref: Normative reference to an Informational RFC: RFC 7340 Summary: 4 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 C. Wendt 3 Internet-Draft D. Hancock 4 Intended status: Standards Track Comcast 5 Expires: September 12, 2019 M. Barnes 6 iconectiv 7 J. Peterson 8 Neustar Inc. 9 March 11, 2019 11 TNAuthList profile of ACME Authority Token 12 draft-ietf-acme-authority-token-tnauthlist-02 14 Abstract 16 This document defines a profile of the Automated Certificate 17 Management Environment (ACME) Authority Token for the automated and 18 authorized creation of certificates for VoIP Telephone Providers to 19 support Secure Telephony Identity (STI) using the TNAuthList defined 20 by STI certificates. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on September 12, 2019. 39 Copyright Notice 41 Copyright (c) 2019 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. ACME new-order identifiers for TNAuthList . . . . . . . . . . 3 59 4. TNAuthList Identifier Authorization . . . . . . . . . . . . . 5 60 5. TNAuthList Authority Token . . . . . . . . . . . . . . . . . 7 61 5.1. "iss" claim . . . . . . . . . . . . . . . . . . . . . . . 7 62 5.2. "exp" claim . . . . . . . . . . . . . . . . . . . . . . . 7 63 5.3. "jti" claim . . . . . . . . . . . . . . . . . . . . . . . 8 64 5.4. "atc" claim . . . . . . . . . . . . . . . . . . . . . . . 8 65 5.5. Acquiring the token from the Token Authority . . . . . . 9 66 5.6. Token Authority Responsibilities . . . . . . . . . . . . 10 67 6. Validating the TNAuthList Authority Token . . . . . . . . . . 10 68 7. Usage Considerations . . . . . . . . . . . . . . . . . . . . 10 69 7.1. Large number of Non-contiguous TNAuthList values . . . . 10 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 72 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 73 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 74 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 75 11.2. Informative References . . . . . . . . . . . . . . . . . 12 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 78 1. Introduction 80 [I-D.ietf-acme-acme] is a mechanism for automating certificate 81 management on the Internet. It enables administrative entities to 82 prove effective control over resources like domain names, and 83 automates the process of generating and issuing certificates. 84 [I-D.ietf-acme-authority-token] extends ACME to provide a general 85 method of extending the authority and authorization of entities to 86 control a resource via a third party Token Authority beyond the 87 Certification Authority. 89 This document addresses the STIR problem statement [RFC7340] which 90 identifies the need for Internet credentials that can attest 91 authority for the originator of VoIP calls in order to detect 92 impersonation, which is currently an enabler for common attacks 93 associated with illegal robocalling, voicemail hacking, and swatting. 94 These credentials are used to sign PASSporTs [RFC8225], which can be 95 carried in using protocols such as SIP [RFC8224]. Currently, the 96 only defined credentials for this purpose are the certificates 97 specified in [RFC8226]. 99 [RFC8226] describes certificate extensions suitable for associating 100 telephone numbers and service provider codes with certificates. 101 Specifically, the TN Authorization List defined in [RFC8226] 102 Section 9, defines the ability to associate a STI certificate with a 103 specific set of Service Provider Codes (SPCs), Telephone Numbers 104 (TNs), or Telephone Number ranges (TN ranges). Typically, these 105 identifiers have been assigned to a Communications Service Provider 106 (CSP) that is authorized to use a set of telephone numbers or 107 telephone number ranges in association with a Service Provider Code 108 as defined in [RFC8226]. The SPC is a unique code or string managed 109 by a national regulatory body that has the authority over those code- 110 to-CSP associations. 112 This document will also incorporate the ability for a telephone 113 authority to authorize the creation of CA types of certificates for 114 delegation as defined in [I-D.peterson-stir-cert-delegation]. 116 2. Terminology 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 document are to be interpreted as described in [RFC2119]. 122 3. ACME new-order identifiers for TNAuthList 124 In [I-D.ietf-acme-acme], Section 7.4 defines the procedure that an 125 ACME client uses to order a new certificate from a Certification 126 Authority. The new-order request contains an identifier field that 127 specifies the identifier objects the order corresponds to. This 128 draft defines a new type of identifier object called TNAuthList. A 129 TNAuthList identifier contains the identity information to be 130 populated in the TN Authorization List of the new certificate. For 131 the TNAuthList identifier, the new-order request MUST include a type 132 set to the string "TNAuthList". The value of the TNAuthList 133 identifier MUST be set to the details of the TNAuthList requested. 135 The format of the string that represents the TNAuthList MUST be 136 constructed as a base64 [RFC4648] encoding of the TN Authorization 137 List certificate extension ASN.1 object. The TN Authorization List 138 certificate extension ASN.1 syntax is defined in [RFC8226] section 9. 140 An example of an ACME order object "identifiers" field containing a 141 TNAuthList certificate would look as follows, 143 "identifiers": [{"type":"TNAuthList","value":"F83n2a...avn27DN3=="}] 145 where the "value" object string represents the arbitrary length 146 base64 encoded string. 148 A full new-order request would look as follows, 150 POST /acme/new-order HTTP/1.1 151 Host: example.com 152 Content-Type: application/jose+json 154 { 155 "protected": base64url({ 156 "alg": "ES256", 157 "kid": "https://example.com/acme/acct/1", 158 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 159 "url": "https://example.com/acme/new-order" 160 }), 161 "payload": base64url({ 162 "identifiers": [{"type:"TNAuthList","value":"F83n2a...avn27DN3=="}], 163 "notBefore": "2016-01-01T00:00:00Z", 164 "notAfter": "2016-01-08T00:00:00Z" 165 }), 166 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 167 } 169 On receiving a valid new-order request, the CA creates an 170 authorization object containing the challenge that the ACME client 171 must satisfy to demonstrate authority for the identifiers specified 172 by the new order (in this case, the TNAuthList identifier). The CA 173 adds the authorization object URL to the "authorizations" field of 174 the order object, and returns the order object to the ACME client in 175 the body of a 201 (Created) response. 177 HTTP/1.1 201 Created 178 Replay-Nonce: MYAuvOpaoIiywTezizk5vw 179 Location: https://example.com/acme/order/1234 181 { 182 "status": "pending", 183 "expires": "2015-03-01T14:09:00Z", 185 "notBefore": "2016-01-01T00:00:00Z", 186 "notAfter": "2016-01-08T00:00:00Z", 187 "identifiers":[{"type:"TNAuthList", 188 "value":"F83n2a...avn27DN3=="}], 190 "authorizations": [ 191 "https://example.com/acme/authz/1234" 192 ], 193 "finalize": "https://example.com/acme/order/1234/finalize" 194 } 196 4. TNAuthList Identifier Authorization 198 On receiving the new-order response, the ACME client queries the 199 referenced authorization object to obtain the challenges for the 200 identifier contained in the new-order request as shown in the 201 following example request and response. 203 POST /acme/authz/1234 HTTP/1.1 204 Host: example.com 205 Content-Type: application/jose+json 207 { 208 "protected": base64url({ 209 "alg": "ES256", 210 "kid": " https://example.com/acme/acct/1", 211 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 212 "url": "https://example.com/acme/authz/1234", 213 }), 214 "payload": "", 215 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 216 } 218 HTTP/1.1 200 OK 219 Content-Type: application/json 220 Link: ;rel="index" 222 { 223 "status": "pending", 224 "expires": "2018-03-03T14:09:00Z", 226 "identifier": { 227 "type:"TNAuthList", 228 "value":"F83n2a...avn27DN3==" 229 }, 231 "challenges": [ 232 { 233 "type": "tkauth-01", 234 "tkauth-type": "ATC", 235 "token-authority": "https://authority.example.org/authz", 236 "url": "https://boulder.example.com/authz/asdf/0" 237 "token": "IlirfxKKXAsHtmzK29Pj8A" 238 } 239 ] 240 } 242 When processing a certificate order containing an identifier of type 243 "TNAuthList", a CA MUST use the Authority Token challenge mechanism 244 defined in [I-D.ietf-acme-authority-token] to verify that the 245 requesting ACME client has authenticated and authorized control over 246 the requested resources represented by the "TNAuthList" value. 248 The challenge "token-authority" parameter is optional and only used 249 in cases where the VoIP telephone network requires the CA to identify 250 the Token Authority. This is currently not the case for the SHAKEN 251 [ATIS-1000080] certificate framework governance, but may be used by 252 other frameworks. If a "token-authority" parameter is present, then 253 the ACME client MAY use the "token-authority" value to identify the 254 URL representing the Token Authority that will provide the TNAuthList 255 Authority Token response to the challenge. If the "token-authority" 256 parameter is not present, then the ACME client MUST identify the 257 Token Authority based on locally configured information or local 258 policies. 260 The ACME client MUST respond to the challenge by posting the 261 TNAuthList Authority Token to the challenge URL identified in the 262 returned ACME authorization object, an example of which follows. 264 POST /acme/authz/asdf/0 HTTP/1.1 265 Host: boulder.example.com 266 Content-Type: application/jose+json 268 { 269 "protected": base64url({ 270 "alg": "ES256", 271 "kid": "https://example.com/acme/acct/1", 272 "nonce": "Q_s3MWoqT05TrdkM2MTDcw", 273 "url": "https://boulder.example.com/acme/authz/asdf/0" 274 }), 275 "payload": base64url({ 276 "ATC": "DGyRejmCefe7v4N...vb29HhjjLPSggwiE" 277 }), 278 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 279 } 281 The specifics of the construction of the TNAuthList specific "ATC" 282 token is defined in the next section. 284 5. TNAuthList Authority Token 286 The Telephone Number Authority List Authority Token (TNAuthList 287 Authority Token) is an extension of the ACME Authority Token defined 288 in [I-D.ietf-acme-authority-token]. 290 The TNAuthList Authority Token Protected header MUST comply with the 291 Authority Token Protected header as defined in 292 [I-D.ietf-acme-authority-token]. 294 The TNAuthList Authority Token Payload MUST include the mandatory 295 claims and MAY include the optional claims defined for the Authority 296 Token detailed in the next subsections. 298 5.1. "iss" claim 300 The "iss" claim is an optional claim. It can be used as a URL 301 identifying the Token Authority that issued the TNAuthList Authority 302 Token beyond the "x5u" Header claim that identifies the location of 303 the certificate of the Token Authority used to validate the 304 TNAuthList Authority Token. 306 5.2. "exp" claim 308 The "exp" claim contains the DateTime value of the ending date and 309 time that the TNAuthList Authority Token expires. 311 5.3. "jti" claim 313 The "jti" claim contains a unique identifier for this TNAuthList 314 Authority Token transaction. 316 5.4. "atc" claim 318 The "atc" claim is the only claim specifically defined in this 319 document. It contains a JSON object of three elements. 321 o a "TNAuthList" key with a string value equal to the TNAuthList 322 identifier "value" string which MUST contain the base64 encoding 323 of the TN Authorization List certificate extension ASN.1 object. 325 o a "ca" key with a boolean value set to either true when the 326 requested certificate is allowed to be a CA cert for delegation 327 uses or false when the requested certificate MUST NOT be a CA cert 328 and only an end-entity certificate 330 o a "fingerprint" key with a fingerprint value equal to the 331 fingerprint, as defined in [RFC4949], of the ACME account 332 credentials. Specifically, the fingerprint value is a secure one- 333 way hash of the Distinguished Encoding Rules (DER) form of the 334 public key corresponding to the key pair the SP used to create the 335 account with the ACME server. The fingerprint value consists of 336 the name of the hash function, which shall be 'SHA256' for this 337 specification, followed by the hash value itself. The hash value 338 is represented as a sequence of uppercase hexadecimal bytes, 339 separated by colons. The number of bytes is defined by the hash 340 function. 342 An example of the TNAuthList Authority Token is as follows, 344 { "typ":"JWT", 345 "alg":"ES256", 346 "x5u":https://authority.example.org/cert 347 } 349 { 350 "iss":"https://authority.example.org/authz", 351 "exp":1300819380, 352 "jti":"id6098364921", 353 "atc":{"TnAuthList","F83n2a...avn27DN3==", 354 "ca":false, 355 "fingerprint":"SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:BA:B9:19:81:F8:50: 356 9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} 357 } 359 5.5. Acquiring the token from the Token Authority 361 Following [I-D.ietf-acme-authority-token] Section 5, the authority 362 token should be acquired using a RESTful HTTP POST transaction as 363 follows 365 POST /at/account/:id/token HTTP/1.1 366 Host: authority.example.com 367 Content-Type: application/json 369 The request will pass the account id as a string in the request 370 parameter "id". This string will be managed as an identifier 371 specific to the authorities relationship with a CSP. There is 372 assumed to also be a corresponding authentication procedure that can 373 be verified for the success of this transaction. For example, an 374 HTTP authorization header containing a valid authorization 375 credentials as defined in [RFC2616] Section 14.8. 377 The body of the POST request MUST contain the "atc" JSON object that 378 should be embedded in the token that is requested, for example the 379 body should contain a JSON object as shown: 381 { 382 "atc":{"TNAuthList":"F83n2a...avn27DN3==", 383 "ca":false, 384 "fingerprint":"SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3 \ 385 :BA:B9:19:81:F8:50:9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} 386 } 388 The response to the POST request if successful MUST return a 200 OK 389 with a JSON body that contains the TNAuthList Authority Token as a 390 JSON object with a single key of "ATC" and the base64 encoded string 391 representing the ATC token. 393 An example successful response would be as follows: 395 HTTP/1.1 200 OK 396 Content-Type: application/json 398 {"ATC": "DGyRejmCefe7v4N...vb29HhjjLPSggwiE"} 400 If the request is not successful, the response should indicate the 401 error condition. Specifically, for the case that the authorization 402 credentials are invalid, the response code MUST be 403 - Forbidden. 403 If the Account ID provided does not exist or does not match 404 credentials in Authorization header, the response MUST be 404 - 405 Invalid account ID. Other 4xx and 5xx responses SHOULD follow 406 standard [RFC2616] HTTP error condition conventions. 408 5.6. Token Authority Responsibilities 410 When the Token Authority creates the TnAuthList Authority Token, it 411 is the responsibility of the Token Authority to validate that the 412 information contained in the ASN.1 TNAuthList accurately represents 413 the SPC or telephone number resources the ACME client is authorized 414 to represent. 416 6. Validating the TNAuthList Authority Token 418 Upon receiving a response to the challenge, the ACME server MUST 419 perform the following steps to determine the validity of the 420 response. 422 o Verify that the token contained in the Payload "ATC" field is an 423 TNAuthList Authority Token. 425 o Verify the TNAuthList Authority Token signature using the public 426 key of the certificate referenced by the token's "x5u" parameter. 428 o Verify that "atc" claim contains an identifier type of 429 "TNAuthList", 431 o Verify that the "atc" claim contains the equivalent base64 encoded 432 TNAuthList certificate extension string value as the Identifier 433 specified in the original challenge. 435 o Verify that the remaining claims are valid (e.g., verify that 436 token has not expired) 438 o Verify that the "atc" claim "fingerprint" is valid 440 o Verify that the "ca" claim boolean corresponds to the CSR request 441 for either CA certificate or end-entity certificate 443 If all steps in the token validation process pass, then the CA MUST 444 set the challenge object "status" to "valid". If any step of the 445 validation process fails, the "status" in the challenge object MUST 446 be set to "invalid". 448 7. Usage Considerations 450 7.1. Large number of Non-contiguous TNAuthList values 452 There are many scenarios and reasons to have various combinations of 453 SPCs, TNs, and TN Ranges. [RFC8226] has provided a somewhat 454 unbounded set of combinations. It's possible that a complex non- 455 contiguous set of telephone numbers are being managed by a CSP. Best 456 practice may be simply to split a set of non-contiguous numbers under 457 management into multiple STI certificates to represent the various 458 contiguous parts of the greater non-contiguous set of TNs, 459 particularly if length of the set of values in identifier object 460 grows to be too large. 462 8. Security Considerations 464 TBD 466 9. IANA Considerations 468 This document requests the addition of a new identifier object type 469 that can be present in the identifier field of the ACME authorization 470 object defined in [I-D.ietf-acme-acme]. 472 +------------+-----------+ 473 | Label | Reference | 474 +------------+-----------+ 475 | TNAuthList | RFCThis | 476 +------------+-----------+ 478 10. Acknowledgements 480 We would like to thank Richard Barnes and Russ Housley for valuable 481 contributions to this document. 483 11. References 485 11.1. Normative References 487 [I-D.ietf-acme-acme] 488 Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 489 Kasten, "Automatic Certificate Management Environment 490 (ACME)", draft-ietf-acme-acme-18 (work in progress), 491 December 2018. 493 [I-D.ietf-acme-authority-token] 494 Peterson, J., Barnes, M., Hancock, D., and C. Wendt, "ACME 495 Challenges Using an Authority Token", draft-ietf-acme- 496 authority-token-02 (work in progress), March 2019. 498 [I-D.peterson-stir-cert-delegation] 499 Peterson, J., "STIR Certificate Delegation", draft- 500 peterson-stir-cert-delegation-00 (work in progress), March 501 2019. 503 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 504 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 505 Transfer Protocol -- HTTP/1.1", RFC 2616, 506 DOI 10.17487/RFC2616, June 1999, 507 . 509 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 510 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 511 . 513 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 514 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 515 . 517 [RFC7340] Peterson, J., Schulzrinne, H., and H. Tschofenig, "Secure 518 Telephone Identity Problem Statement and Requirements", 519 RFC 7340, DOI 10.17487/RFC7340, September 2014, 520 . 522 [RFC8224] Peterson, J., Jennings, C., Rescorla, E., and C. Wendt, 523 "Authenticated Identity Management in the Session 524 Initiation Protocol (SIP)", RFC 8224, 525 DOI 10.17487/RFC8224, February 2018, 526 . 528 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 529 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 530 . 532 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 533 Credentials: Certificates", RFC 8226, 534 DOI 10.17487/RFC8226, February 2018, 535 . 537 11.2. Informative References 539 [ATIS-1000074] 540 ATIS/SIP Forum NNI Task Group, "Signature-based Handling 541 of Asserted information using toKENs (SHAKEN) 542 ", January 2017. 545 [ATIS-1000080] 546 ATIS/SIP Forum NNI Task Group, "Signature-based Handling 547 of Asserted information using toKENs (SHAKEN) Governance 548 Model and Certificate Management 549 ", July 2017. 552 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 553 Requirement Levels", BCP 14, RFC 2119, 554 DOI 10.17487/RFC2119, March 1997, 555 . 557 Authors' Addresses 559 Chris Wendt 560 Comcast 561 One Comcast Center 562 Philadelphia, PA 19103 563 USA 565 Email: chris-ietf@chriswendt.net 567 David Hancock 568 Comcast 570 Email: davidhancock.ietf@gmail.com 572 Mary Barnes 573 iconectiv 575 Email: mary.ietf.barnes@gmail.com 577 Jon Peterson 578 Neustar Inc. 579 1800 Sutter St Suite 570 580 Concord, CA 94520 581 US 583 Email: jon.peterson@neustar.biz