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

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 has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9118.¶

Copyright Notice

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) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶

1. Introduction

The use of certificates [RFC5280] in establishing authority over telephone numbers is described in [RFC8226]. These certificates are often called "STIR Certificates". STIR certificates are an important element of the overall system that prevents the impersonation of telephone numbers on the Internet.¶

Section 8 of [RFC8226] provides a certificate extension to constrain the JSON Web Token (JWT) claims that can be included in the Personal Assertion Token (PASSporT) [RFC8225]. If the PASSporT signer includes a JWT claim outside the constraint boundaries, then the PASSporT recipient will reject the entire PASSporT.¶

This document defines an enhanced JWTClaimConstraints certificate extension, which provides all of the capabilities available in the original certificate extension as well as an additional way to constrain the allowable JWT claims. That is, the enhanced extension can provide 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] describes the situation where service providers issue a STIR certificate to enterprises or other customers to sign PASSporTs, and the Enhanced JWT Claim Constraints certificate extension can be used to prevent specific claims from being included in PASSporTs and accepted as valid by the PASSporT recipient.¶

The JWT Claim Constraints certificate extension defined in [RFC8226] provides a list of claims that must be included in a valid PASSporT as well as a list of permitted values for selected claims. The Enhanced JWT Claim Constraints certificate extension defined in this document includes those capabilities and adds a list of claims that must not be included in a valid PASSporT.¶

2. Terminology

The key 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.¶

3. Enhanced JWT Claim Constraints Syntax

The Enhanced JWT Claim Constraints certificate extension is non-critical, applicable only to end-entity certificates, and 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, but, when present, it constrains the JWT claims that authentication services may include in the PASSporT objects they sign. Constraints are applied by certificate issuers and enforced by recipients when validating PASSporT claims as follows:¶

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 the following object identifier (OID):¶

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

The Enhanced JWT Claim Constraints certificate extension has the following 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

Consider these usage examples with a PASSporT claim called "confidence" with values "low", "medium", and "high". These examples illustrate the constraints that are imposed by mustInclude, permittedValues, and mustExclude:¶

5. Certificate Extension Example

A certificate containing an example of the EnhancedJWTClaimConstraints certificate extension is provided in Figure 1. The certificate is provided in the format described in [RFC7468]. The example of the EnhancedJWTClaimConstraints extension from the certificate is shown in Figure 2. The example imposes three constraints:¶

-----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-----

  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'
       :       }
       :     }
       :   }

6. Guidance to Certification Authorities

The EnhancedJWTClaimConstraints extension specified in this document and the JWTClaimConstraints extension specified in [RFC8226] MUST NOT both appear in the same certificate.¶

If the situation calls for mustExclude constraints, then the EnhancedJWTClaimConstraints extension is the only extension that can express the constraints.¶

On the other hand, if the situation does not call for mustExclude constraints, then either the EnhancedJWTClaimConstraints extension or the JWTClaimConstraints extension can express the constraints. Until such time as support for the EnhancedJWTClaimConstraints extension becomes widely implemented, the use of the JWTClaimConstraints extension may be more likely to be supported. This guess is 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:¶

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

8. Security Considerations

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.¶

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.¶

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.¶

Appendix A. ASN.1 Module

This appendix provides the ASN.1 [X.680] definitions for the Enhanced JWT Claim Constraints certificate extension. The module defined in this appendix is compatible with the ASN.1 specifications published in 2015.¶

This ASN.1 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>

Acknowledgements

Many thanks to Chris Wendt for his insight into the need for the for the Enhanced JWT Claim Constraints certificate extension.¶

Thanks to Ben Campbell, Theresa Enghardt, Ben Kaduk, Erik Kline, Éric Vyncke, and Rob Wilton for their thoughtful review and comments. The document is much better as a result of their efforts.¶

Author's Address