RFC 9118

Enhanced JSON Web Token (JWT) Claim Constraints for Secure Telephone Identity Revisited (STIR) Certificates

📅 published August 2021, from ietf

RFC 9118: Enhanced JWT Claim Constraints for Secure Telephone Identity Revisited (STIR) Certificates 🎀

okay bestie, this one is by R. Housley at Vigil Security 💼 and it's a Standards Track doc, so it's the real deal with the whole IETF consensus stamp ✨. It's dated August 2021 🌸 and it updates RFC 8226 (Updates: 8226). It's giving "build on what's already there" energy. The ISSN is 2070-1721.

Abstract ✨

RFC 8226 is the spec for certificates used in Secure Telephone Identity Credentials 📞, which people call "Secure Telephone Identity Revisited (STIR) Certificates" 🦋. It adds a certificate extension that constrains which JWT claims can show up in a PASSporT (the thing defined in RFC 8225). If the PASSporT signer puts a JWT claim outside those constraint boundaries, the PASSporT recipient rejects the entire PASSporT 💀.

This doc updates RFC 8226 🔥. It keeps every capability the original extension had, and adds a new way to constrain the allowable JWT claims. The enhanced extension can also hand over a list of claims that are not allowed to be in the PASSporT 🙅‍♀️.

Status of This Memo 🌈

This is an Internet Standards Track document 👑.

This document is a product of the Internet Engineering Task Force (IETF) 💜. It represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication. You can find more about Internet Standards in Section 2 of RFC 7841 🧚.

For the current status, any errata, and where to send feedback, check https://www.rfc-editor.org/info/rfc9118 🔗.

Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved ©️.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date. Please actually read them, because they spell out your rights and restrictions for this document 📜. Any Code Components pulled out of this document must include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as the Simplified BSD License describes 🫶.

Table of Contents 🍓

   1.  Introduction
   2.  Terminology
   3.  Enhanced JWT Claim Constraints Syntax
   4.  Usage Examples
   5.  Certificate Extension Example
   6.  Guidance to Certification Authorities
   7.  IANA Considerations
   8.  Security Considerations
   9.  References
     9.1.  Normative References
     9.2.  Informative References
   Appendix A.  ASN.1 Module
   Acknowledgements
   Author's Address

1. Introduction ✨

Okay so, [RFC8226] is where the use of certificates [RFC5280] for establishing authority over telephone numbers gets described 📞. People call these certificates "STIR Certificates" 🦋. They're a huge piece of the bigger system that stops telephone numbers from being impersonated on the Internet 🛡️. Iconic work honestly.

Section 8 of [RFC8226] gives a certificate extension that constrains the JSON Web Token (JWT) claims which can be included in the Personal Assertion Token (PASSporT) [RFC8225]. If the PASSporT signer includes a JWT claim outside the constraint boundaries, the PASSporT recipient rejects the entire PASSporT 💀.

This document defines an enhanced JWTClaimConstraints certificate extension 💖. It has every capability the original extension had, plus an extra way to constrain the allowable JWT claims. In other words, the enhanced extension can give a list of claims that are not allowed to be included in the PASSporT 🙅‍♀️.

The Enhanced JWT Claim Constraints certificate extension is needed to limit the authority when a parent STIR certificate delegates to a subordinate STIR certificate 🌸. For example, [RFC9060] covers the situation where service providers issue a STIR certificate to enterprises or other customers so they can sign PASSporTs 🏢. The Enhanced JWT Claim Constraints extension can stop specific claims from being included in PASSporTs and then getting accepted as valid by the PASSporT recipient 🚫.

The JWT Claim Constraints certificate extension from [RFC8226] gives a list of claims that have to be included in a valid PASSporT, along with a list of permitted values for selected claims 📋. The Enhanced version in this document keeps all of that and adds a list of claims that must not be included in a valid PASSporT 🔥.

2. Terminology 🔑

Here's the key word rule, bestie 🗝️. The words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🎀. Lowercase versions are just regular words, so no stress 💅.

3. Enhanced JWT Claim Constraints Syntax 🦋

The Enhanced JWT Claim Constraints certificate extension is non-critical 🙂, applies only to end-entity certificates, and is defined with ASN.1 [X.680]. The syntax of the JWT claims in a PASSporT is specified in [RFC8225] 📖.

