]> Somos Inc.

US chris@appliedbits.com

Somos Inc.

US davidhancock.ietf@gmail.com

sec acme, STIR This document defines an authority token profile for the validation of JWTClaimConstraints and EnhancedJWTClaimConstraints certificate extensions within the Automated Certificate Management Environment (ACME) protocol. This profile is based on the Authority Token framework and establishes the specific ACME identifier type, challenge mechanism, and token format necessary to authorize a client to request a certificate containing these constraints.

Introduction The validation of certificate extensions that constrain the use of a certificate's credentials, such as the JWTClaimConstraints extension defined in and the EnhancedJWTClaimConstraints extension defined in , is critical for defining the scope of an issued certificate. This document specifies an authority token profile for validating these constraints, modeled after the authority token framework established in and the TNAuthList validation defined in . This profile facilitates proper delegation and authorization for entities requesting certificates under ACME. It defines the use of the JWTClaimConstraints Authority Token in the ACME challenge to prove an authoritative or trusted use of the contents of the JWTClaimConstraints and EnhancedJWTClaimConstraints extensions based on the issuer of the token. This document is intended for use by Secure Telephone Identity (STI) Certification Authorities. In this ecosystem, certificates contain telephone-number-related (TNAuthList) extensions and JWTClaimConstraints extensions defined in and , and certificate issuance is governed by a set of STI-specific Token Authorities. The TNAuthList Authority Token profile () is the parallel specification for telephone number authorization in this ecosystem and is already widely deployed. This document follows the same pattern to address authorization of the JWTClaimConstraints and EnhancedJWTClaimConstraints extensions. ACME implementers unfamiliar with the STIR ecosystem can treat the validation of the JWTClaimConstraints token value as a domain-specific authorization step analogous to TNAuthList validation: the ACME wire protocol mechanics are identical, and the Token Authority is responsible for the domain-specific semantic validation described in and . The normative requirements of this document apply to implementers of ACME clients and ACME servers: the new-order identifier type (), the challenge and Authority Token exchange, the Authority Token structure, and the server-side validation rules in . To an ACME client or server, the JWTClaimConstraints value carried in the identifier and in the token's "tkvalue" is an opaque octet string that is transported, compared octet-by-octet, and never parsed. The internal structure of that value, and the rules governing what a Token Authority may place in it, are a STIR ecosystem concern governed by and ; that material appears in this document (for example, in and ) as informative background for implementers of Token Authorities, and is not needed to implement the ACME client or ACME server role. This document also discusses the ability for an authority to authorize the creation of CA types of certificates for delegation as defined in .

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 when, and only when, they appear in all capitals, as shown here.

ACME new-order Identifiers for JWTClaimConstraints In , Section 7 defines the procedure that an ACME client uses to order a new certificate from a Certification Authority (CA). This draft defines a new type of identifier object called JWTClaimConstraints. A JWTClaimConstraints identifier contains the Token Claim Constraints information to be populated in the JWTClaimConstraints or EnhancedJWTClaimConstraints of the new certificate. For the JWTClaimConstraints identifier, the new-order request includes a type set to the string "JWTClaimConstraints". The value of the JWTClaimConstraints identifier MUST be set to the details of the JWTClaimConstraints or EnhancedJWTClaimConstraints extension requested. The format of the string that represents the JWTClaimConstraints MUST be constructed using base64url encoding, as per base64url encoding described in Section 5 of according to the profile specified in JSON Web Signature in Section 2 of . The base64url encoding MUST NOT include any padding characters and the JWTClaimConstraints ASN.1 object MUST be encoded using DER encoding rules. DER (the canonical subset of BER) and unpadded base64url together uniquely determine the octet sequence for a given JWTClaimConstraints or EnhancedJWTClaimConstraints ASN.1 value. The same canonical encoding is used as the "tkvalue" string in the "atc" claim of the corresponding Authority Token, so that the value carried in the new-order identifier and the value carried in the token are octet-by-octet identical and can be compared as described in , step 5. An example of an ACME order object "identifiers" field containing a JWTClaimConstraints certificate:

