idnits 2.17.1 draft-ietf-stir-enhance-rfc8226-03.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 (10 June 2021) is 1050 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 245 -- Looks like a reference, but probably isn't: '1' on line 250 -- Looks like a reference, but probably isn't: '2' on line 261 ** 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) 10 June 2021 5 Intended status: Standards Track 6 Expires: 12 December 2021 8 Enhanced JWT Claim Constraints for STIR Certificates 9 draft-ietf-stir-enhance-rfc8226-03 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 to define an additional way 21 that the JWT claims can be constrained. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 12 December 2021. 40 Copyright Notice 42 Copyright (c) 2021 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Enhanced JWT Claim Constraints Syntax . . . . . . . . . . . . 3 59 4. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 4 60 5. Certificate Extension Example . . . . . . . . . . . . . . . . 5 61 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 63 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 64 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 66 9.2. Informative References . . . . . . . . . . . . . . . . . 9 67 Appendix A. ASN.1 Module . . . . . . . . . . . . . . . . . . . . 9 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 70 1. Introduction 72 The use of certificates [RFC5280] in establishing authority over 73 telephone numbers is described in [RFC8226]. These certificates are 74 often called "STIR Certificates". STIR certificates are an important 75 element of the overall system that prevents the impersonation of 76 telephone numbers on the Internet. 78 Section 8 of [RFC8226] provides a certificate extension to constrain 79 the JSON Web Token (JWT) claims that can be included in the Personal 80 Assertion Token (PASSporT) [RFC8225]. If the PASSporT signer 81 includes a JWT claim outside the constraint boundaries, then the 82 PASSporT recipient will reject the entire PASSporT. 84 This document defines an enhanced JWTClaimConstraints certificate 85 extension, which provides all of the capabilities available in the 86 original certificate extension as well as an additional way to 87 constrain the allowable JWT claims. That is, the enhanced extension 88 can provide a list of claims that are not allowed to be included in 89 the PASSporT. 91 The Enhanced JWT Claim Constraints certificate extension is needed to 92 limit the authority when a parent STIR certificate delegates to a 93 subordinate STIR certificate. For example, 94 [I-D.ietf-stir-cert-delegation] describes the situation where service 95 providers issue a STIR certificate to enterprises or other customers 96 to sign PASSporTs, and the Enhanced JWT Claim Constraints certificate 97 extension can be used to prevent specific claims from being included 98 in PASSporTs and accepted as valid by the PASSporT recipient. 100 The JWT Claim Constraints certificate extension defined in [RFC8226] 101 provides a list of claims that must be included in a valid PASSporT 102 as well as a list if permitted values for selected claims. The 103 Enhanced JWT Claim Constraints certificate extension defined in this 104 document includes those capabilities and adds a list of claims that 105 must not be included in a valid PASSporT. 107 2. Terminology 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 111 "OPTIONAL" in this document are to be interpreted as described in 112 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 113 capitals, as shown here. 115 3. Enhanced JWT Claim Constraints Syntax 117 The Enhanced JWT Claim Constraints certificate extension is non- 118 critical, applicable only to end-entity certificates, and defined 119 with ASN.1 [X.680]. The syntax of the JWT claims in a PASSporT is 120 specified in [RFC8225]. 122 The Enhanced JWT Claim Constraints certificate extension is optional, 123 but when present, it constrains the JWT claims that authentication 124 services may include in the PASSporT objects they sign. Constraints 125 are applied by certificate issuers and enforced by recipients when 126 validating PASSporT claims as follows: 128 1. mustInclude indicates JWT claims that MUST appear in the PASSporT 129 in addition to the iat, orig, and dest claims. The baseline 130 PASSporT claims ("iat", "orig", and "dest") are considered to be 131 required by [RFC8225], and these claims SHOULD NOT be part of the 132 mustInclude list. If mustInclude is absent, the iat, orig, and 133 dest claims MUST appear in the PASSporT. 135 2. permittedValues indicates that if the claim name is present, the 136 claim MUST exactly match one of the listed values. 138 3. mustExclude indicates JWT claims that MUST NOT appear in the 139 PASSporT. The baseline PASSporT claims ("iat", "orig", and 140 "dest") are always permitted, and these claims MUST NOT be part 141 of the mustExclude list. 143 The Enhanced JWT Claim Constraints certificate extension is 144 identified by the following object identifier (OID): 146 id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe TBD1 } 148 The Enhanced JWT Claim Constraints certificate extension has the 149 following syntax: 151 EnhancedJWTClaimConstraints ::= SEQUENCE { 152 mustInclude [0] JWTClaimNames OPTIONAL, 153 -- The listed claim names MUST appear in the PASSporT 154 -- in addition to iat, orig, and dest. If absent, iat, orig, 155 -- and dest MUST appear in the PASSporT. 156 permittedValues [1] JWTClaimValuesList OPTIONAL, 157 -- If the claim name is present, the claim MUST contain one 158 -- of the listed values. 159 mustExclude [2] JWTClaimNames OPTIONAL } 160 -- The listed claim names MUST NOT appear in the PASSporT. 161 ( WITH COMPONENTS { ..., mustInclude PRESENT } | 162 WITH COMPONENTS { ..., permittedValues PRESENT } | 163 WITH COMPONENTS { ..., mustExclude PRESENT } ) 165 JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues 167 JWTClaimValues ::= SEQUENCE { 168 claim JWTClaimName, 169 values SEQUENCE SIZE (1..MAX) OF UTF8String } 171 JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName 173 JWTClaimName ::= IA5String 175 4. Usage Examples 177 Consider these usage examples with a PASSporT claim called 178 "confidence" with values "low", "medium", and "high". These examples 179 illustrate the constraints that are imposed by mustInclude, 180 permittedValues, and mustExclude: 182 * If a CA issues a certificate to an authentication service that 183 includes an Enhanced JWT Claim Constraints certificate extension 184 that contains the mustInclude JWTClaimName "confidence", then an 185 authentication service is required to include the "confidence" 186 claim in all PASSporTs it generates and signs. A verification 187 service will treat as invalid any PASSporT it receives without a 188 "confidence" PASSporT claim. 190 * If a CA issues a certificate to an authentication service that 191 includes an Enhanced JWT Claim Constraints certificate extension 192 that contains the permittedValues JWTClaimName "confidence" and a 193 permitted "high" value, then a verification service will treat as 194 invalid any PASSporT it receives with a PASSporT "confidence" 195 claim with a value other than "high". However, a verification 196 service will not treat as invalid a PASSporT it receives without a 197 PASSporT "confidence" claim at all. 199 * If a CA issues a certificate to an authentication service that 200 includes an Enhanced JWT Claim Constraints certificate extension 201 that contains the mustExclude JWTClaimName "confidence", then a 202 verification service will treat as invalid any PASSporT it 203 receives with a PASSporT "confidence" claim regardless of the 204 claim value. 206 5. Certificate Extension Example 208 A certificate containing an example of the 209 EnhancedJWTClaimConstraints certificate extension is provided in 210 Figure 1. The certificate is provided in the format described in 211 [RFC7468]. The example of the EnhancedJWTClaimConstraints extension 212 from the certificate is shown in Figure 2. The example imposes four 213 constraints: 215 1. The "confidence" claim must be present in the PASSporT. 217 2. The "confidence" claim must have a value of "high" or "medium". 219 3. The "priority" claim must not be present in the PASSporT. 221 NOTE: This certificate in Figure 1 will need to be corrected once 222 IANA assigns the object identifier for the certificate extension. 224 -----BEGIN CERTIFICATE----- 225 MIICqjCCAlCgAwIBAgIUH7Zd3rQ5AsvOlzLnzUHhrVhDSlowCgYIKoZIzj0EAwIw 226 KTELMAkGA1UEBhMCVVMxGjAYBgNVBAMMEUJPR1VTIFNIQUtFTiBST09UMB4XDTIx 227 MDQxNTEyMTg1NloXDTIyMDQxNTEyMTg1NlowbDELMAkGA1UEBhMCVVMxCzAJBgNV 228 BAgMAlZBMRAwDgYDVQQHDAdIZXJuZG9uMR4wHAYDVQQKDBVCb2d1cyBFeGFtcGxl 229 IFRlbGVjb20xDTALBgNVBAsMBFZvSVAxDzANBgNVBAMMBlNIQUtFTjBZMBMGByqG 230 SM49AgEGCCqGSM49AwEHA0IABNR6C6nBWRA/fXTglV03aXkXy8hx9oBttVLhsTZ1 231 IYVRBao4OZhVf/Xv1a3xLsZ6KfdhuylSeAKuCoSbVGojYDGjggERMIIBDTAMBgNV 232 HRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDAdBgNVHQ4EFgQUDlG3dxHyzKL/FZfS 233 PI7rpuueRbswHwYDVR0jBBgwFoAUlToKtrQeFrwwyXpMj1qu3TQEeoEwQgYJYIZI 234 AYb4QgENBDUWM1RoaXMgY2VydGlmaWNhdGUgY2Fubm90IGJlIHRydXN0ZWQgZm9y 235 IGFueSBwdXJwb3NlLjAWBggrBgEFBQcBGgQKMAigBhYEMTIzNDBRBgsrBgEFBQcB 236 l4+jcARCMECgDjAMFgpjb25maWRlbmNloSAwHjAcFgpjb25maWRlbmNlMA4MBGhp 237 Z2gMBm1lZGl1baIMMAoWCHByaW9yaXR5MAoGCCqGSM49BAMCA0gAMEUCIQC1AR9y 238 WWHoUWH3KZ0UIvBamAThQvjJCyKWuHQIyR6LSAIgWhuf+di772aGlWhMpv5uSua5 239 ljiGsKx+dMEIE2uU978= 240 -----END CERTIFICATE----- 242 Figure 1. Example Certificate. 244 0 64: SEQUENCE { 245 2 14: [0] { 246 4 12: SEQUENCE { 247 6 10: IA5String 'confidence' 248 : } 249 : } 250 18 32: [1] { 251 20 30: SEQUENCE { 252 22 28: SEQUENCE { 253 24 10: IA5String 'confidence' 254 36 14: SEQUENCE { 255 38 4: UTF8String 'high' 256 44 6: UTF8String 'medium' 257 : } 258 : } 259 : } 260 : } 261 52 12: [2] { 262 54 10: SEQUENCE { 263 56 8: IA5String 'priority' 264 : } 265 : } 266 : } 268 Figure 2. Example EnhancedJWTClaimConstraints extension. 270 6. IANA Considerations 272 This document makes use of object identifiers for the Enhanced JWT 273 Claim Constraints certificate extension defined in Section 3 and the 274 ASN.1 module identifier defined in Appendix A. Therefore, IANA is 275 asked to made the following assignments within the SMI Numbers 276 Registry. 278 For the Enhanced JWT Claim Constraints certificate extension in the 279 "SMI Security for PKIX Certificate Extension" (1.3.6.1.5.5.7.1) 280 registry: 282 TBD1 id-pe-eJWTClaimConstraints 284 For the ASN.1 module identifier in the "SMI Security for PKIX Module 285 Identifier" (1.3.6.1.5.5.7.0) registry: 287 TBD2 id-mod-eJWTClaimConstraints-2021 289 7. Security Considerations 291 For further information on certificate security and practices, see 292 [RFC5280], especially the Security Considerations section. 294 The Enhanced JWT Claim Constraints certificate extension can be used 295 by certificate issuers to provide limits on the acceptable PASSporTs 296 that will be accepted by verification services. Enforcement of these 297 limits depends upon proper implementation by the verification 298 services. The digital signature on the PASSportT data structure will 299 be valid even if the limits are violated. 301 Use of the Enhanced JWT Claim Constraints certificate extension 302 permittedValues constraint is most useful when the claim definition 303 allows a specified set of values. In this way, all of the values 304 that are not listed in the JWTClaimValuesList are prohibited in a 305 valid PASSporT. 307 Certificate issuers must take care when imposing constraints on the 308 PASSporT claims and the claim values that can successfully validated; 309 some combinations can prevent any PASSporT from being successfully 310 validated by the certificate. For example, an entry in mustInclude 311 and an entry in mustExclude for the same claim will prevent 312 successful validation on any PASSporT. 314 Certificate issuers should not include an entry in mustExclude for 315 the "rcdi" claim for a certificate that will be used with the 316 PASSporT Extension for Rich Call Data defined in 317 [I-D.ietf-stir-passport-rcd]. Excluding this claim would prevent the 318 integrity protection mechanism from working properly. 320 Certificate issuers must take care when performing certificate 321 renewal [RFC4949] to include exactly the same Enhanced JWT Claim 322 Constraints certificate extension in the new certificate as the old 323 one. Renewal usually takes place before the old certificate expires, 324 so there is a period of time where both the new certificate and the 325 old certificate are valid. If different constraints appear in the 326 two certificates with the same public key, some PASSporTs might be 327 valid when one certificate is used and invalid when the other one is 328 used. 330 8. Acknowledgements 332 Many thanks to Chris Wendt for his insight into the need for the for 333 the Enhanced JWT Claim Constraints certificate extension. 335 Thanks to Ben Campbell and Theresa Enghardt for the thoughtful review 336 and comments. The document is much better as a result of the 337 comments. 339 9. References 341 9.1. Normative References 343 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 344 Requirement Levels", BCP 14, RFC 2119, 345 DOI 10.17487/RFC2119, March 1997, 346 . 348 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 349 Housley, R., and W. Polk, "Internet X.509 Public Key 350 Infrastructure Certificate and Certificate Revocation List 351 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 352 . 354 [RFC5912] Hoffman, P. and J. Schaad, "New ASN.1 Modules for the 355 Public Key Infrastructure Using X.509 (PKIX)", RFC 5912, 356 DOI 10.17487/RFC5912, June 2010, 357 . 359 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 360 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 361 May 2017, . 363 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 364 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 365 . 367 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 368 Credentials: Certificates", RFC 8226, 369 DOI 10.17487/RFC8226, February 2018, 370 . 372 [X.680] International Telecommunication Union, "Information 373 Technology - Abstract Syntax Notation One (ASN.1): 374 Specification of basic notation", ISO/IEC 8824-1, August 375 2021. 377 9.2. Informative References 379 [I-D.ietf-stir-cert-delegation] 380 Peterson, J., "STIR Certificate Delegation", Work in 381 Progress, Internet-Draft, draft-ietf-stir-cert-delegation- 382 04, 22 February 2021, . 385 [I-D.ietf-stir-passport-rcd] 386 Wendt, C. and J. Peterson, "PASSporT Extension for Rich 387 Call Data", Work in Progress, Internet-Draft, draft-ietf- 388 stir-passport-rcd-11, 29 March 2021, 389 . 392 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 393 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 394 . 396 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 397 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 398 April 2015, . 400 Appendix A. ASN.1 Module 402 This appendix provides the ASN.1 [X.680] definitions for the Enhanced 403 JWT Claim Constraints certificate extension. The module defined in 404 this appendix are compatible with the ASN.1 specifications published 405 in 2015. 407 This ASN.1 module imports ASN.1 from [RFC5912]. 409 410 EnhancedJWTClaimConstraints-2021 411 { iso(1) identified-organization(3) dod(6) internet(1) 412 security(5) mechanisms(5) pkix(7) id-mod(0) 413 id-mod-eJWTClaimConstraints-2021(TBD2) } 415 DEFINITIONS EXPLICIT TAGS ::= BEGIN 417 IMPORTS 419 id-pe 420 FROM PKIX1Explicit-2009 -- From RFC 5912 421 { iso(1) identified-organization(3) dod(6) internet(1) 422 security(5) mechanisms(5) pkix(7) id-mod(0) 423 id-mod-pkix1-explicit-02(51) } 425 EXTENSION 426 FROM PKIX-CommonTypes-2009 -- From RFC 5912 427 { iso(1) identified-organization(3) dod(6) internet(1) 428 security(5) mechanisms(5) pkix(7) id-mod(0) 429 id-mod-pkixCommon-02(57) } ; 431 -- Enhanced JWT Claim Constraints Certificate Extension 433 ext-eJWTClaimConstraints EXTENSION ::= { 434 SYNTAX EnhancedJWTClaimConstraints 435 IDENTIFIED BY id-pe-eJWTClaimConstraints } 437 id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe TBD1 } 439 EnhancedJWTClaimConstraints ::= SEQUENCE { 440 mustInclude [0] JWTClaimNames OPTIONAL, 441 -- The listed claim names MUST appear in the PASSporT 442 -- in addition to iat, orig, and dest. If absent, iat, orig, 443 -- and dest MUST appear in the PASSporT. 444 permittedValues [1] JWTClaimValuesList OPTIONAL, 445 -- If the claim name is present, the claim MUST contain one 446 -- of the listed values. 447 mustExclude [2] JWTClaimNames OPTIONAL } 448 -- The listed claim names MUST NOT appear in the PASSporT. 449 ( WITH COMPONENTS { ..., mustInclude PRESENT } | 450 WITH COMPONENTS { ..., permittedValues PRESENT } | 451 WITH COMPONENTS { ..., mustExclude PRESENT } ) 453 JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues 455 JWTClaimValues ::= SEQUENCE { 456 claim JWTClaimName, 457 values SEQUENCE SIZE (1..MAX) OF UTF8String } 459 JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName 461 JWTClaimName ::= IA5String 463 END 464 466 Author's Address 468 Russ Housley 469 Vigil Security, LLC 470 516 Dranesville Road 471 Herndon, VA, 20170 472 United States of America 474 Email: housley@vigilsec.com