idnits 2.17.1 draft-ietf-acme-authority-token-tnauthlist-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** 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 (July 01, 2018) is 2119 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'ATIS-1000074' is defined on line 417, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-acme-acme-12 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 C. Wendt 3 Internet-Draft D. Hancock 4 Intended status: Informational Comcast 5 Expires: January 2, 2019 M. Barnes 6 iconectiv 7 J. Peterson 8 Neustar Inc. 9 July 01, 2018 11 TNAuthList profile of ACME Authority Token 12 draft-ietf-acme-authority-token-tnauthlist-00 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 January 2, 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 . . . . . . . . . . . . . 4 60 5. TNAuthList Authority Token . . . . . . . . . . . . . . . . . 6 61 5.1. "iss" claim . . . . . . . . . . . . . . . . . . . . . . . 6 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 Authority . . . . . . . . . 8 66 5.6. Authority Responsibilities . . . . . . . . . . . . . . . 8 67 6. Validating the TNAuthList Authority Token . . . . . . . . . . 8 68 7. Usage Considerations . . . . . . . . . . . . . . . . . . . . 8 69 7.1. Large number of Non-contiguous TNAuthList values . . . . 8 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 71 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 72 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 10.1. Normative References . . . . . . . . . . . . . . . . . . 9 74 10.2. Informative References . . . . . . . . . . . . . . . . . 10 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 77 1. Introduction 79 [I-D.ietf-acme-acme] is a mechanism for automating certificate 80 management on the Internet. It enables administrative entities to 81 prove effective control over resources like domain names, and 82 automates the process of generating and issuing certificates. 83 [I-D.peterson-acme-authority-token] extends ACME to provide a general 84 method of extending the Authority and authorization of entities to 85 control a resource via a third party Authority beyond the 86 Certification Authority. 88 This document addresses the STIR problem statement [RFC7340] which 89 identifies the need for Internet credentials that can attest 90 authority for the originator of VoIP calls in order to detect 91 impersonation, which is currently an enabler for common attacks 92 associated with illegal robocalling, voicemail hacking, and swatting. 93 These credentials are used to sign PASSporTs [RFC8225], which can be 94 carried in using protocols such as SIP [RFC8224]. Currently, the 95 only defined credentials for this purpose are the certificates 96 specified in [RFC8226]. 98 [RFC8226] describes certificate extensions suitable for associating 99 telephone numbers and service provider codes with certificates. 100 Specifically, the TN Authorization List defined in [RFC8226] 101 Section 9, defines the ability to associate a STI certificate with a 102 specific set of Service Provider Codes (SPC), Telephone Numbers 103 (TNs), or Telephone Number ranges (TN ranges). Typically, these 104 identifiers have been associated to a Communications Service Provider 105 (CSP) that is authorized to use a set of telephone numbers or 106 telephone number ranges in association with a Service Provider Code 107 as defined in [RFC8226]. The SPC is a unique code or string managed 108 by a national regulatory body that has the authority over those code 109 associations. 111 2. Terminology 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in [RFC2119]. 117 3. ACME new-order identifiers for TNAuthList 119 In [I-D.ietf-acme-acme], Section 7.4 defines the procedure that an 120 ACME client uses to order a new certificate from a Certificate 121 Authority. The new-order request contains an identifier object that 122 specifies the identifiers the order corresponds to. For the 123 TNAuthList identifier, the new-order request MUST include a type set 124 to the string "TNAuthList". The value of the identifier MUST be set 125 to the details of the TNAuthList requested. 127 The format of the string that represents the TNAuthList MUST be 128 constructed as a base64 [RFC4648] encoding of the TN Authorization 129 List certificate extension ASN.1 object. The TN Authorization List 130 certificate extension ASN.1 syntax is defined in [RFC8226] section 9. 132 An example request for a TNAuthList certificate would look as 133 follows, 135 "identifiers": [{"type":"TNAuthList","value":"F83n2a...avn27DN3=="}] 137 Where the "value" object string represents the arbitrary length 138 base64 encoded string. 140 A full new-order request would look as follows, 142 POST /acme/new-order HTTP/1.1 143 Host: example.com 144 Content-Type: application/jose+json 146 { 147 "protected": base64url({ 148 "alg": "ES256", 149 "kid": "https://example.com/acme/acct/1", 150 "nonce": "5XJ1L3lEkMG7tR6pA00clA", 151 "url": "https://example.com/acme/new-order" 152 }), 153 "payload": base64url({ 154 "identifiers": [{"type:"TNAuthList","value":"F83n2a...avn27DN3=="}], 155 "notBefore": "2018-01-01T00:00:00Z", 156 "notAfter": "2018-01-08T00:00:00Z" 157 }), 158 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g" 159 } 161 4. TNAuthList Identifier Authorization 163 On receiving a valid new-order request, the CA creates an 164 authorization challenge and can be queried by the following example 165 request and response. 167 GET /acme/authz/1234 HTTP/1.1 168 Host: example.com 169 HTTP/1.1 200 OK 170 Content-Type: application/json 171 Link: ;rel="index" 173 { 174 "status": "pending", 175 "expires": "2018-03-03T14:09:00Z", 177 "identifier": { 178 "type:"TNAuthList", 179 "value":"F83n2a...avn27DN3==" 180 }, 182 "challenges": [ 183 { 184 "type": "tkauth-01", 185 "tkauth-type": "ATC", 186 "token-authority": "https://authority.example.org/authz", 187 "url": "https://boulder.example.com/authz/asdf/0" 188 "token": "IlirfxKKXAsHtmzK29Pj8A" 189 } 190 ] 191 } 193 This follows [I-D.peterson-acme-authority-token] with a challenge 194 with the specific identifier of type "TNAuthList" corresponding to 195 new-order defined previously in this document. 197 When processing a certificate order containing an identifier of type 198 "TNAuthList", a CA MUST use the Authority Token challenge mechanism 199 defined in [I-D.peterson-acme-authority-token] to verify that the 200 requesting ACME client has authenticated and authorized control over 201 the requested resources represented by the "TNAuthList" value. 203 The challenge "token-authority" parameter is optional and only used 204 in cases where the VoIP telephone network requires a CA to determine 205 the authority. This is currently not the case for the SHAKEN 206 [ATIS-1000080] certificate framework governance, but may be used by 207 other frameworks. If a "token-authority" parameter is present, then 208 the ACME client MAY use the "token-authority" value to identify the 209 URL representing the authority that will provide the TNAuthList 210 Authority Token response to the challenge. If the "token-authority" 211 parameter is not present, then the ACME client MUST identify the 212 Authority based on locally configured information or local policies. 214 A client responds to this challenge by providing an TNAuthList 215 Authority Token to the CA. The ACME client MUST respond to the 216 challenge by posting the TNAuthList Authority Token to the URL 217 identified in the ACME challenge with a request, an example of which 218 follows. 220 POST /acme/authz/asdf/0 HTTP/1.1 221 Host: sti-ca.com 222 Content-Type: application/jose+json 224 { 225 "protected": base64url({ 226 "alg": "ES256", 227 "kid": "https://sti-ca.com/acme/reg/asdf", 228 "nonce": "Q_s3MWoqT05TrdkM2MTDcw", 229 "url": "https://sti-ca.com/acme/authz/asdf/0" 230 }), 231 "payload": base64url({ 232 "ATC": "DGyRejmCefe7v4N...vb29HhjjLPSggwiE" 233 }), 234 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ" 235 } 237 The specifics of the construction of the TNAuthList specific "ATC" 238 token is defined in the next section. 240 5. TNAuthList Authority Token 242 The Telephone Number Authority List Authority Token (TNAuthList 243 Authority Token) is an extension of the ACME Authority Token defined 244 in [I-D.peterson-acme-authority-token]. 246 The TNAuthList Authority Token Protected header MUST comply with the 247 Authority Token Protected header as defined in 248 [I-D.peterson-acme-authority-token]. 250 The TNAuthList Authority Token Payload MUST include the mandatory 251 claims and MAY include the optional claims defined for the Authority 252 Token detailed in the next subsections. 254 5.1. "iss" claim 256 The "iss" claim is an optional claim. It can be used as a URL 257 identifying the Authority that issued the TNAuthList Authority Token 258 beyond the "x5u" Header claim that identifies the location of the 259 certificate of the Authority used to validate the Authority Token. 261 5.2. "exp" claim 263 The "exp" claim contains the DateTime value of the ending time and 264 date that the TNAuthList Authority Token expires. 266 5.3. "jti" claim 268 The "jti" claim contains a unique identifier for the TNAuthList 269 Authority Token transaction. 271 5.4. "atc" claim 273 The "atc" claim is the only claim specifically defined in this 274 document. It contains an array of three elements; a string set to 275 "TNAuthList", the base64 encoded TNAuthList certificate extension 276 string, and a fingerprint. 278 The "fingerprint" value is a certificate fingerprint of the ACME 279 credentials, defined in [RFC4949]. The fingerprint is of the 280 certificate the SP used to create an account with the ACME server. A 281 certificate fingerprint is a secure one-way hash of the Distinguished 282 Encoding Rules (DER) form of the certificate. The fingerprint value 283 consists of the name of the hash function, which shall be 'SHA256' 284 for this specification, followed by the hash value itself. The hash 285 value is represented as a sequence of uppercase hexadecimal bytes, 286 separated by colons. The number of bytes is defined by the hash 287 function. 289 An example of the TNAuthList Authority Token is as follows, 291 { "typ":"JWT", 292 "alg":"ES256", 293 "x5u":https://authority.example.org/cert 294 } 296 { 297 "iss":"https://authority.example.org/authz", 298 "exp":1300819380, 299 "jti":"id6098364921", 300 "atc":["TnAuthList","F83n2a...avn27DN3==", 301 "SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:BA:B9:19:81:F8:50: 302 9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"] 303 } 305 Similar to how the TNAuthList identifier value is defined, the 306 identifier value in the "atc" should also include the same base64 307 encoded TNAuthList certificate extension string. 309 5.5. Acquiring the token from the Authority 311 The specifics of how the token is acquired from the authority can 312 vary and is out of the scope of this document. 314 5.6. Authority Responsibilities 316 When the Authority creates the Authority Token, it is the 317 responsibility of the Authority to validate that the information 318 contained in the ASN.1 TNAuthList accurately represents the SPC or 319 telephone number resources the ACME client is authorized to 320 represent. 322 6. Validating the TNAuthList Authority Token 324 Upon receiving a response to the challenge, the ACME server MUST 325 perform the following steps to determine the validity of the 326 response. 328 o Verify that the token contained in the Payload "ATC" field is an 329 TNAuthList Authority Token. 331 o Verify the TNAuthList Authority Token signature using the public 332 key of the certificate referenced by the token's "x5u" parameter. 334 o Verify that "atc" claim contains an identifier type of 335 "TNAuthList", 337 o Verify that the "atc" claim contains the equivalent base64 encoded 338 TNAuthList certificate extension string value as the Identifier 339 specified in the original challenge. 341 o Verify that the remaining claims are valid (e.g., verify that 342 token has not expired) 344 If all steps in the token validation process pass, then the CA MUST 345 set the challenge object "status" to "valid". If any step of the 346 validation process fails, the "status" in the challenge object MUST 347 be set to "invalid". 349 7. Usage Considerations 351 7.1. Large number of Non-contiguous TNAuthList values 353 There are many scenarios and reasons to have various combinations of 354 SPCs, TNs, and TN Ranges. [RFC8226] has provided a somewhat 355 unbounded set of combinations. It's possible that a complex non- 356 contiguous set of telephone numbers are being managed by a CSP. Best 357 practice may be simply to split a set of non-contiguous numbers under 358 management into multiple STI certificates to represent the various 359 contiguous parts of the greater non-contiguous set of TNs, 360 particularly if length of the set of values in identifier object 361 grows to be too large. 363 8. Security Considerations 365 TBD 367 9. Acknowledgements 369 We would like to thank Richard Barnes and Russ Housley for valuable 370 contributions to this document. 372 10. References 374 10.1. Normative References 376 [I-D.ietf-acme-acme] 377 Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. 378 Kasten, "Automatic Certificate Management Environment 379 (ACME)", draft-ietf-acme-acme-12 (work in progress), April 380 2018. 382 [I-D.peterson-acme-authority-token] 383 Peterson, J., Barnes, M., Hancock, D., and C. Wendt, "ACME 384 Challenges Using an Authority Token", draft-peterson-acme- 385 authority-token-01 (work in progress), March 2018. 387 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 388 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 389 . 391 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 392 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 393 . 395 [RFC7340] Peterson, J., Schulzrinne, H., and H. Tschofenig, "Secure 396 Telephone Identity Problem Statement and Requirements", 397 RFC 7340, DOI 10.17487/RFC7340, September 2014, 398 . 400 [RFC8224] Peterson, J., Jennings, C., Rescorla, E., and C. Wendt, 401 "Authenticated Identity Management in the Session 402 Initiation Protocol (SIP)", RFC 8224, 403 DOI 10.17487/RFC8224, February 2018, 404 . 406 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 407 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 408 . 410 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 411 Credentials: Certificates", RFC 8226, 412 DOI 10.17487/RFC8226, February 2018, 413 . 415 10.2. Informative References 417 [ATIS-1000074] 418 ATIS/SIP Forum NNI Task Group, "Signature-based Handling 419 of Asserted information using toKENs (SHAKEN)", January 420 2017. 422 [ATIS-1000080] 423 ATIS/SIP Forum NNI Task Group, "Signature-based Handling 424 of Asserted information using toKENs (SHAKEN) Governance 425 Model and Certificate Management", July 2017. 427 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 428 Requirement Levels", BCP 14, RFC 2119, 429 DOI 10.17487/RFC2119, March 1997, 430 . 432 Authors' Addresses 434 Chris Wendt 435 Comcast 436 One Comcast Center 437 Philadelphia, PA 19103 438 USA 440 Email: chris-ietf@chriswendt.net 442 David Hancock 443 Comcast 445 Email: davidhancock.ietf@gmail.com 447 Mary Barnes 448 iconectiv 450 Email: mary.ietf.barnes@gmail.com 451 Jon Peterson 452 Neustar Inc. 453 1800 Sutter St Suite 570 454 Concord, CA 94520 455 US 457 Email: jon.peterson@neustar.biz