where the "value" object string represents the arbitrary length base64url encoded string. A full new-order request would look as follows,

On receiving a valid new-order request, the ACME server creates an authorization object, Section 7.1.4, containing the challenge that the ACME client must satisfy to demonstrate authority for the identifiers specified by the new order (in this case, the JWTClaimConstraints identifier). The CA adds the authorization object URL to the "authorizations" field of the order object, and returns the order object to the ACME client in the body of a 201 (Created) response.

JWTClaimConstraints Authorization On receiving the new-order response, the ACME client queries the referenced authorization object to obtain the challenges for the identifier contained in the new-order request.

;rel="index" { "status": "pending", "expires": "2025-01-08T00:00:00Z", "identifier": { "type": "JWTClaimConstraints", "value": "F83n2a...avn27DN3" }, "challenges": [ { "type": "tkauth-01", "tkauth-type": "atc", "token-authority": "https://authority.example.org", "url": "https://example.com/acme/chall/prV_B7yEyA4", "status": "pending", "token": "IlirfxKKXAsHtmzK29Pj8A" } ] } ]]>

When processing a certificate order containing an identifier of type "JWTClaimConstraints", a CA uses the Authority Token challenge type of "tkauth-01" with a "tkauth-type" of "atc", defined in , to verify that the requesting ACME client has authenticated and authorized control over the requested resources represented by the "JWTClaimConstraints" value. The challenge "token-authority" parameter is OPTIONAL. If a "token-authority" parameter is present, the ACME client MAY use this value to identify the URL representing the Token Authority that will provide the JWTClaimConstraints Authority Token response to the challenge. If the "token-authority" parameter is not present, the ACME client is expected to have been configured out of band with the location of the Token Authority. The "token-authority" parameter is advisory to the ACME client; the ACME server does not use it when validating the challenge response (), where trust in the token is established through the issuer certificate referenced by the token's "x5u" or "x5c" header parameter. The ACME client responds to the challenge by posting the JWTClaimConstraints Authority Token to the challenge URL identified in the returned ACME authorization object.

The "tkauth" field in the challenge response object is specific to the tkauth-01 challenge type. When responding to a challenge for a JWTClaimConstraints identifier, this field SHALL contain the JWTClaimConstraints Authority Token defined in the next section.

JWTClaimConstraints Authority Token The JWTClaimConstraints Authority Token is a profile instance of the ACME Authority Token defined in . This section defines the structure of the token (its data model); the rules an ACME server applies to validate it are specified in . The JWTClaimConstraints Authority Token Protected header MUST comply with the Authority Token Protected header as defined in .

JWTClaimConstraints Authority Token Payload The JWTClaimConstraints Authority Token Payload MUST include the mandatory claims "exp", "jti", and "atc", and MAY include the optional claims defined for the Authority Token.

"iss" claim The "iss" claim is an optional claim defined in Section 4.1.1. It can be used as a URL identifying the Token Authority that issued the JWTClaimConstraints Authority Token beyond the "x5u" or other Header claims that identify the location of the certificate or certificate chain of the Token Authority used to validate the JWTClaimConstraints Authority Token.

"exp" claim The "exp" claim, defined in Section 4.1.4, MUST be included and contains the DateTime value of the ending date and time that the JWTClaimConstraints Authority Token expires.

"jti" claim The "jti" claim, defined in Section 4.1.7, MUST be included and contains a unique identifier for this JWTClaimConstraints Authority Token transaction.

