idnits 2.17.00 (12 Aug 2021) /tmp/idnits60985/draft-ietf-stir-enhance-rfc8226-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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC8226, but the abstract doesn't seem to directly say this. It does mention RFC8226 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (23 March 2021) is 424 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 243 -- Looks like a reference, but probably isn't: '1' on line 247 -- Looks like a reference, but probably isn't: '2' on line 255 -- Looks like a reference, but probably isn't: '3' on line 259 ** Downref: Normative reference to an Informational RFC: RFC 5912 == Outdated reference: A later version (-17) exists of draft-ietf-stir-passport-rcd-09 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 6 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) 23 March 2021 5 Intended status: Standards Track 6 Expires: 24 September 2021 8 Enhanced JWT Claim Constraints for STIR Certificates 9 draft-ietf-stir-enhance-rfc8226-01 11 Abstract 13 RFC 8226 provides a certificate extension to constrain the JWT claims 14 that can be included in the PASSporT as defined in RFC 8225. If the 15 signer includes a JWT claim outside the constraint boundaries, then 16 the recipient will reject the entire PASSporT. This document defines 17 additional ways that the JWT claims can be constrained. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 24 September 2021. 36 Copyright Notice 38 Copyright (c) 2021 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 54 3. Enhanced JWT Claim Constraints Syntax . . . . . . . . . . . . 3 55 4. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 4 56 5. Certificate Extension Example . . . . . . . . . . . . . . . . 5 57 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 58 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 59 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 60 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 62 9.2. Informative References . . . . . . . . . . . . . . . . . 9 63 Appendix A. ASN.1 Module . . . . . . . . . . . . . . . . . . . . 9 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 66 1. Introduction 68 The use of certificates [RFC5280] in establishing authority over 69 telephone numbers is described in [RFC8226]. 71 Section 8 of [RFC8226] provides a certificate extension to constrain 72 the JWT claims that can be included in the PASSporT [RFC8225]. If 73 the signer includes a JWT claim outside the constraint boundaries, 74 then the recipient will reject the entire PASSporT. 76 This document defines an enhanced JWTClaimConstraints certificate 77 extension, which provides all of the capabilities available in the 78 original certificate extension as well as some additional ways to 79 constrain the allowable JWT claims. 81 2. Terminology 83 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 84 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 85 "OPTIONAL" in this document are to be interpreted as described in 86 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 87 capitals, as shown here. 89 3. Enhanced JWT Claim Constraints Syntax 91 The Enhanced JWT Claim Constraints certificate extension limits the 92 PASSporT claims and the claim values that can successfully validated 93 by the certificate that contains the extension. Certificate issuers 94 permit all claims by omitting the Enhanced JWT Claim Constraints 95 certificate extension from the extension field of the certificate 96 [RFC5280]. The certificate extension is non-critical, applicable 97 only to end-entity certificates, and defined with ASN.1 [X.680]. The 98 syntax of the JWT claims in a PASSporT is specified in [RFC8225]. 100 The Enhanced JWT Claim Constraints certificate extension is optional, 101 but when present, it constrains the JWT claims that authentication 102 services may include in the PASSporT objects they sign. Constraints 103 are applied by certificate issuers and enforced by recipients when 104 validating PASSporT claims as follows: 106 1. mustInclude indicates JWT claims that MUST appear in the PASSporT 107 in addition to the iat, orig, and dest claims. The baseline 108 PASSporT claims ("iat", "orig", and "dest") are considered to be 109 required by [RFC8225], and these claims SHOULD NOT be part of the 110 mustInclude list. If mustInclude is absent, the iat, orig, and 111 dest claims MUST appear in the PASSporT. 113 2. permittedValues indicates that if the claim name is present, the 114 claim MUST exactly match one of the listed values. 116 3. mustExclude indicates JWT claims that MUST NOT appear in the 117 PASSporT. The baseline PASSporT claims ("iat", "orig", and 118 "dest") are always permitted, and these claims MUST NOT be part 119 of the mustExclude list. 121 4. excludedValues indicates that if the claim name is present, the 122 claim MUST NOT exactly match any of the listed values. 124 The Enhanced JWT Claim Constraints certificate extension is 125 identified by the following object identifier (OID): 127 id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe TBD1 } 129 The Enhanced JWT Claim Constraints certificate extension has the 130 following syntax: 132 EnhancedJWTClaimConstraints ::= SEQUENCE { 133 mustInclude [0] JWTClaimNames OPTIONAL, 134 -- The listed claim names MUST appear in the PASSporT 135 -- in addition to iat, orig, and dest. If absent, iat, orig, 136 -- and dest MUST appear in the PASSporT. 137 permittedValues [1] JWTClaimValuesList OPTIONAL, 138 -- If the claim name is present, the claim MUST contain one 139 -- of the listed values. 140 mustExclude [2] JWTClaimNames OPTIONAL, 141 -- The listed claim names MUST NOT appear in the PASSporT. 142 excludedValues [3] JWTClaimValuesList OPTIONAL } 143 -- If the claim name is present, the claim MUST NOT contain 144 -- any of the listed values. 146 ( WITH COMPONENTS { ..., mustInclude PRESENT } | 147 WITH COMPONENTS { ..., permittedValues PRESENT } | 148 WITH COMPONENTS { ..., mustExclude PRESENT } | 149 WITH COMPONENTS { ..., excludedValues PRESENT } ) 151 JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues 153 JWTClaimValues ::= SEQUENCE { 154 claim JWTClaimName, 155 values SEQUENCE SIZE (1..MAX) OF UTF8String } 157 JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName 159 JWTClaimName ::= IA5String 161 4. Usage Examples 163 Consider these usage examples with a PASSporT claim called 164 "confidence" with values "low", "medium", and "high". These examples 165 illustrate the constraints that are imposed by mustInclude, 166 permittedValues, mustExclude, and excludedValues: 168 * If a CA issues to an authentication service certificate that 169 includes an Enhanced JWT Claim Constraints certificate extension 170 that contains the mustInclude JWTClaimName "confidence", then an 171 authentication service is required to include the "confidence" 172 claim in all PASSporTs it generates and signs; a verification 173 service will treat as invalid any PASSporT it receives with a 174 PASSporT claim that does not include the "confidence" claim. 176 * If a CA issues to an authentication service certificate that 177 includes an Enhanced JWT Claim Constraints certificate extension 178 that contains the permittedValues JWTClaimName "confidence" and a 179 permitted "high" value, then a recipient authentication service 180 will treat as invalid any PASSporT it receives with a PASSporT 181 "confidence" claim with a value other than "high". However, a 182 recipient authentication service will not treat as invalid a 183 PASSporT it receives without a PASSporT "confidence" claim at all. 185 * If a CA issues to an authentication service certificate that 186 includes an Enhanced JWT Claim Constraints certificate extension 187 that contains the mustExclude JWTClaimName "confidence", then a 188 recipient authentication service will treat as invalid any 189 PASSporT it receives with a PASSporT "confidence" claim regardless 190 of the claim value. 192 * If a CA issues to an authentication service certificate that 193 includes an Enhanced JWT Claim Constraints certificate extension 194 that contains the excludedValues JWTClaimName "confidence" and a 195 permitted "low" value, then a recipient authentication service 196 will treat as invalid any PASSporT it receives with a PASSporT 197 "confidence" claim with a value of "low". However, a recipient 198 authentication service will not treat as invalid a PASSporT it 199 receives without a PASSporT "confidence" claim at all. 201 5. Certificate Extension Example 203 A certificate containing an example of the 204 EnhancedJWTClaimConstraints certificate extension is provided in 205 Figure 1. The certificate is provided in the format described in 206 [RFC7468]. The example of the EnhancedJWTClaimConstraints extension 207 from the certificate is shown in Figure 2. The example imposes four 208 constraints: 210 1. The "confidence" claim must be present in the PASSporT. 212 2. The "confidence" claim must have a value of "high" or "medium". 214 3. The "priority" claim must not be present in the PASSporT. 216 4. The "assurance" claim, if present in the PASSporT, must not have 217 a value of "low". 219 NOTE: This certificate in Figure 1 will need to be corrected once 220 IANA assigns the object identifier for the certificate extension. 222 -----BEGIN CERTIFICATE----- 223 MIICwjCCAmigAwIBAgIUH7Zd3rQ5AsvOlzLnzUHhrVhDSlkwCgYIKoZIzj0EAwIw 224 KTELMAkGA1UEBhMCVVMxGjAYBgNVBAMMEUJPR1VTIFNIQUtFTiBST09UMB4XDTIx 225 MDEyNjIwMTc1M1oXDTIyMDEyNjIwMTc1M1owbDELMAkGA1UEBhMCVVMxCzAJBgNV 226 BAgMAlZBMRAwDgYDVQQHDAdIZXJuZG9uMR4wHAYDVQQKDBVCb2d1cyBFeGFtcGxl 227 IFRlbGVjb20xDTALBgNVBAsMBFZvSVAxDzANBgNVBAMMBlNIQUtFTjBZMBMGByqG 228 SM49AgEGCCqGSM49AwEHA0IABNR6C6nBWRA/fXTglV03aXkXy8hx9oBttVLhsTZ1 229 IYVRBao4OZhVf/Xv1a3xLsZ6KfdhuylSeAKuCoSbVGojYDGjggEpMIIBJTAMBgNV 230 HRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDAdBgNVHQ4EFgQUDlG3dxHyzKL/FZfS 231 PI7rpuueRbswHwYDVR0jBBgwFoAUlToKtrQeFrwwyXpMj1qu3TQEeoEwQgYJYIZI 232 AYb4QgENBDUWM1RoaXMgY2VydGlmaWNhdGUgY2Fubm90IGJlIHRydXN0ZWQgZm9y 233 IGFueSBwdXJwb3NlLjAWBggrBgEFBQcBGgQKMAigBhYEMTIzNDBpBgsrBgEFBQcB 234 l4+jcARaMFigDjAMFgpjb25maWRlbmNloSAwHjAcFgpjb25maWRlbmNlMA4MBGhp 235 Z2gMBm1lZGl1baIMMAoWCHByaW9yaXR5oxYwFDASFglhc3N1cmFuY2UwBQwDbG93 236 MAoGCCqGSM49BAMCA0gAMEUCIGEJnDIaAI0SiSh0YFWujezSpFVYPCvYh5xnNA1J 237 xxV+AiEApm9YYpEuuzBb7sWfh7ZveMWPfTsmCM5unTUaY6skAGE= 238 -----END CERTIFICATE----- 240 Figure 1. Example Certificate. 242 0 89: SEQUENCE { 243 2 14: [0] { 244 4 12: SEQUENCE { 245 6 10: IA5String 'confidence' 246 : } } 247 18 32: [1] { 248 20 30: SEQUENCE { 249 22 28: SEQUENCE { 250 24 10: IA5String 'confidence' 251 36 14: SEQUENCE { 252 38 4: UTF8String 'high' 253 44 6: UTF8String 'medium' 254 : } } } } 255 52 12: [2] { 256 54 10: SEQUENCE { 257 56 8: IA5String 'priority' 258 : } } 259 66 22: [3] { 260 68 20: SEQUENCE { 261 70 18: SEQUENCE { 262 72 9: IA5String 'assurance' 263 83 5: SEQUENCE { 264 85 3: UTF8String 'low' 265 : } } } } } 267 Figure 2. Example EnhancedJWTClaimConstraints extension. 269 6. IANA Considerations 271 This document makes use of object identifiers for the Enhanced JWT 272 Claim Constraints certificate extension defined in Section 3 and the 273 ASN.1 module identifier defined in Appendix A. Therefore, IANA is 274 asked to made the following assignments within the SMI Numbers 275 Registry. 277 For the Enhanced JWT Claim Constraints certificate extension in the 278 "SMI Security for PKIX Certificate Extension" (1.3.6.1.5.5.7.1) 279 registry: 281 TBD1 id-pe-eJWTClaimConstraints 283 For the ASN.1 module identifier in the "SMI Security for PKIX Module 284 Identifier" (1.3.6.1.5.5.7.0) registry: 286 TBD2 id-mod-eJWTClaimConstraints-2021 288 7. Security Considerations 290 For further information on certificate security and practices, see 291 [RFC5280], especially the Security Considerations section. 293 The Enhanced JWT Claim Constraints certificate extension can be used 294 by certificate issuers to provide limits on the acceptable PASSporT 295 that will be accepted by recipient verification services. 296 Enforcement of these limits depends upon proper implementation by the 297 recipient verification services. The digital signature on the 298 PASSportT data structure will be valid even if the limits are 299 violated. 301 Certificate issuers must take care when imposing constraints on the 302 PASSporT claims and the claim values that can successfully validated; 303 some combinations can prevent any PASSporT from being successfully 304 validated by the certificate. For example, an entry in mustInclude 305 and an entry in mustExclude for the same claim will prevent 306 successful validation on any PASSporT. 308 Likewise, certificate issuers should not include an entry in 309 mustExclude for the "rcdi" claim for a certificate that will be used 310 with the PASSporT Extension for Rich Call Data defined in 311 [I-D.ietf-stir-passport-rcd]. Excluding this claim would prevent the 312 integrity protection mechanism from working properly. 314 Certificate issuers must take care when performing certificate 315 renewal [RFC4949] to include exactly the same Enhanced JWT Claim 316 Constraints certificate extension in the new certificate as the old 317 one. Renewal usually takes place before the old certificate expires, 318 so there is a period of time where both the new certificate and the 319 old certificate are valid. If different constraints appear in the 320 two certificates with the same public key, some PASSporTs might be 321 valid when one certificate is used and invalid when the other one is 322 used. 324 8. Acknowledgements 326 Many thanks to Chris Wendt for his insight into the need for the for 327 the Enhanced JWT Claim Constraints certificate extension. 329 Thanks to Ben Campbell for the thoughtful review and comments. The 330 document is much better as a result of the comments. 332 9. References 334 9.1. Normative References 336 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 337 Requirement Levels", BCP 14, RFC 2119, 338 DOI 10.17487/RFC2119, March 1997, 339 . 341 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 342 Housley, R., and W. Polk, "Internet X.509 Public Key 343 Infrastructure Certificate and Certificate Revocation List 344 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 345 . 347 [RFC5912] Hoffman, P. and J. Schaad, "New ASN.1 Modules for the 348 Public Key Infrastructure Using X.509 (PKIX)", RFC 5912, 349 DOI 10.17487/RFC5912, June 2010, 350 . 352 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 353 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 354 May 2017, . 356 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 357 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 358 . 360 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 361 Credentials: Certificates", RFC 8226, 362 DOI 10.17487/RFC8226, February 2018, 363 . 365 [X.680] International Telecommunication Union, "Information 366 Technology - Abstract Syntax Notation One (ASN.1): 367 Specification of basic notation", ISO/IEC 8824-1, August 368 2021. 370 9.2. Informative References 372 [I-D.ietf-stir-passport-rcd] 373 Peterson, J. and C. Wendt, "PASSporT Extension for Rich 374 Call Data", Work in Progress, Internet-Draft, draft-ietf- 375 stir-passport-rcd-09, 18 November 2020, 376 . 379 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 380 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 381 . 383 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 384 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 385 April 2015, . 387 Appendix A. ASN.1 Module 389 This appendix provides the ASN.1 [X.680] definitions for the Enhanced 390 JWT Claim Constraints certificate extension. The module defined in 391 this appendix are compatible with the ASN.1 specifications published 392 in 2015. 394 This ASN.1 module imports ASN.1 from [RFC5912]. 396 397 EnhancedJWTClaimConstraints-2021 398 { iso(1) identified-organization(3) dod(6) internet(1) 399 security(5) mechanisms(5) pkix(7) id-mod(0) 400 id-mod-eJWTClaimConstraints-2021(TBD2) } 402 DEFINITIONS EXPLICIT TAGS ::= BEGIN 404 IMPORTS 406 id-pe 407 FROM PKIX1Explicit-2009 -- From RFC 5912 408 { iso(1) identified-organization(3) dod(6) internet(1) 409 security(5) mechanisms(5) pkix(7) id-mod(0) 410 id-mod-pkix1-explicit-02(51) } 412 EXTENSION 413 FROM PKIX-CommonTypes-2009 -- From RFC 5912 414 { iso(1) identified-organization(3) dod(6) internet(1) 415 security(5) mechanisms(5) pkix(7) id-mod(0) 416 id-mod-pkixCommon-02(57) } ; 418 -- Enhanced JWT Claim Constraints Certificate Extension 420 ext-eJWTClaimConstraints EXTENSION ::= { 421 SYNTAX EnhancedJWTClaimConstraints 422 IDENTIFIED BY id-pe-JWTClaimConstraints } 424 id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe TBD1 } 426 EnhancedJWTClaimConstraints ::= SEQUENCE { 427 mustInclude [0] JWTClaimNames OPTIONAL, 428 -- The listed claim names MUST appear in the PASSporT 429 -- in addition to iat, orig, and dest. If absent, iat, orig, 430 -- and dest MUST appear in the PASSporT. 431 permittedValues [1] JWTClaimValuesList OPTIONAL, 432 -- If the claim name is present, the claim MUST contain one 433 -- of the listed values. 434 mustExclude [2] JWTClaimNames OPTIONAL, 435 -- The listed claim names MUST NOT appear in the PASSporT. 436 excludedValues [3] JWTClaimValuesList OPTIONAL } 437 -- If the claim name is present, the claim MUST NOT contain 438 -- any of the listed values. 439 ( WITH COMPONENTS { ..., mustInclude PRESENT } | 440 WITH COMPONENTS { ..., permittedValues PRESENT } | 441 WITH COMPONENTS { ..., mustExclude PRESENT } | 442 WITH COMPONENTS { ..., excludedValues PRESENT } ) 444 JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues 446 JWTClaimValues ::= SEQUENCE { 447 claim JWTClaimName, 448 values SEQUENCE SIZE (1..MAX) OF UTF8String } 450 JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName 452 JWTClaimName ::= IA5String 454 END 455 457 Author's Address 458 Russ Housley 459 Vigil Security, LLC 460 516 Dranesville Road 461 Herndon, VA, 20170 462 United States of America 464 Email: housley@vigilsec.com