The Enhanced JWT Claim Constraints certificate extension is optional 🌈. When it's present, it constrains the JWT claims that authentication services can include in the PASSporT objects they sign ✍️. Certificate issuers apply the constraints, and recipients enforce them when validating PASSporT claims, like this:

  1. mustInclude indicates JWT claims that MUST appear in the PASSporT in addition to the iat, orig, and dest claims 💫. The baseline PASSporT claims ("iat", "orig", and "dest") are considered to be required by [RFC8225], and these claims SHOULD NOT be part of the mustInclude list 🙈. If mustInclude is absent, the iat, orig, and dest claims MUST appear in the PASSporT 🧚.
  2. permittedValues indicates that, if the claim name is present, the claim MUST exactly match one of the listed values 🎯.
  3. mustExclude indicates JWT claims that MUST NOT appear in the PASSporT 🚫. The baseline PASSporT claims ("iat", "orig", and "dest") are always permitted, so these claims MUST NOT be part of the mustExclude list 💅. If one of these baseline PASSporT claims shows up in the mustExclude list, the certificate MUST be treated as if the extension was not present 💀.

Following the precedent in [RFC8226], JWT Claim Names MUST be ASCII strings, which are also known as strings using the International Alphabet No. 5 [ISO646] 🔤.

The Enhanced JWT Claim Constraints certificate extension is identified by this object identifier (OID) 🆔:

    id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe 33 }

And the Enhanced JWT Claim Constraints certificate extension has this syntax 🌸:

    EnhancedJWTClaimConstraints ::= SEQUENCE {
      mustInclude [0] JWTClaimNames OPTIONAL,
        -- The listed claim names MUST appear in the PASSporT
        -- in addition to iat, orig, and dest.  If absent, iat, orig,
        -- and dest MUST appear in the PASSporT.
      permittedValues [1] JWTClaimValuesList OPTIONAL,
        -- If the claim name is present, the claim MUST contain one
        -- of the listed values.
      mustExclude [2] JWTClaimNames OPTIONAL }
        -- The listed claim names MUST NOT appear in the PASSporT.
    ( WITH COMPONENTS { ..., mustInclude PRESENT } |
      WITH COMPONENTS { ..., permittedValues PRESENT } |
      WITH COMPONENTS { ..., mustExclude PRESENT } )

    JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues

    JWTClaimValues ::= SEQUENCE {
      claim JWTClaimName,
      values SEQUENCE SIZE (1..MAX) OF UTF8String }

    JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName

    JWTClaimName ::= IA5String

4. Usage Examples 💖

Let's look at some examples 👀. They all use a PASSporT claim called confidence, which can have the values low, medium, and high 🍓. They show the constraints that mustInclude, permittedValues, and mustExclude put in place:

  • Say a certification authority (CA) issues a certificate to an authentication service, and the certificate has an Enhanced JWT Claim Constraints extension with the mustInclude JWTClaimName "confidence" 🎀. Then the authentication service is required to include the confidence claim in every PASSporT it generates and signs 📝. A verification service treats any PASSporT it gets without a confidence claim as invalid 🚨.
  • Say a CA issues a certificate to an authentication service, and the extension has the permittedValues JWTClaimName "confidence" with a permitted "high" value 🌟. Then a verification service treats any PASSporT with a confidence claim whose value isn't high as invalid ❌. Still, a verification service won't treat a PASSporT without a confidence claim at all as invalid, unless "confidence" also appears in mustInclude 🤷‍♀️.
  • Say a CA issues a certificate to an authentication service, and the extension has the mustExclude JWTClaimName "confidence" 🙅‍♀️. Then a verification service treats any PASSporT with a confidence claim as invalid, no matter what the value is 💀.

5. Certificate Extension Example ✨

okay so here's a real certificate that carries the EnhancedJWTClaimConstraints extension 🎀 It's written in the format from [RFC7468], and Figure 2 shows the extension pulled out of it so you can see what's inside. This example sets up three constraints 💅

  1. The "confidence" claim must be present in the PASSporT.
  2. The "confidence" claim must have a value of "high" or "medium".
  3. The "priority" claim must not be present in the PASSporT.