"atc" claim The "atc" claim MUST be included and is defined in . It contains a JSON object with the following elements: a "tktype" key with a string value equal to "JWTClaimConstraints" to represent a JWTClaimConstraints profile of the authority token defined by this document. "tktype" is a required key and MUST be included. a "tkvalue" key with a string value equal to the base64url encoding of the JWTClaimConstraints or EnhancedJWTClaimConstraints certificate extension ASN.1 object using DER encoding rules. "tkvalue" is a required key and MUST be included. a "ca" key with a boolean value set to false (since the JWTClaimConstraints extension is applicable only to end-entity certificates). "ca" is an optional key; if not included, the "ca" value is considered false by default. a "fingerprint" key is constructed as defined in Section 8.1 corresponding to the computation of the fingerprint step using the ACME account key credentials. "fingerprint" is a required key and MUST be included. An example of the JWTClaimConstraints Authority Token is as follows:

Acquiring the token from the Token Authority Following Section 5, the authority token should be acquired using a RESTful HTTP POST transaction as follows:

The request will pass the account id as a string in the request parameter "id". Note that this account identifier refers to the ACME client's account with the Token Authority, and is distinct from the ACME account used with the CA. There is assumed to be a corresponding authentication procedure that can be verified for the success of this transaction, for example, an HTTP Authorization header field containing valid authorization credentials as defined in Section 14.8. The body of the POST request MUST contain a JSON object with key value pairs corresponding to values that are requested as the content of the claims in the issued token. As an example, the body SHOULD contain a JSON object as follows:

The response to the POST request if successful returns a 200 OK with a JSON body that contains, at a minimum, the JWTClaimConstraints Authority Token as a JSON object with a key of "token" and the base64url encoded string representing the atc token. JSON is easily extensible, so users of this specification may want to pass other pieces of information relevant to a specific application. An example successful response would be as follows:

The ACME client then uses the value of the "token" field as the "tkauth" field in the challenge response POST to the ACME challenge URL, as described in Section 4. If the request is not successful, the response should indicate the error condition. Specifically, for the case that the authorization credentials are invalid or if the Account ID provided does not exist, the response code MUST be 403 - Forbidden. Other 4xx and 5xx responses MUST follow standard HTTP error condition conventions.

Token Authority Responsibilities When creating the JWTClaimConstraints Authority Token, the Token Authority MUST validate that the information contained in the ASN.1 JWTClaimConstraints accurately represents the corresponding JWTClaimConstraint resources the requesting party is authorized to represent based on their pre-established and verified secure relationship between the Token Authority and the requesting party. The fingerprint in the token request is not meant to be verified by the Token Authority. Rather, it is meant to be signed as part of the token so that the party that requests the token can, as part of the challenge response, allow the ACME server to validate that the token requested and used came from the same party that controls the ACME client.

Scope of the JWTClaimConstraints Because this specification involves the JWTClaimConstraints and EnhancedJWTClaimConstraints extensions, the client MAY request an Authority Token with some subset of its own authority as the JWTClaimConstraints provided in the "tkvalue" element of the "atc" JSON object. These extensions define a limited scope of the claims and claim values the client is authorized to assert in PASSporTs signed with the resulting certificate, using the following components: mustInclude (context tag [0], ) is a list of claim names that MUST be present. permittedValues (context tag [1], ) is a list of claim names, each paired with the set of values that claim is permitted to take. mustExclude (context tag [2], ) is a list of claim names that MUST NOT be present. This component is only available in the EnhancedJWTClaimConstraints extension, so the enhanced form is needed only when the optional ("extended") claims must be constrained; otherwise the JWTClaimConstraints extension of is sufficient. The Token Authority validates the requested JWTClaimConstraints or EnhancedJWTClaimConstraints value against the resources the requesting party is authorized to represent (see Section 5.3) and places that value in the token. The ACME server then compares the token value to the new-order identifier value octet-by-octet (, step 5) and does not parse or interpret the ASN.1 content. Informative examples are provided in .

