idnits 2.17.1 draft-ietf-stir-enhance-rfc8226-02.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 (15 April 2021) is 1078 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 225 -- Looks like a reference, but probably isn't: '1' on line 230 -- Looks like a reference, but probably isn't: '2' on line 241 ** Downref: Normative reference to an Informational RFC: RFC 5912 == Outdated reference: A later version (-26) exists of draft-ietf-stir-passport-rcd-09 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 5 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) 15 April 2021 5 Intended status: Standards Track 6 Expires: 17 October 2021 8 Enhanced JWT Claim Constraints for STIR Certificates 9 draft-ietf-stir-enhance-rfc8226-02 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 an additional way 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 17 October 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 . . . . . . . . . . . . . . . . . . . . . 6 58 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 59 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 60 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 62 9.2. Informative References . . . . . . . . . . . . . . . . . 8 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 an additional way to 79 constrain the allowable JWT claims. That is, the enhanced extension 80 can provide a list of claims that are not allowed to be included in 81 the PASSporT. 83 2. Terminology 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 87 "OPTIONAL" in this document are to be interpreted as described in 88 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 89 capitals, as shown here. 91 3. Enhanced JWT Claim Constraints Syntax 93 The Enhanced JWT Claim Constraints certificate extension limits the 94 PASSporT claims and the claim values that can successfully validated 95 by the certificate that contains the extension. Certificate issuers 96 permit all claims by omitting the Enhanced JWT Claim Constraints 97 certificate extension from the extension field of the certificate 98 [RFC5280]. The certificate extension is non-critical, applicable 99 only to end-entity certificates, and defined with ASN.1 [X.680]. The 100 syntax of the JWT claims in a PASSporT is specified in [RFC8225]. 102 The Enhanced JWT Claim Constraints certificate extension is optional, 103 but when present, it constrains the JWT claims that authentication 104 services may include in the PASSporT objects they sign. Constraints 105 are applied by certificate issuers and enforced by recipients when 106 validating PASSporT claims as follows: 108 1. mustInclude indicates JWT claims that MUST appear in the PASSporT 109 in addition to the iat, orig, and dest claims. The baseline 110 PASSporT claims ("iat", "orig", and "dest") are considered to be 111 required by [RFC8225], and these claims SHOULD NOT be part of the 112 mustInclude list. If mustInclude is absent, the iat, orig, and 113 dest claims MUST appear in the PASSporT. 115 2. permittedValues indicates that if the claim name is present, the 116 claim MUST exactly match one of the listed values. 118 3. mustExclude indicates JWT claims that MUST NOT appear in the 119 PASSporT. The baseline PASSporT claims ("iat", "orig", and 120 "dest") are always permitted, and these claims MUST NOT be part 121 of the mustExclude list. 123 The Enhanced JWT Claim Constraints certificate extension is 124 identified by the following object identifier (OID): 126 id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe TBD1 } 128 The Enhanced JWT Claim Constraints certificate extension has the 129 following syntax: 131 EnhancedJWTClaimConstraints ::= SEQUENCE { 132 mustInclude [0] JWTClaimNames OPTIONAL, 133 -- The listed claim names MUST appear in the PASSporT 134 -- in addition to iat, orig, and dest. If absent, iat, orig, 135 -- and dest MUST appear in the PASSporT. 136 permittedValues [1] JWTClaimValuesList OPTIONAL, 137 -- If the claim name is present, the claim MUST contain one 138 -- of the listed values. 139 mustExclude [2] JWTClaimNames OPTIONAL } 140 -- The listed claim names MUST NOT appear in the PASSporT. 141 ( WITH COMPONENTS { ..., mustInclude PRESENT } | 142 WITH COMPONENTS { ..., permittedValues PRESENT } | 143 WITH COMPONENTS { ..., mustExclude PRESENT } ) 145 JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues 147 JWTClaimValues ::= SEQUENCE { 148 claim JWTClaimName, 149 values SEQUENCE SIZE (1..MAX) OF UTF8String } 151 JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName 153 JWTClaimName ::= IA5String 155 4. Usage Examples 157 Consider these usage examples with a PASSporT claim called 158 "confidence" with values "low", "medium", and "high". These examples 159 illustrate the constraints that are imposed by mustInclude, 160 permittedValues, and mustExclude: 162 * If a CA issues to an authentication service certificate that 163 includes an Enhanced JWT Claim Constraints certificate extension 164 that contains the mustInclude JWTClaimName "confidence", then an 165 authentication service is required to include the "confidence" 166 claim in all PASSporTs it generates and signs; a verification 167 service will treat as invalid any PASSporT it receives without a 168 "confidence" PASSporT claim. 170 * If a CA issues to an authentication service certificate that 171 includes an Enhanced JWT Claim Constraints certificate extension 172 that contains the permittedValues JWTClaimName "confidence" and a 173 permitted "high" value, then a verification service will treat as 174 invalid any PASSporT it receives with a PASSporT "confidence" 175 claim with a value other than "high". However, a verification 176 service will not treat as invalid a PASSporT it receives without a 177 PASSporT "confidence" claim at all. 179 * If a CA issues to an authentication service certificate that 180 includes an Enhanced JWT Claim Constraints certificate extension 181 that contains the mustExclude JWTClaimName "confidence", then a 182 verification service will treat as invalid any PASSporT it 183 receives with a PASSporT "confidence" claim regardless of the 184 claim value. 186 5. Certificate Extension Example 188 A certificate containing an example of the 189 EnhancedJWTClaimConstraints certificate extension is provided in 190 Figure 1. The certificate is provided in the format described in 191 [RFC7468]. The example of the EnhancedJWTClaimConstraints extension 192 from the certificate is shown in Figure 2. The example imposes four 193 constraints: 195 1. The "confidence" claim must be present in the PASSporT. 197 2. The "confidence" claim must have a value of "high" or "medium". 199 3. The "priority" claim must not be present in the PASSporT. 201 NOTE: This certificate in Figure 1 will need to be corrected once 202 IANA assigns the object identifier for the certificate extension. 204 -----BEGIN CERTIFICATE----- 205 MIICqjCCAlCgAwIBAgIUH7Zd3rQ5AsvOlzLnzUHhrVhDSlowCgYIKoZIzj0EAwIw 206 KTELMAkGA1UEBhMCVVMxGjAYBgNVBAMMEUJPR1VTIFNIQUtFTiBST09UMB4XDTIx 207 MDQxNTEyMTg1NloXDTIyMDQxNTEyMTg1NlowbDELMAkGA1UEBhMCVVMxCzAJBgNV 208 BAgMAlZBMRAwDgYDVQQHDAdIZXJuZG9uMR4wHAYDVQQKDBVCb2d1cyBFeGFtcGxl 209 IFRlbGVjb20xDTALBgNVBAsMBFZvSVAxDzANBgNVBAMMBlNIQUtFTjBZMBMGByqG 210 SM49AgEGCCqGSM49AwEHA0IABNR6C6nBWRA/fXTglV03aXkXy8hx9oBttVLhsTZ1 211 IYVRBao4OZhVf/Xv1a3xLsZ6KfdhuylSeAKuCoSbVGojYDGjggERMIIBDTAMBgNV 212 HRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDAdBgNVHQ4EFgQUDlG3dxHyzKL/FZfS 213 PI7rpuueRbswHwYDVR0jBBgwFoAUlToKtrQeFrwwyXpMj1qu3TQEeoEwQgYJYIZI 214 AYb4QgENBDUWM1RoaXMgY2VydGlmaWNhdGUgY2Fubm90IGJlIHRydXN0ZWQgZm9y 215 IGFueSBwdXJwb3NlLjAWBggrBgEFBQcBGgQKMAigBhYEMTIzNDBRBgsrBgEFBQcB 216 l4+jcARCMECgDjAMFgpjb25maWRlbmNloSAwHjAcFgpjb25maWRlbmNlMA4MBGhp 217 Z2gMBm1lZGl1baIMMAoWCHByaW9yaXR5MAoGCCqGSM49BAMCA0gAMEUCIQC1AR9y 218 WWHoUWH3KZ0UIvBamAThQvjJCyKWuHQIyR6LSAIgWhuf+di772aGlWhMpv5uSua5 219 ljiGsKx+dMEIE2uU978= 220 -----END CERTIFICATE----- 222 Figure 1. Example Certificate. 224 0 64: SEQUENCE { 225 2 14: [0] { 226 4 12: SEQUENCE { 227 6 10: IA5String 'confidence' 228 : } 229 : } 230 18 32: [1] { 231 20 30: SEQUENCE { 232 22 28: SEQUENCE { 233 24 10: IA5String 'confidence' 234 36 14: SEQUENCE { 235 38 4: UTF8String 'high' 236 44 6: UTF8String 'medium' 237 : } 238 : } 239 : } 240 : } 241 52 12: [2] { 242 54 10: SEQUENCE { 243 56 8: IA5String 'priority' 244 : } 245 : } 246 : } 248 Figure 2. Example EnhancedJWTClaimConstraints extension. 250 6. IANA Considerations 252 This document makes use of object identifiers for the Enhanced JWT 253 Claim Constraints certificate extension defined in Section 3 and the 254 ASN.1 module identifier defined in Appendix A. Therefore, IANA is 255 asked to made the following assignments within the SMI Numbers 256 Registry. 258 For the Enhanced JWT Claim Constraints certificate extension in the 259 "SMI Security for PKIX Certificate Extension" (1.3.6.1.5.5.7.1) 260 registry: 262 TBD1 id-pe-eJWTClaimConstraints 264 For the ASN.1 module identifier in the "SMI Security for PKIX Module 265 Identifier" (1.3.6.1.5.5.7.0) registry: 267 TBD2 id-mod-eJWTClaimConstraints-2021 269 7. Security Considerations 271 For further information on certificate security and practices, see 272 [RFC5280], especially the Security Considerations section. 274 The Enhanced JWT Claim Constraints certificate extension can be used 275 by certificate issuers to provide limits on the acceptable PASSporTs 276 that will be accepted by verification services. Enforcement of these 277 limits depends upon proper implementation by the verification 278 services. The digital signature on the PASSportT data structure will 279 be valid even if the limits are violated. 281 Use of the Enhanced JWT Claim Constraints certificate extension 282 permittedValues constraint is most useful when the claim definition 283 allows a specified set of values. In this way, all of the values 284 that are not listed in the JWTClaimValuesList are prohibited in a 285 valid PASSporT. 287 Certificate issuers must take care when imposing constraints on the 288 PASSporT claims and the claim values that can successfully validated; 289 some combinations can prevent any PASSporT from being successfully 290 validated by the certificate. For example, an entry in mustInclude 291 and an entry in mustExclude for the same claim will prevent 292 successful validation on any PASSporT. 294 Certificate issuers must take care when imposing constraints on the 295 PASSporT claims and the claim values that can successfully validated; 296 some combinations can prevent any PASSporT from being successfully 297 validated by the certificate. For example, an entry in mustInclude 298 and an entry in mustExclude for the same claim will prevent 299 successful validation on any PASSporT. 301 Certificate issuers should not include an entry in mustExclude for 302 the "rcdi" claim for a certificate that will be used with the 303 PASSporT Extension for Rich Call Data defined in 304 [I-D.ietf-stir-passport-rcd]. Excluding this claim would prevent the 305 integrity protection mechanism from working properly. 307 Certificate issuers must take care when performing certificate 308 renewal [RFC4949] to include exactly the same Enhanced JWT Claim 309 Constraints certificate extension in the new certificate as the old 310 one. Renewal usually takes place before the old certificate expires, 311 so there is a period of time where both the new certificate and the 312 old certificate are valid. If different constraints appear in the 313 two certificates with the same public key, some PASSporTs might be 314 valid when one certificate is used and invalid when the other one is 315 used. 317 8. Acknowledgements 319 Many thanks to Chris Wendt for his insight into the need for the for 320 the Enhanced JWT Claim Constraints certificate extension. 322 Thanks to Ben Campbell for the thoughtful review and comments. The 323 document is much better as a result of the comments. 325 9. References 327 9.1. Normative References 329 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 330 Requirement Levels", BCP 14, RFC 2119, 331 DOI 10.17487/RFC2119, March 1997, 332 . 334 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 335 Housley, R., and W. Polk, "Internet X.509 Public Key 336 Infrastructure Certificate and Certificate Revocation List 337 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 338 . 340 [RFC5912] Hoffman, P. and J. Schaad, "New ASN.1 Modules for the 341 Public Key Infrastructure Using X.509 (PKIX)", RFC 5912, 342 DOI 10.17487/RFC5912, June 2010, 343 . 345 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 346 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 347 May 2017, . 349 [RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion 350 Token", RFC 8225, DOI 10.17487/RFC8225, February 2018, 351 . 353 [RFC8226] Peterson, J. and S. Turner, "Secure Telephone Identity 354 Credentials: Certificates", RFC 8226, 355 DOI 10.17487/RFC8226, February 2018, 356 . 358 [X.680] International Telecommunication Union, "Information 359 Technology - Abstract Syntax Notation One (ASN.1): 360 Specification of basic notation", ISO/IEC 8824-1, August 361 2021. 363 9.2. Informative References 365 [I-D.ietf-stir-passport-rcd] 366 Peterson, J. and C. Wendt, "PASSporT Extension for Rich 367 Call Data", Work in Progress, Internet-Draft, draft-ietf- 368 stir-passport-rcd-09, 18 November 2020, 369 . 372 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 373 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 374 . 376 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 377 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 378 April 2015, . 380 Appendix A. ASN.1 Module 382 This appendix provides the ASN.1 [X.680] definitions for the Enhanced 383 JWT Claim Constraints certificate extension. The module defined in 384 this appendix are compatible with the ASN.1 specifications published 385 in 2015. 387 This ASN.1 module imports ASN.1 from [RFC5912]. 389 390 EnhancedJWTClaimConstraints-2021 391 { iso(1) identified-organization(3) dod(6) internet(1) 392 security(5) mechanisms(5) pkix(7) id-mod(0) 393 id-mod-eJWTClaimConstraints-2021(TBD2) } 395 DEFINITIONS EXPLICIT TAGS ::= BEGIN 397 IMPORTS 399 id-pe 400 FROM PKIX1Explicit-2009 -- From RFC 5912 401 { iso(1) identified-organization(3) dod(6) internet(1) 402 security(5) mechanisms(5) pkix(7) id-mod(0) 403 id-mod-pkix1-explicit-02(51) } 405 EXTENSION 406 FROM PKIX-CommonTypes-2009 -- From RFC 5912 407 { iso(1) identified-organization(3) dod(6) internet(1) 408 security(5) mechanisms(5) pkix(7) id-mod(0) 409 id-mod-pkixCommon-02(57) } ; 411 -- Enhanced JWT Claim Constraints Certificate Extension 412 ext-eJWTClaimConstraints EXTENSION ::= { 413 SYNTAX EnhancedJWTClaimConstraints 414 IDENTIFIED BY id-pe-eJWTClaimConstraints } 416 id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe TBD1 } 418 EnhancedJWTClaimConstraints ::= SEQUENCE { 419 mustInclude [0] JWTClaimNames OPTIONAL, 420 -- The listed claim names MUST appear in the PASSporT 421 -- in addition to iat, orig, and dest. If absent, iat, orig, 422 -- and dest MUST appear in the PASSporT. 423 permittedValues [1] JWTClaimValuesList OPTIONAL, 424 -- If the claim name is present, the claim MUST contain one 425 -- of the listed values. 426 mustExclude [2] JWTClaimNames OPTIONAL } 427 -- The listed claim names MUST NOT appear in the PASSporT. 428 ( WITH COMPONENTS { ..., mustInclude PRESENT } | 429 WITH COMPONENTS { ..., permittedValues PRESENT } | 430 WITH COMPONENTS { ..., mustExclude PRESENT } ) 432 JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues 434 JWTClaimValues ::= SEQUENCE { 435 claim JWTClaimName, 436 values SEQUENCE SIZE (1..MAX) OF UTF8String } 438 JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName 440 JWTClaimName ::= IA5String 442 END 443 445 Author's Address 447 Russ Housley 448 Vigil Security, LLC 449 516 Dranesville Road 450 Herndon, VA, 20170 451 United States of America 453 Email: housley@vigilsec.com