-----BEGIN CERTIFICATE-----
MIICpzCCAk2gAwIBAgIUH7Zd3rQ5AsvOlzLnzUHhrVhDSlswCgYIKoZIzj0EAwIw
KTELMAkGA1UEBhMCVVMxGjAYBgNVBAMMEUJPR1VTIFNIQUtFTiBST09UMB4XDTIx
MDcxNTIxNTIxNVoXDTIyMDcxNTIxNTIxNVowbDELMAkGA1UEBhMCVVMxCzAJBgNV
BAgMAlZBMRAwDgYDVQQHDAdIZXJuZG9uMR4wHAYDVQQKDBVCb2d1cyBFeGFtcGxl
IFRlbGVjb20xDTALBgNVBAsMBFZvSVAxDzANBgNVBAMMBlNIQUtFTjBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABNR6C6nBWRA/fXTglV03aXkXy8hx9oBttVLhsTZ1
IYVRBao4OZhVf/Xv1a3xLsZ6KfdhuylSeAKuCoSbVGojYDGjggEOMIIBCjAMBgNV
HRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDAdBgNVHQ4EFgQUDlG3dxHyzKL/FZfS
PI7rpuueRbswHwYDVR0jBBgwFoAUlToKtrQeFrwwyXpMj1qu3TQEeoEwQgYJYIZI
AYb4QgENBDUWM1RoaXMgY2VydGlmaWNhdGUgY2Fubm90IGJlIHRydXN0ZWQgZm9y
IGFueSBwdXJwb3NlLjAWBggrBgEFBQcBGgQKMAigBhYEMTIzNDBOBggrBgEFBQcB
IQRCMECgDjAMFgpjb25maWRlbmNloSAwHjAcFgpjb25maWRlbmNlMA4MBGhpZ2gM
Bm1lZGl1baIMMAoWCHByaW9yaXR5MAoGCCqGSM49BAMCA0gAMEUCIQCbNR4QK1um
+0vq2CE1B1/W3avYeREsPi/7RKHffL+5eQIgarHot+X9Rl7SOyNBq5X5JyEMx0SQ
hRLkCY3Zoz2OCNQ=
-----END CERTIFICATE-----

Figure 1: Example Certificate

     0  64: SEQUENCE {
     2  14:   [0] {
     4  12:     SEQUENCE {
     6  10:       IA5String 'confidence'
          :       }
          :     }
    18  32:   [1] {
    20  30:     SEQUENCE {
    22  28:       SEQUENCE {
    24  10:         IA5String 'confidence'
    36  14:         SEQUENCE {
    38   4:           UTF8String 'high'
    44   6:           UTF8String 'medium'
          :           }
          :         }
          :       }
          :     }
    52  12:   [2] {
    54  10:     SEQUENCE {
    56   8:       IA5String 'priority'
          :       }
          :     }
          :   }

Figure 2: Example EnhancedJWTClaimConstraints Extension

6. Guidance to Certification Authorities 👑

heads up CAs 🫶 The EnhancedJWTClaimConstraints extension from this document and the JWTClaimConstraints extension from [RFC8226] MUST NOT both appear in the same certificate. Never both, no exceptions 🙅‍♀️

If the situation calls for mustExclude constraints, then the EnhancedJWTClaimConstraints extension is the only extension that can express those constraints. It's the only one that can do it, so no other option.

If the situation does not call for mustExclude constraints, then either the EnhancedJWTClaimConstraints extension or the JWTClaimConstraints extension can express the constraints. Until support for the EnhancedJWTClaimConstraints extension becomes widely implemented, the use of the JWTClaimConstraints extension may be more likely to be supported. ngl this part is a guess 🙈 It's based on the presumption that the first specified extension will be implemented more widely in the next few years.

7. IANA Considerations 🧚

This document makes use of object identifiers for the Enhanced JWT Claim Constraints certificate extension defined in Section 3 and the ASN.1 module identifier defined in Appendix A. Therefore, IANA has made the following assignments within the "Structure of Management Information (SMI) Numbers (MIB Module Registrations)" registry.

For the Enhanced JWT Claim Constraints certificate extension in the "SMI Security for PKIX Certificate Extension" (1.3.6.1.5.5.7.1) registry:

              +=========+============================+
              | Decimal | Description                |
              +=========+============================+
              | 33      | id-pe-eJWTClaimConstraints |
              +---------+----------------------------+

                                 Table 1

For the ASN.1 module identifier in the "SMI Security for PKIX Module Identifier" (1.3.6.1.5.5.7.0) registry:

              +=========+==================================+
              | Decimal | Description                      |
              +=========+==================================+
              | 101     | id-mod-eJWTClaimConstraints-2021 |
              +---------+----------------------------------+

                                 Table 2

8. Security Considerations 💀

this section is serious business, so read it all 🔥

For further information on certificate security and practices, see [RFC5280], especially the Security Considerations section.

Since non-critical certificate extensions are ignored by implementations that do not recognize the extension object identifier (OID), constraints on PASSporT validation will only be applied by relying parties that recognize the EnhancedJWTClaimConstraints extension. So if a relying party doesn't know this extension, it just skips the constraints entirely 😭

The Enhanced JWT Claim Constraints certificate extension can be used by certificate issuers to provide limits on the acceptable PASSporTs that can be accepted by verification services. Enforcement of these limits depends upon proper implementation by the verification services. The digital signature on the PASSporT data structure will be valid even if the limits are violated. So a signature can check out fine while the limits get broken 🙃