ACME Challenges requiring multiple Authority Tokens The ACME new-order request can include multiple identifiers, each of which is authorized separately. With the introduction of this specification, for STIR certificates , a certificate order can require two Authority Token identifier types: The JWTClaimConstraints identifier defined in this document, and The TNAuthList identifier defined in . Other Authority Token types can be introduced in future Authority Token profile specifications with similar requirements. This section describes scenarios where a new-order request contains both of these identifier types. In such cases, the CA requires the ACME client to provide both a JWTClaimConstraints Authority Token and a TNAuthList Authority Token as part of the challenge response. The TNAuthList Authority Token authorizes the token holder to obtain certificates containing a TNAuthList extension whose scope is less than or equal to the scope of the TNAuthList identifier in the token. The JWTClaimConstraints Authority Token authorizes the token holder to obtain a certificate containing a JWTClaimConstraints or EnhancedJWTClaimConstraints extension, provided that the extension is within the scope of the JWTClaimConstraints identifier in the token. Since these two certificate extensions constrain the resources and claims available to the certificate, there is an inherent interaction between these two types of Authority Tokens. The "value" field of the JWTClaimConstraints identifier, and the corresponding "tkvalue" in the "atc" claim, is a base64url-encoded DER representation of a JWTClaimConstraints or EnhancedJWTClaimConstraints ASN.1 object as defined in and . From the ACME server's perspective this value is opaque: validation step 5 in requires only that the value in the token is octet-by-octet identical to the value in the order. The semantic content of the extension — which claims are permitted or excluded, and for which telephone numbers — is a STIR ecosystem concern governed by and , and is validated by the Token Authority prior to token issuance (see Section 5.3). In particular, the ACME server does not parse or cross-check the JWTClaimConstraints and TNAuthList extensions for mutual consistency: if a requested JWTClaimConstraints value constrains a claim such as "orig" to telephone numbers that are inconsistent with the certificate's TNAuthList, no PASSporT can satisfy both constraints during verification (governed by and ), so such a certificate fails verification for all calls. The ACME account holder that submits the CSR is responsible for recognizing this potential conflict and for requesting TNAuthList and JWTClaimConstraints extensions that are mutually compatible and correctly authorized; this places authority and accountability for the certificate's contents with the requesting party, which is a desirable security property. Informative examples of JWTClaimConstraints ASN.1 structures, their DER encodings, and corresponding base64url values are provided in .

ACME Procedures when Challenge requires two Authority Tokens Sections 3 and 4 describe the ACME procedures for issuing a certificate based on a single JWTClaimConstraints identifier. This section describes how these procedures are modified to support the case where the new-order request contains both a TNAuthList and JWTClaimConstraints identifier. A new-order request contains at most one JWTClaimConstraints identifier and at most one TNAuthList identifier. First, the "identifiers" field in the new-order request includes both identifier types:

The CA includes two "authorizations" URLs in the 201 (Created) response to the new-order request, one for each identifier:

The ACME client then queries each "authorizations" URL as shown in Section 4. The CA returns the Authority Token challenge for each identifier. The ACME client responds to each challenge by providing an Authority Token of the appropriate type.

