idnits 2.17.1 draft-ietf-stir-enhance-rfc8226-04.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (30 June 2021) is 1031 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) -- Looks like a reference, but probably isn't: '0' on line 256 -- Looks like a reference, but probably isn't: '1' on line 261 -- Looks like a reference, but probably isn't: '2' on line 272 ** Downref: Normative reference to an Informational RFC: RFC 5912 == Outdated reference: A later version (-26) exists of draft-ietf-stir-passport-rcd-11 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Housley 3 Internet-Draft Vigil Security 4 Updates: 8226 (if approved) 30 June 2021 5 Intended status: Standards Track 6 Expires: 1 January 2022 8 Enhanced JWT Claim Constraints for STIR Certificates 9 draft-ietf-stir-enhance-rfc8226-04 11 Abstract 13 RFC 8226 specifies the use of certificates for Secure Telephone 14 Identity Credentials, and these certificates are often called "STIR 15 Certificates". RFC 8226 provides a certificate extension to 16 constrain the JSON Web Token (JWT) claims that can be included in the 17 Personal Assertion Token (PASSporT) as defined in RFC 8225. If the 18 PASSporT signer includes a JWT claim outside the constraint 19 boundaries, then the PASSporT recipient will reject the entire 20 PASSporT. This document updates RFC 8226; it provides all of the 21 capabilities available in the original certificate extension as well 22 as an additional way to constrain the allowable JWT claims. The 23 enhanced extension can also provide a list of claims that are not 24 allowed to be included in the PASSporT. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on 1 January 2022. 43 Copyright Notice 45 Copyright (c) 2021 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Enhanced JWT Claim Constraints Syntax . . . . . . . . . . . . 3 62 4. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 5 63 5. Certificate Extension Example . . . . . . . . . . . . . . . . 5 64 6. Guidance to Certification Authorities . . . . . . . . . . . . 7 65 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 66 8. Security Considerations . . . . . . . . . . . . . . . . . . . 7 67 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 68 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 10.1. Normative References . . . . . . . . . . . . . . . . . . 8 70 10.2. Informative References . . . . . . . . . . . . . . . . . 9 71 Appendix A. ASN.1 Module . . . . . . . . . . . . . . . . . . . . 10 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 74 1. Introduction 76 The use of certificates [RFC5280] in establishing authority over 77 telephone numbers is described in [RFC8226]. These certificates are 78 often called "STIR Certificates". STIR certificates are an important 79 element of the overall system that prevents the impersonation of 80 telephone numbers on the Internet. 82 Section 8 of [RFC8226] provides a certificate extension to constrain 83 the JSON Web Token (JWT) claims that can be included in the Personal 84 Assertion Token (PASSporT) [RFC8225]. If the PASSporT signer 85 includes a JWT claim outside the constraint boundaries, then the 86 PASSporT recipient will reject the entire PASSporT. 88 This document defines an enhanced JWTClaimConstraints certificate 89 extension, which provides all of the capabilities available in the 90 original certificate extension as well as an additional way to 91 constrain the allowable JWT claims. That is, the enhanced extension 92 can provide a list of claims that are not allowed to be included in 93 the PASSporT. 95 The Enhanced JWT Claim Constraints certificate extension is needed to 96 limit the authority when a parent STIR certificate delegates to a 97 subordinate STIR certificate. For example, 98 [I-D.ietf-stir-cert-delegation] describes the situation where service 99 providers issue a STIR certificate to enterprises or other customers 100 to sign PASSporTs, and the Enhanced JWT Claim Constraints certificate 101 extension can be used to prevent specific claims from being included 102 in PASSporTs and accepted as valid by the PASSporT recipient. 104 The JWT Claim Constraints certificate extension defined in [RFC8226] 105 provides a list of claims that must be included in a valid PASSporT 106 as well as a list if permitted values for selected claims. The 107 Enhanced JWT Claim Constraints certificate extension defined in this 108 document includes those capabilities and adds a list of claims that 109 must not be included in a valid PASSporT. 111 2. Terminology 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 115 "OPTIONAL" in this document are to be interpreted as described in 116 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 117 capitals, as shown here. 119 3. Enhanced JWT Claim Constraints Syntax 121 The Enhanced JWT Claim Constraints certificate extension is non- 122 critical, applicable only to end-entity certificates, and defined 123 with ASN.1 [X.680]. The syntax of the JWT claims in a PASSporT is 124 specified in [RFC8225]. 126 The Enhanced JWT Claim Constraints certificate extension is optional, 127 but when present, it constrains the JWT claims that authentication 128 services may include in the PASSporT objects they sign. Constraints 129 are applied by certificate issuers and enforced by recipients when 130 validating PASSporT claims as follows: 132 1. mustInclude indicates JWT claims that MUST appear in the PASSporT 133 in addition to the iat, orig, and dest claims. The baseline 134 PASSporT claims ("iat", "orig", and "dest") are considered to be 135 required by [RFC8225], and these claims SHOULD NOT be part of the 136 mustInclude list. If mustInclude is absent, the iat, orig, and 137 dest claims MUST appear in the PASSporT. 139 2. permittedValues indicates that if the claim name is present, the 140 claim MUST exactly match one of the listed values. 142 3. mustExclude indicates JWT claims that MUST NOT appear in the 143 PASSporT. The baseline PASSporT claims ("iat", "orig", and 144 "dest") are always permitted, and these claims MUST NOT be part 145 of the mustExclude list. If one of these baseline PASSporT 146 claims appears in the mustExclude list, then the certificate MUST 147 be treated as if the extension was not present. 149 Following the precedent in [RFC8226], JWT Claim Names MUST be ASCII 150 strings, which are also known as strings using the International 151 Alphabet No. 5 [ISO646]. 153 The Enhanced JWT Claim Constraints certificate extension is 154 identified by the following object identifier (OID): 156 id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe TBD1 } 158 The Enhanced JWT Claim Constraints certificate extension has the 159 following syntax: 161 EnhancedJWTClaimConstraints ::= SEQUENCE { 162 mustInclude [0] JWTClaimNames OPTIONAL, 163 -- The listed claim names MUST appear in the PASSporT 164 -- in addition to iat, orig, and dest. If absent, iat, orig, 165 -- and dest MUST appear in the PASSporT. 166 permittedValues [1] JWTClaimValuesList OPTIONAL, 167 -- If the claim name is present, the claim MUST contain one 168 -- of the listed values. 169 mustExclude [2] JWTClaimNames OPTIONAL } 170 -- The listed claim names MUST NOT appear in the PASSporT. 171 ( WITH COMPONENTS { ..., mustInclude PRESENT } | 172 WITH COMPONENTS { ..., permittedValues PRESENT } | 173 WITH COMPONENTS { ..., mustExclude PRESENT } ) 175 JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues 177 JWTClaimValues ::= SEQUENCE { 178 claim JWTClaimName, 179 values SEQUENCE SIZE (1..MAX) OF UTF8String } 181 JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName 183 JWTClaimName ::= IA5String 185 4. Usage Examples 187 Consider these usage examples with a PASSporT claim called 188 "confidence" with values "low", "medium", and "high". These examples 189 illustrate the constraints that are imposed by mustInclude, 190 permittedValues, and mustExclude: 192 * If a CA issues a certificate to an authentication service that 193 includes an Enhanced JWT Claim Constraints certificate extension 194 that contains the mustInclude JWTClaimName "confidence", then an 195 authentication service is required to include the "confidence" 196 claim in all PASSporTs it generates and signs. A verification 197 service will treat as invalid any PASSporT it receives without a 198 "confidence" PASSporT claim. 200 * If a CA issues a certificate to an authentication service that 201 includes an Enhanced JWT Claim Constraints certificate extension 202 that contains the permittedValues JWTClaimName "confidence" and a 203 permitted "high" value, then a verification service will treat as 204 invalid any PASSporT it receives with a PASSporT "confidence" 205 claim with a value other than "high". However, a verification 206 service will not treat as invalid a PASSporT it receives without a 207 PASSporT "confidence" claim at all, unless "confidence" also 208 appears in mustInclude. 210 * If a CA issues a certificate to an authentication service that 211 includes an Enhanced JWT Claim Constraints certificate extension 212 that contains the mustExclude JWTClaimName "confidence", then a 213 verification service will treat as invalid any PASSporT it 214 receives with a PASSporT "confidence" claim regardless of the 215 claim value. 217 5. Certificate Extension Example 219 A certificate containing an example of the 220 EnhancedJWTClaimConstraints certificate extension is provided in 221 Figure 1. The certificate is provided in the format described in 222 [RFC7468]. The example of the EnhancedJWTClaimConstraints extension 223 from the certificate is shown in Figure 2. The example imposes four 224 constraints: 226 1. The "confidence" claim must be present in the PASSporT. 228 2. The "confidence" claim must have a value of "high" or "medium". 230 3. The "priority" claim must not be present in the PASSporT. 232 NOTE: This certificate in Figure 1 will need to be corrected once 233 IANA assigns the object identifier for the certificate extension. 235 -----BEGIN CERTIFICATE----- 236 MIICqjCCAlCgAwIBAgIUH7Zd3rQ5AsvOlzLnzUHhrVhDSlowCgYIKoZIzj0EAwIw 237 KTELMAkGA1UEBhMCVVMxGjAYBgNVBAMMEUJPR1VTIFNIQUtFTiBST09UMB4XDTIx 238 MDQxNTEyMTg1NloXDTIyMDQxNTEyMTg1NlowbDELMAkGA1UEBhMCVVMxCzAJBgNV 239 BAgMAlZBMRAwDgYDVQQHDAdIZXJuZG9uMR4wHAYDVQQKDBVCb2d1cyBFeGFtcGxl 240 IFRlbGVjb20xDTALBgNVBAsMBFZvSVAxDzANBgNVBAMMBlNIQUtFTjBZMBMGByqG 241 SM49AgEGCCqGSM49AwEHA0IABNR6C6nBWRA/fXTglV03aXkXy8hx9oBttVLhsTZ1 242 IYVRBao4OZhVf/Xv1a3xLsZ6KfdhuylSeAKuCoSbVGojYDGjggERMIIBDTAMBgNV 243 HRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDAdBgNVHQ4EFgQUDlG3dxHyzKL/FZfS 244 PI7rpuueRbswHwYDVR0jBBgwFoAUlToKtrQeFrwwyXpMj1qu3TQEeoEwQgYJYIZI 245 AYb4QgENBDUWM1RoaXMgY2VydGlmaWNhdGUgY2Fubm90IGJlIHRydXN0ZWQgZm9y 246 IGFueSBwdXJwb3NlLjAWBggrBgEFBQcBGgQKMAigBhYEMTIzNDBRBgsrBgEFBQcB 247 l4+jcARCMECgDjAMFgpjb25maWRlbmNloSAwHjAcFgpjb25maWRlbmNlMA4MBGhp 248 Z2gMBm1lZGl1baIMMAoWCHByaW9yaXR5MAoGCCqGSM49BAMCA0gAMEUCIQC1AR9y 249 WWHoUWH3KZ0UIvBamAThQvjJCyKWuHQIyR6LSAIgWhuf+di772aGlWhMpv5uSua5 250 ljiGsKx+dMEIE2uU978= 251 -----END CERTIFICATE----- 253 Figure 1. Example Certificate. 255 0 64: SEQUENCE { 256 2 14: [0] { 257 4 12: SEQUENCE { 258 6 10: IA5String 'confidence' 259 : } 260 : } 261 18 32: [1] { 262 20 30: SEQUENCE { 263 22 28: SEQUENCE { 264 24 10: IA5String 'confidence' 265 36 14: SEQUENCE { 266 38 4: UTF8String 'high' 267 44 6: UTF8String 'medium' 268 : } 269 : } 270 : } 271 : } 272 52 12: [2] { 273 54 10: SEQUENCE { 274 56 8: IA5String 'priority' 275 : } 276 : } 277 : } 279 Figure 2. Example EnhancedJWTClaimConstraints extension. 281 6. Guidance to Certification Authorities 283 The EnhancedJWTClaimConstraints extension specified in this document 284 and the JWTClaimConstraints extension specified in [RFC8226] MUST NOT 285 both appear in the same certificate. 287 If the situation calls for mustExclude constraints, then the 288 EnhancedJWTClaimConstraints extension is the only extension that can 289 express the constraints. 291 On the other hand, if the situation does not call for mustExclude 292 constraints, then either the EnhancedJWTClaimConstraints extension or 293 the JWTClaimConstraints extension can express the constraints. Until 294 such time as the EnhancedJWTClaimConstraints become widely 295 implemented, the use of the JWTClaimConstraints extension may be more 296 likely to be implemented. This guess is based on the presumption 297 that the first specified extension will be implemented more widely in 298 the next few years. 300 7. IANA Considerations 302 This document makes use of object identifiers for the Enhanced JWT 303 Claim Constraints certificate extension defined in Section 3 and the 304 ASN.1 module identifier defined in Appendix A. Therefore, IANA is 305 asked to made the following assignments within the SMI Numbers 306 Registry. 308 For the Enhanced JWT Claim Constraints certificate extension in the 309 "SMI Security for PKIX Certificate Extension" (1.3.6.1.5.5.7.1) 310 registry: 312 TBD1 id-pe-eJWTClaimConstraints 314 For the ASN.1 module identifier in the "SMI Security for PKIX Module 315 Identifier" (1.3.6.1.5.5.7.0) registry: 317 TBD2 id-mod-eJWTClaimConstraints-2021 319 8. Security Considerations 321 For further information on certificate security and practices, see 322 [RFC5280], especially the Security Considerations section. 324 Since non-critical certificate extension are ignored by 325 implementations that do not recognize the extension object identifier 326 (OID), constraints on PASSporT validation will only be applied by 327 relying parties that recognize the EnhancedJWTClaimConstraints 328 extension. 330 The Enhanced JWT Claim Constraints certificate extension can be used 331 by certificate issuers to provide limits on the acceptable PASSporTs 332 that can be accepted by verification services. Enforcement of these 333 limits depends upon proper implementation by the verification 334 services. The digital signature on the PASSportT data structure will 335 be valid even if the limits are violated. 337 Use of the Enhanced JWT Claim Constraints certificate extension 338 permittedValues constraint is most useful when the claim definition 339 allows a specified set of values. In this way, all of the values 340 that are not listed in the JWTClaimValuesList are prohibited in a 341 valid PASSporT. 343 Certificate issuers must take care when imposing constraints on the 344 PASSporT claims and the claim values that can successfully validated; 345 some combinations can prevent any PASSporT from being successfully 346 validated by the certificate. For example, an entry in mustInclude 347 and an entry in mustExclude for the same claim will prevent 348 successful validation on any PASSporT. 350 Certificate issuers SHOULD NOT include an entry in mustExclude for 351 the "rcdi" claim for a certificate that will be used with the 352 PASSporT Extension for Rich Call Data defined in 353 [I-D.ietf-stir-passport-rcd]. Excluding this claim would prevent the 354 integrity protection mechanism from working properly. 356 Certificate issuers must take care when performing certificate 357 renewal [RFC4949] to include exactly the same Enhanced JWT Claim 358 Constraints certificate extension in the new certificate as the old 359 one. Renewal usually takes place before the old certificate expires, 360 so there is a period of time where both the new certificate and the 361 old certificate are valid. If different constraints appear in the 362 two certificates with the same public key, some PASSporTs might be 363 valid when one certificate is used and invalid when the other one is 364 used. 366 9. Acknowledgements 368 Many thanks to Chris Wendt for his insight into the need for the for 369 the Enhanced JWT Claim Constraints certificate extension. 371 Thanks to Ben Campbell, Theresa Enghardt, Ben Kaduk, Erik Kline, Eric 372 Vyncke, and Rob Wilton for their thoughtful review and comments. The 373 document is much better as a result of their efforts. 375 10. References 377 10.1. Normative References 379 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 380 Requirement Levels", BCP 14, RFC 2119, 381 DOI 10.17487/RFC2119, March 1997, 382 . 384 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 385 Housley, R., and W. Polk, "Internet X.509 Public Key 386 Infrastructure Certificate and Certificate Revocation List 387 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 388 . 390 [RFC5912] Hoffman, P. and J. Schaad, "New ASN.1 Modules for the 391 Public Key Infrastructure Using X.509 (PKIX)", RFC 5912, 392 DOI 10.17487/RFC5912, June 2010, 393 . 395 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 396 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 397 May 2017, . 399 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 400 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 401 . 403 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 404 Credentials: Certificates", RFC 8226, 405 DOI 10.17487/RFC8226, February 2018, 406 . 408 [X.680] International Telecommunication Union, "Information 409 Technology - Abstract Syntax Notation One (ASN.1): 410 Specification of basic notation", ISO/IEC 8824-1, August 411 2021. 413 10.2. Informative References 415 [I-D.ietf-stir-cert-delegation] 416 Peterson, J., "STIR Certificate Delegation", Work in 417 Progress, Internet-Draft, draft-ietf-stir-cert-delegation- 418 04, 22 February 2021, . 421 [I-D.ietf-stir-passport-rcd] 422 Wendt, C. and J. Peterson, "PASSporT Extension for Rich 423 Call Data", Work in Progress, Internet-Draft, draft-ietf- 424 stir-passport-rcd-11, 29 March 2021, 425 . 428 [ISO646] International Organization for Standardization, 429 "Information processing - ISO 7-bit coded character set 430 for information interchange", ISO/IEC 646:1991, December 431 1991. 433 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 434 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 435 . 437 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 438 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 439 April 2015, . 441 Appendix A. ASN.1 Module 443 This appendix provides the ASN.1 [X.680] definitions for the Enhanced 444 JWT Claim Constraints certificate extension. The module defined in 445 this appendix are compatible with the ASN.1 specifications published 446 in 2015. 448 This ASN.1 module imports ASN.1 from [RFC5912]. 450 451 EnhancedJWTClaimConstraints-2021 452 { iso(1) identified-organization(3) dod(6) internet(1) 453 security(5) mechanisms(5) pkix(7) id-mod(0) 454 id-mod-eJWTClaimConstraints-2021(TBD2) } 456 DEFINITIONS EXPLICIT TAGS ::= BEGIN 458 IMPORTS 460 id-pe 461 FROM PKIX1Explicit-2009 -- From RFC 5912 462 { iso(1) identified-organization(3) dod(6) internet(1) 463 security(5) mechanisms(5) pkix(7) id-mod(0) 464 id-mod-pkix1-explicit-02(51) } 466 EXTENSION 467 FROM PKIX-CommonTypes-2009 -- From RFC 5912 468 { iso(1) identified-organization(3) dod(6) internet(1) 469 security(5) mechanisms(5) pkix(7) id-mod(0) 470 id-mod-pkixCommon-02(57) } ; 472 -- Enhanced JWT Claim Constraints Certificate Extension 474 ext-eJWTClaimConstraints EXTENSION ::= { 475 SYNTAX EnhancedJWTClaimConstraints 476 IDENTIFIED BY id-pe-eJWTClaimConstraints } 478 id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe TBD1 } 480 EnhancedJWTClaimConstraints ::= SEQUENCE { 481 mustInclude [0] JWTClaimNames OPTIONAL, 482 -- The listed claim names MUST appear in the PASSporT 483 -- in addition to iat, orig, and dest. If absent, iat, orig, 484 -- and dest MUST appear in the PASSporT. 485 permittedValues [1] JWTClaimValuesList OPTIONAL, 486 -- If the claim name is present, the claim MUST contain one 487 -- of the listed values. 488 mustExclude [2] JWTClaimNames OPTIONAL } 489 -- The listed claim names MUST NOT appear in the PASSporT. 490 ( WITH COMPONENTS { ..., mustInclude PRESENT } | 491 WITH COMPONENTS { ..., permittedValues PRESENT } | 492 WITH COMPONENTS { ..., mustExclude PRESENT } ) 494 JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues 496 JWTClaimValues ::= SEQUENCE { 497 claim JWTClaimName, 498 values SEQUENCE SIZE (1..MAX) OF UTF8String } 500 JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName 502 JWTClaimName ::= IA5String 504 END 505 507 Author's Address 509 Russ Housley 510 Vigil Security, LLC 511 516 Dranesville Road 512 Herndon, VA, 20170 513 United States of America 515 Email: housley@vigilsec.com