idnits 2.17.1 draft-ietf-acme-authority-token-tnauthlist-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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 2 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 22, 2018) is 2013 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 471, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-acme-acme-16 == Outdated reference: A later version (-09) exists of draft-ietf-acme-authority-token-00 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Downref: Normative reference to an Informational RFC: RFC 7340 Summary: 3 errors (**), 0 flaws (~~), 4 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: April 25, 2019 M. Barnes 6 iconectiv 7 J. Peterson 8 Neustar Inc. 9 October 22, 2018 11 TNAuthList profile of ACME Authority Token 12 draft-ietf-acme-authority-token-tnauthlist-01 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 April 25, 2019. 39 Copyright Notice 41 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . 6 61 5.1. "iss" claim . . . . . . . . . . . . . . . . . . . . . . . 7 62 5.2. "exp" claim . . . . . . . . . . . . . . . . . . . . . . . 7 63 5.3. "jti" claim . . . . . . . . . . . . . . . . . . . . . . . 7 64 5.4. "atc" claim . . . . . . . . . . . . . . . . . . . . . . . 7 65 5.5. Acquiring the token from the Token Authority . . . . . . 8 66 5.6. Token Authority Responsibilities . . . . . . . . . . . . 8 67 6. Validating the TNAuthList Authority Token . . . . . . . . . . 8 68 7. Usage Considerations . . . . . . . . . . . . . . . . . . . . 9 69 7.1. Large number of Non-contiguous TNAuthList values . . . . 9 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 72 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 73 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 11.1. Normative References . . . . . . . . . . . . . . . . . . 10 75 11.2. Informative References . . . . . . . . . . . . . . . . . 11 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 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 2. Terminology 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 116 document are to be interpreted as described in [RFC2119]. 118 3. ACME new-order identifiers for TNAuthList 120 In [I-D.ietf-acme-acme], Section 7.4 defines the procedure that an 121 ACME client uses to order a new certificate from a Certification 122 Authority. The new-order request contains an identifier field that 123 specifies the identifier objects the order corresponds to. This 124 draft defines a new type of identifier object called TNAuthList. A 125 TNAuthList identifier contains the identity information to be 126 populated in the TN Authorization List of the new certificate. For 127 the TNAuthList identifier, the new-order request MUST include a type 128 set to the string "TNAuthList". The value of the TNAuthList 129 identifier MUST be set to the details of the TNAuthList requested. 131 The format of the string that represents the TNAuthList MUST be 132 constructed as a base64 [RFC4648] encoding of the TN Authorization 133 List certificate extension ASN.1 object. The TN Authorization List 134 certificate extension ASN.1 syntax is defined in [RFC8226] section 9. 136 An example of an ACME order object "identifiers" field containing a 137 TNAuthList certificate would look as follows, 139 "identifiers": [{"type":"TNAuthList","value":"F83n2a...avn27DN3=="}] 141 where the "value" object string represents the arbitrary length 142 base64 encoded string. 144 A full new-order request would look as follows, 146 POST /acme/new-order HTTP/1.1 147 Host: example.com 148 Content-Type: application/jose+json 150 { 151 "protected": base64url({ 152 "alg": "ES256", 153 "kid": "https://example.com/acme/acct/1", 154 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 155 "url": "https://example.com/acme/new-order" 156 }), 157 "payload": base64url({ 158 "identifiers": [{"type:"TNAuthList","value":"F83n2a...avn27DN3=="}], 159 "notBefore": "2016-01-01T00:00:00Z", 160 "notAfter": "2016-01-08T00:00:00Z" 161 }), 162 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 163 } 165 On receiving a valid new-order request, the CA creates an 166 authorization object containing the challenge that the ACME client 167 must satisfy to demonstrate authority for the identifiers specified 168 by the new order (in this case, the TNAuthList identifier). The CA 169 adds the authorization object URL to the "authorizations" field of 170 the order object, and returns the order object to the ACME client in 171 the body of a 201 (Created) response. 173 HTTP/1.1 201 Created 174 Replay-Nonce: MYAuvOpaoIiywTezizk5vw 175 Location: https://example.com/acme/order/1234 177 { 178 "status": "pending", 179 "expires": "2015-03-01T14:09:00Z", 181 "notBefore": "2016-01-01T00:00:00Z", 182 "notAfter": "2016-01-08T00:00:00Z", 183 "identifiers":[{"type:"TNAuthList", 184 "value":"F83n2a...avn27DN3=="}], 186 "authorizations": [ 187 "https://example.com/acme/authz/1234" 188 ], 189 "finalize": "https://example.com/acme/order/1234/finalize" 190 } 192 4. TNAuthList Identifier Authorization 194 On receiving the new-order response, the ACME client queries the 195 referenced authorization object to obtain the challenges for the 196 identifier contained in the new-order request as shown in the 197 following example request and response. 199 POST /acme/authz/1234 HTTP/1.1 200 Host: example.com 201 Content-Type: application/jose+json 203 { 204 "protected": base64url({ 205 "alg": "ES256", 206 "kid": " https://example.com/acme/acct/1", 207 "nonce": "uQpSjlRb4vQVCjVYAyyUWg", 208 "url": "https://example.com/acme/authz/1234", 209 }), 210 "payload": "", 211 "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps" 212 } 214 HTTP/1.1 200 OK 215 Content-Type: application/json 216 Link: ;rel="index" 218 { 219 "status": "pending", 220 "expires": "2018-03-03T14:09:00Z", 222 "identifier": { 223 "type:"TNAuthList", 224 "value":"F83n2a...avn27DN3==" 225 }, 227 "challenges": [ 228 { 229 "type": "tkauth-01", 230 "tkauth-type": "ATC", 231 "token-authority": "https://authority.example.org/authz", 232 "url": "https://boulder.example.com/authz/asdf/0" 233 "token": "IlirfxKKXAsHtmzK29Pj8A" 234 } 235 ] 236 } 238 When processing a certificate order containing an identifier of type 239 "TNAuthList", a CA MUST use the Authority Token challenge mechanism 240 defined in [I-D.ietf-acme-authority-token] to verify that the 241 requesting ACME client has authenticated and authorized control over 242 the requested resources represented by the "TNAuthList" value. 244 The challenge "token-authority" parameter is optional and only used 245 in cases where the VoIP telephone network requires the CA to identify 246 the Token Authority. This is currently not the case for the SHAKEN 247 [ATIS-1000080] certificate framework governance, but may be used by 248 other frameworks. If a "token-authority" parameter is present, then 249 the ACME client MAY use the "token-authority" value to identify the 250 URL representing the Token Authority that will provide the TNAuthList 251 Authority Token response to the challenge. If the "token-authority" 252 parameter is not present, then the ACME client MUST identify the 253 Token Authority based on locally configured information or local 254 policies. 256 The ACME client MUST respond to the challenge by posting the 257 TNAuthList Authority Token to the challenge URL identified in the 258 returned ACME authorization object, an example of which follows. 260 POST /acme/authz/asdf/0 HTTP/1.1 261 Host: boulder.example.com 262 Content-Type: application/jose+json 264 { 265 "protected": base64url({ 266 "alg": "ES256", 267 "kid": "https://example.com/acme/acct/1", 268 "nonce": "Q_s3MWoqT05TrdkM2MTDcw", 269 "url": "https://boulder.example.com/acme/authz/asdf/0" 270 }), 271 "payload": base64url({ 272 "ATC": "DGyRejmCefe7v4N...vb29HhjjLPSggwiE" 273 }), 274 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 275 } 277 The specifics of the construction of the TNAuthList specific "ATC" 278 token is defined in the next section. 280 5. TNAuthList Authority Token 282 The Telephone Number Authority List Authority Token (TNAuthList 283 Authority Token) is an extension of the ACME Authority Token defined 284 in [I-D.ietf-acme-authority-token]. 286 The TNAuthList Authority Token Protected header MUST comply with the 287 Authority Token Protected header as defined in 288 [I-D.ietf-acme-authority-token]. 290 The TNAuthList Authority Token Payload MUST include the mandatory 291 claims and MAY include the optional claims defined for the Authority 292 Token detailed in the next subsections. 294 5.1. "iss" claim 296 The "iss" claim is an optional claim. It can be used as a URL 297 identifying the Token Authority that issued the TNAuthList Authority 298 Token beyond the "x5u" Header claim that identifies the location of 299 the certificate of the Token Authority used to validate the 300 TNAuthList Authority Token. 302 5.2. "exp" claim 304 The "exp" claim contains the DateTime value of the ending date and 305 time that the TNAuthList Authority Token expires. 307 5.3. "jti" claim 309 The "jti" claim contains a unique identifier for this TNAuthList 310 Authority Token transaction. 312 5.4. "atc" claim 314 The "atc" claim is the only claim specifically defined in this 315 document. It contains an array of three elements; a string set to 316 "TNAuthList", the TNAuthList identifier "value" string, and a 317 fingerprint. 319 The "fingerprint" value is a fingerprint, as defined in [RFC4949] of 320 the ACME account credentials. Specifically, the fingerprint value is 321 a secure one-way hash of the Distinguished Encoding Rules (DER) form 322 of the public key corresponding to the key pair the SP used to create 323 the account with the ACME server. The fingerprint value consists of 324 the name of the hash function, which shall be 'SHA256' for this 325 specification, followed by the hash value itself. The hash value is 326 represented as a sequence of uppercase hexadecimal bytes, separated 327 by colons. The number of bytes is defined by the hash function. 329 An example of the TNAuthList Authority Token is as follows, 330 { "typ":"JWT", 331 "alg":"ES256", 332 "x5u":https://authority.example.org/cert 333 } 335 { 336 "iss":"https://authority.example.org/authz", 337 "exp":1300819380, 338 "jti":"id6098364921", 339 "atc":["TnAuthList","F83n2a...avn27DN3==", 340 "SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:BA:B9:19:81:F8:50: 341 9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"] 342 } 344 Similar to the definition for the TNAuthList identifier "value" 345 string, the identifier value in the "atc" claim must contain the 346 base64 encoding of the TN Authorization List certificate extension 347 ASN.1 object. 349 5.5. Acquiring the token from the Token Authority 351 The specifics of how the token is acquired from the authority is out 352 of the scope of this document 354 5.6. Token Authority Responsibilities 356 When the Token Authority creates the TnAuthList Authority Token, it 357 is the responsibility of the Token Authority to validate that the 358 information contained in the ASN.1 TNAuthList accurately represents 359 the SPC or telephone number resources the ACME client is authorized 360 to represent. 362 6. Validating the TNAuthList Authority Token 364 Upon receiving a response to the challenge, the ACME server MUST 365 perform the following steps to determine the validity of the 366 response. 368 o Verify that the token contained in the Payload "ATC" field is an 369 TNAuthList Authority Token. 371 o Verify the TNAuthList Authority Token signature using the public 372 key of the certificate referenced by the token's "x5u" parameter. 374 o Verify that "atc" claim contains an identifier type of 375 "TNAuthList", 377 o Verify that the "atc" claim contains the equivalent base64 encoded 378 TNAuthList certificate extension string value as the Identifier 379 specified in the original challenge. 381 o Verify that the remaining claims are valid (e.g., verify that 382 token has not expired) 384 o Verify that the "atc" claim "fingerprint" is valid 386 If all steps in the token validation process pass, then the CA MUST 387 set the challenge object "status" to "valid". If any step of the 388 validation process fails, the "status" in the challenge object MUST 389 be set to "invalid". 391 7. Usage Considerations 393 7.1. Large number of Non-contiguous TNAuthList values 395 There are many scenarios and reasons to have various combinations of 396 SPCs, TNs, and TN Ranges. [RFC8226] has provided a somewhat 397 unbounded set of combinations. It's possible that a complex non- 398 contiguous set of telephone numbers are being managed by a CSP. Best 399 practice may be simply to split a set of non-contiguous numbers under 400 management into multiple STI certificates to represent the various 401 contiguous parts of the greater non-contiguous set of TNs, 402 particularly if length of the set of values in identifier object 403 grows to be too large. 405 8. Security Considerations 407 TBD 409 9. IANA Considerations 411 This document requests the addition of a new identifier object type 412 that can be present in the identifier field of the ACME authorization 413 object defined in [I-D.ietf-acme-acme]. 415 +------------+-----------+ 416 | Label | Reference | 417 +------------+-----------+ 418 | TNAuthList | RFCThis | 419 +------------+-----------+ 421 10. Acknowledgements 423 We would like to thank Richard Barnes and Russ Housley for valuable 424 contributions to this document. 426 11. References 428 11.1. Normative References 430 [I-D.ietf-acme-acme] 431 Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 432 Kasten, "Automatic Certificate Management Environment 433 (ACME)", draft-ietf-acme-acme-16 (work in progress), 434 October 2018. 436 [I-D.ietf-acme-authority-token] 437 Peterson, J., Barnes, M., Hancock, D., and C. Wendt, "ACME 438 Challenges Using an Authority Token", draft-ietf-acme- 439 authority-token-00 (work in progress), July 2018. 441 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 442 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 443 . 445 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 446 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 447 . 449 [RFC7340] Peterson, J., Schulzrinne, H., and H. Tschofenig, "Secure 450 Telephone Identity Problem Statement and Requirements", 451 RFC 7340, DOI 10.17487/RFC7340, September 2014, 452 . 454 [RFC8224] Peterson, J., Jennings, C., Rescorla, E., and C. Wendt, 455 "Authenticated Identity Management in the Session 456 Initiation Protocol (SIP)", RFC 8224, 457 DOI 10.17487/RFC8224, February 2018, 458 . 460 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 461 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 462 . 464 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 465 Credentials: Certificates", RFC 8226, 466 DOI 10.17487/RFC8226, February 2018, 467 . 469 11.2. Informative References 471 [ATIS-1000074] 472 ATIS/SIP Forum NNI Task Group, "Signature-based Handling 473 of Asserted information using toKENs (SHAKEN) 474 ", January 2017. 477 [ATIS-1000080] 478 ATIS/SIP Forum NNI Task Group, "Signature-based Handling 479 of Asserted information using toKENs (SHAKEN) Governance 480 Model and Certificate Management 481 ", July 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 Authors' Addresses 491 Chris Wendt 492 Comcast 493 One Comcast Center 494 Philadelphia, PA 19103 495 USA 497 Email: chris-ietf@chriswendt.net 499 David Hancock 500 Comcast 502 Email: davidhancock.ietf@gmail.com 504 Mary Barnes 505 iconectiv 507 Email: mary.ietf.barnes@gmail.com 508 Jon Peterson 509 Neustar Inc. 510 1800 Sutter St Suite 570 511 Concord, CA 94520 512 US 514 Email: jon.peterson@neustar.biz