Validating the JWTClaimConstraints Authority Token Upon receiving a response to the challenge, the ACME server MUST perform the following steps to determine the validity of the response. Steps 1 through 3 and steps 6 through 8 are general STIR Authority Token validation steps, applicable to any STIR Authority Token profile and mirroring the TNAuthList validation defined in . Steps 4 and 5 are specific to the JWTClaimConstraints profile. The semantic validation of whether the JWTClaimConstraints or EnhancedJWTClaimConstraints content accurately reflects the requesting party's authorized resources is the responsibility of the Token Authority prior to issuing the token (see Section 5.3), and is governed by and . Verify that the value of the "atc" claim is a well-formed JSON object containing the mandatory key values ("tktype", "tkvalue", "fingerprint"). Verify Token Issuer: The certificate referenced by the token's "x5u" or "x5c" header parameter MUST represent a Token Authority that the ACME server is configured to trust as an issuer of Authority Tokens for the ecosystem. assumes a preexisting trust relationship between the CA and the Token Authority; the specific trust anchors, and any ecosystem-specific requirements on the Token Authority certificate, are established by the deploying ecosystem (for example, the STIR governance framework) and are out of scope for this document. If an "x5u" parameter is present, verify that it is an HTTPS URL referencing such a certificate. If an "x5c" parameter is present, verify that the certificate array contains such a certificate. If neither "x5u" nor "x5c" is present, or the referenced certificate is not one the ACME server trusts as an Authority Token issuer for the ecosystem, this step MUST fail. Verify Signature: Verify the JWTClaimConstraints Authority Token signature using the public key of the certificate referenced by the token's "x5u" or "x5c" parameter. Verify Token Type: Verify that the "atc" claim contains a "tktype" identifier with the value "JWTClaimConstraints". Verify Constraints Match: Verify that the value of the "atc" claim "tkvalue" is octet-by-octet identical to the "value" of the JWTClaimConstraints identifier in the original new-order request. Both values are the canonical encoding defined in : the base64url encoding (without padding) of the DER encoding of a JWTClaimConstraints or EnhancedJWTClaimConstraints ASN.1 object. The ACME server MUST perform this verification as a direct octet-by-octet comparison of the two base64url strings, and MUST NOT decode, re-encode, canonicalize, normalize, or otherwise transform either value before comparison. If either value contains characters outside the base64url alphabet defined in Section 5 of , contains padding characters ("="), or differs from the other in any octet, this step MUST fail. See for discussion of identifier comparison considerations. Verify Claims: Verify that the "exp" claim is present and that the token has not expired relative to the ACME server's current time; the ACME server MAY allow for a small amount of clock skew according to local policy. Verify that the "jti" claim is present. If the "exp" claim is absent, the token has expired, or the "jti" claim is absent, this step MUST fail. Verify Account Control: Verify that the "atc" claim "fingerprint" is valid and matches the ACME account key () of the client making the request. Verify CA Flag: Verify that the "atc" claim "ca" identifier boolean corresponds to the CA boolean in the Basic Constraints extension in the Certificate Signing Request (CSR) for either a CA certificate or an end-entity certificate. If all steps in the token validation process pass, then the ACME server MUST set the challenge object "status" to "valid". If any step of the validation process fails, the ACME server MUST set the "status" in the challenge object to "invalid" and SHOULD include an "error" field containing a problem document (, Section 6.7); the "urn:ietf:params:acme:error:unauthorized" error type is generally appropriate. The ACME client then handles the failed authorization as described in .

Using ACME-issued Certificates with JSON Web Signature JSON Web Signature (JWS) objects can include an "x5u" header parameter to refer to a certificate for signature validation. In order to support this usage, the Certificate Authority (CA) MAY host the newly issued certificate and provide a URL that the ACME client owner can directly reference in the "x5u" header parameter of their signed JWS objects. To facilitate this, the CA MAY add a newly defined field called "x5u" to the 200 (OK) order object response when the certificate is ready for the finalize request: x5u (optional, string): A URL that can be used to reference the certificate in the "x5u" parameter of a JWS object. The CA SHOULD ensure that this URL remains retrievable for as long as relying parties may need the certificate to validate signatures on JWS objects that reference it, typically at least until the certificate expires. An example of a 200 (OK) response containing the new "x5u" field:

;rel="index" Location: https://example.com/acme/order/TOlocE8rfgo { "status": "valid", "expires": "2016-01-20T14:09:07.99Z", "notBefore": "2016-01-01T00:00:00Z", "notAfter": "2016-01-08T00:00:00Z", "identifiers": [ {"type": "JWTClaimConstraints", "value": "F83n2a...avn27DN3"} ], "authorizations": ["https://example.com/acme/authz/1234"], "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize", "certificate": "https://example.com/acme/cert/mAt3xBGaobw", "x5u": "https://example.com/cert-repo/giJI53km23.pem" } ]]>