Use of the Enhanced JWT Claim Constraints certificate extension permittedValues constraint is most useful when the claim definition allows a specified set of values. In this way, all of the values that are not listed in the JWTClaimValuesList are prohibited in a valid PASSporT.

Certificate issuers must take care when imposing constraints on the PASSporT claims and the claim values that can be successfully validated; some combinations can prevent any PASSporT from being successfully validated by the certificate. For example, an entry in mustInclude and an entry in mustExclude for the same claim will prevent successful validation on any PASSporT. 🚨

Certificate issuers SHOULD NOT include an entry in mustExclude for the "rcdi" claim for a certificate that will be used with the PASSporT Extension for Rich Call Data defined in [STIR-PASSPORT-RCD]. Excluding this claim would prevent the integrity protection mechanism from working properly.

Certificate issuers must take care when performing certificate renewal [RFC4949] to include exactly the same Enhanced JWT Claim Constraints certificate extension in the new certificate as the old one. Renewal usually takes place before the old certificate expires, so there is a period of time where both the new certificate and the old certificate are valid. If different constraints appear in the two certificates with the same public key, some PASSporTs might be valid when one certificate is used and invalid when the other one is used. 😵‍💫

9. References 📚

9.1. Normative References

9.2. Informative References

Appendix A. ASN.1 Module ✨

okay so this appendix is where the ASN.1 [X.680] definitions for the Enhanced JWT Claim Constraints certificate extension live 🎀 the module is compatible with the ASN.1 specs published in 2015, so it's giving official and organized 💅

this module imports ASN.1 from [RFC5912] 🦋

<CODE BEGINS>
EnhancedJWTClaimConstraints-2021
  { iso(1) identified-organization(3) dod(6) internet(1)
    security(5) mechanisms(5) pkix(7) id-mod(0)
    id-mod-eJWTClaimConstraints-2021(101) }

DEFINITIONS EXPLICIT TAGS ::= BEGIN

IMPORTS

id-pe
FROM PKIX1Explicit-2009  -- From RFC 5912
  { iso(1) identified-organization(3) dod(6) internet(1)
    security(5) mechanisms(5) pkix(7) id-mod(0)
    id-mod-pkix1-explicit-02(51) }

EXTENSION
FROM PKIX-CommonTypes-2009  -- From RFC 5912
  { iso(1) identified-organization(3) dod(6) internet(1)
    security(5) mechanisms(5) pkix(7) id-mod(0)
    id-mod-pkixCommon-02(57) } ;

-- Enhanced JWT Claim Constraints Certificate Extension

ext-eJWTClaimConstraints EXTENSION ::= {
  SYNTAX EnhancedJWTClaimConstraints
  IDENTIFIED BY id-pe-eJWTClaimConstraints }

id-pe-eJWTClaimConstraints OBJECT IDENTIFIER ::= { id-pe 33 }

EnhancedJWTClaimConstraints ::= SEQUENCE {
  mustInclude [0] JWTClaimNames OPTIONAL,
    -- The listed claim names MUST appear in the PASSporT
    -- in addition to iat, orig, and dest.  If absent, iat, orig,
    -- and dest MUST appear in the PASSporT.
  permittedValues [1] JWTClaimValuesList OPTIONAL,
    -- If the claim name is present, the claim MUST contain one
    -- of the listed values.
  mustExclude [2] JWTClaimNames OPTIONAL }
    -- The listed claim names MUST NOT appear in the PASSporT.
( WITH COMPONENTS { ..., mustInclude PRESENT } |
  WITH COMPONENTS { ..., permittedValues PRESENT } |
  WITH COMPONENTS { ..., mustExclude PRESENT } )

JWTClaimValuesList ::= SEQUENCE SIZE (1..MAX) OF JWTClaimValues

JWTClaimValues ::= SEQUENCE {
  claim JWTClaimName,
  values SEQUENCE SIZE (1..MAX) OF UTF8String }

JWTClaimNames ::= SEQUENCE SIZE (1..MAX) OF JWTClaimName

JWTClaimName ::= IA5String

END
<CODE ENDS>
the MUST and MUST NOT words in those comments are the real requirements, so the module has to be implemented exactly as written 🔥

Acknowledgements ✨

huge thank you to Chris Wendt 🫶 he's the one who spotted why the Enhanced JWT Claim Constraints certificate extension was needed in the first place 🙌

thanks also to Ben Campbell, Theresa Enghardt, Ben Kaduk, Erik Kline, Éric Vyncke, and Rob Wilton for their thoughtful reviews and comments 💜 the document is so much better because of their work, no cap 🌸

Author's Address 💖

Russ Housley
Vigil Security, LLC
516 Dranesville Road
Herndon, VA 20170
United States of America

Email: housley@vigilsec.com
📦 where this page comes from