Security Considerations The token represented by this document has the credentials to represent JWTClaimConstraints and EnhancedJWTClaimConstraints, which constrain the resources and claims a certificate holder can assert. This token carries credentials that constrain the resources and claims a certificate holder can assert, so its disclosure to a bad actor could enable impersonation or misuse of the constrained resources. The token MUST be transported using the encrypted transport already required by this document, and implementations SHOULD follow the JWT best current practices in and the security considerations of for its creation, handling, and storage. This document inherits the security properties of . Implementations SHOULD follow the best practices identified in for cryptographic security. This document only specifies SHA256 for the fingerprint hash. However, the syntax of the fingerprint object would permit other algorithms if, due to concerns about algorithmic agility, a more robust algorithm were required at a future time. Future specifications CAN define new algorithms for the fingerprint object as needed.

Identifier Comparison Considerations The "value" field of the JWTClaimConstraints identifier and the "tkvalue" string in the "atc" claim are opaque identifiers from the ACME server's perspective. describes a class of vulnerabilities that arises when implementations apply ad hoc normalization, decoding, or "equivalence" judgments to identifier values during comparison: differences between what an implementation considers equivalent and what an attacker can produce can be turned into authorization bypasses. To eliminate this class of vulnerability for this profile, this document requires that both values be produced in a single canonical form (DER under unpadded base64url, as specified in ) and that the ACME server's comparison in , step 5, be a direct octet-by-octet comparison with no intervening transformation. Implementations MUST NOT be permissive about variations such as padded base64url, alternate base64url alphabets, BER encodings that are not also valid DER, embedded whitespace, or differences in canonical ordering inside ASN.1 SET constructs (DER fixes the ordering). Any deviation from the canonical form yields a different identifier value, and the validation step MUST fail. Implementations SHOULD perform the octet-by-octet comparison in constant time. While the values compared in this profile are not themselves secret, constant-time comparison removes a class of timing side channels that have caused issues in other identifier-comparison contexts.

IANA Considerations This document requests the addition of a new identifier object type to the "ACME Identifier Types" registry defined in Section 9.7.7 of .

This document also registers the "tkauth-01" validation method for use with the "JWTClaimConstraints" identifier type in the "ACME Validation Methods" registry defined in Section 9.7.8 of . This registration is required by Section 3 of , which specifies that use of the "tkauth-01" validation method with an ACME identifier type other than "TNAuthList" requires a new registration in that registry.

Acknowledgements We would like to thank ACME and STIR working groups for valuable contributions to the authority token framework used in this document.

This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation. JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. In order to prevent the impersonation of telephone numbers on the Internet, some kind of credential system needs to exist that cryptographically asserts authority over telephone numbers. This document describes the use of certificates in establishing authority over telephone numbers, as a component of a broader architecture for managing telephone numbers as identities in protocols like SIP. Public Key Infrastructure using X.509 (PKIX) certificates are used for a number of purposes, the most significant of which is the authentication of domain names. Thus, certification authorities (CAs) in the Web PKI are trusted to verify that an applicant for a certificate legitimately represents the domain name(s) in the certificate. As of this writing, this verification is done through a collection of ad hoc mechanisms. This document describes a protocol that a CA and an applicant can use to automate the process of verification and certificate issuance. The protocol also provides facilities for other certificate management functions, such as certificate revocation. RFC 8226 specifies the use of certificates for Secure Telephone Identity Credentials; these certificates are often called "Secure Telephone Identity Revisited (STIR) Certificates". RFC 8226 provides a certificate extension to constrain the JSON Web Token (JWT) claims that can be included in the Personal Assertion Token (PASSporT), as defined in RFC 8225. If the PASSporT signer includes a JWT claim outside the constraint boundaries, then the PASSporT recipient will reject the entire PASSporT. This document updates RFC 8226; it provides all of the capabilities available in the original certificate extension as well as an additional way to constrain the allowable JWT claims. The enhanced extension can also provide a list of claims that are not allowed to be included in the PASSporT. Some proposed extensions to the Automated Certificate Management Environment (ACME) rely on proving eligibility for certificates through consulting an external authority that issues a token according to a particular policy. This document specifies a generic Authority Token Challenge for ACME that supports subtype claims for different identifiers or namespaces that can be defined separately for specific applications. This document defines a profile of the Automated Certificate Management Environment (ACME) Authority Token for the automated and authorized creation of certificates for Voice over IP (VoIP) telephone providers to support Secure Telephone Identity (STI) using the TNAuthList defined by STI certificates. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Identifiers such as hostnames, URIs, IP addresses, and email addresses are often used in security contexts to identify security principals and resources. In such contexts, an identifier presented via some protocol is often compared using some policy to make security decisions such as whether the security principal may access the resource, what level of authentication or encryption is required, etc. If the parties involved in a security decision use different algorithms to compare identifiers, then failure scenarios ranging from denial of service to elevation of privilege can result. This document provides a discussion of these issues that designers should consider when defining identifiers and protocols, and when constructing architectures that use multiple protocols. JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security tokens that contain a set of claims that can be signed and/or encrypted. JWTs are being widely used and deployed as a simple security token format in numerous protocols and applications, both in the area of digital identity and in other application areas. This Best Current Practices document updates RFC 7519 to provide actionable guidance leading to secure implementation and deployment of JWTs. The Secure Telephone Identity Revisited (STIR) certificate profile provides a way to attest authority over telephone numbers and related identifiers for the purpose of preventing telephone number spoofing. This specification details how that authority can be delegated from a parent certificate to a subordinate certificate. This supports a number of use cases, including those where service providers grant credentials to enterprises or other customers capable of signing calls with STIR.

JWTClaimConstraints Identifier Value Examples This appendix provides informative examples of JWTClaimConstraints and EnhancedJWTClaimConstraints ASN.1 structures as defined in and , along with their DER encodings and base64url values as used in the ACME identifier "value" field and the "tkvalue" of the "atc" claim. These examples are intended for implementers of STI Token Authorities and certificate requestors in the STIR ecosystem. ACME server implementations treat the identifier value as opaque and are not required to parse or validate its internal structure. Note: single-quote delimiters in the ASN.1 notation below denote string values; inner double quotes are part of the JSON-formatted claim values as defined in .

No Extended Claims Authorized In this case, the requestor is authorized to use a set of telephone numbers but no optional claim information. The EnhancedJWTClaimConstraints extension uses a mustExclude constraint to prohibit all optional claims relevant to the application.

DER encoding (53 bytes, hex):

base64url value:

A simpler alternative for requestors not authorized to include optional claims is to submit a new-order request containing only a TNAuthList identifier. In this case, the absence of a JWTClaimConstraints identifier MAY trigger local policy in the CA to include a restrictive EnhancedJWTClaimConstraints extension in the issued certificate.

Extended Claims Authorized (Uniform Constraints) In this case, the requestor is authorized to assert a specific set of claim information that applies uniformly across all authorized telephone numbers. The extension uses a permittedValues constraint for the authorized claims and a mustExclude constraint for the remainder.

DER encoding (108 bytes, hex):

base64url value:

Extended Claims Constrained to Specific Telephone Numbers In this case, the requestor is authorized to assert a set of claims only for calls that originate from a specific set of telephone numbers. This is expressed by constraining the "orig" claim in permittedValues to those telephone numbers, alongside the other permitted claims. See Section 5.5 for why the CA does not need to cross-check this constraint against the certificate's TNAuthList.

DER encoding (149 bytes, hex):

base64url value: