JWTClaimConstraints profile of ACME Authority Token

Introduction The validation of JWTClaimConstraints as part of an STI certificate defined in is critical for ensuring the integrity and scope of claims used in PASSporTs. This document specifies an authority token profile for validating JWTClaimConstraints, 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 and similar frameworks. This Authority Token profile specifically addresses the inclusions of the STI certificate extensions JWTClaimConstraints, as defined in , and EnhancedJWTClaimConstraints, as defined in . The STI certificate credentials are used to sign PASSporTs , which can be carried in using protocols such as SIP . This document 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 based on the issuer of the token. The Certification Authority (CA) issuing the STI Certificate can be informed of the proper use and contents of the JWTClaimConstraints extension based on the STI eco-system policies, best practices, or authoritative information which is out of scope of this document and will be defined by the STI eco-system. This document also discusses the ability for a telephone 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). The new-order request contains an "identifiers" field that specifies the identifier objects the order corresponds to. 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 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. An example of an ACME order object "identifiers" field containing a JWTClaimConstraints certificate would look as follows,

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 as shown in the following example request and response.

;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://boulder.example.com/acme/chall/prV_B7yEyA4", "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" 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 and is only used in cases where the VoIP telephone network requires the CA to identify the Token Authority. If a "token-authority" parameter is present, then the ACME client MAY use the "token-authority" 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, then the ACME client MUST identify the Token Authority based on locally configured information or local policies. The ACME client responds to the challenge by posting the JWTClaimConstraints Authority Token to the challenge URL identified in the returned ACME authorization object, an example of which follows.

The "tkauth" field in the challenge object is defined in . It is specific to the tkauth-01 challenge type, and when responding to a challenge for a JWTClaimConstraints identifier, that should 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 . 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 detailed in the next subsections.

"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 EnhancedJWTClaimConstaints 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 per 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 "Thumbprint" 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". This string will be managed as an identifier specific to the Token Authority's relationship with the entity that is creating and signing a PASSporT and making the Certificate Signing Request via ACME. There is assumed to also 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:

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. Note that the fingerprint in the token request is not meant to be verified by the Token Authority, but rather 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 the token requested and used came from the same party that controls the ACME client.

Scope of the JWTClaimConstraints Because this specification specifically involves the JWTClaimConstraints and EnhancedJWTClaimConstraints defined in and which involves the required or disallowed different claim types or claim values, the client may also request an Authority Token with some subset of its own authority as the JWTClaimConstraints provided in the "tkvalue" element in the "atc" JSON object. JWTClaimConstraints can be constructed to define a limited scope of claims and claim values the client has authority over. As recommended in security considerations, an Authority Token can either have a scope that attests all of the resources which a client is eligible to receive certificates for, or potentially a more limited scope that is intended to capture only those resources for which a client will receive a certificate from a particular certification authority. Any certification authority that sees an Authority Token can learn information about the resources a client can claim. In cases where this incurs a privacy risk, Authority Token scopes should be limited to only the resources that will be attested by the requested ACME certificate.

ACME Challenges requiring multiple Authority Tokens The ACME new-order request may include multiple identifiers, each of which is authorized separately. With the introduction of this specification, for STIR certificates two identifier types are authorized using Authority Tokens: The JWTClaimConstraints identifier defined in this document, and The TNAuthList identifier defined in . Other Authority Token types may be introduced in future Authority Token profile specificiations 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 issued certificate then bestows on the holder the authority to sign PASSporTs containing an "orig" claim that is within the scope of the certificate's TNAuthList extension. As described in section 5, 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. These two certificate extensions constrain the claims and claim values that may appear in PASSporTs signed using the certificate's credentials. In particular, claim-constraints extensions can restrict the values of the PASSporT "orig" claim, which is also governed by the TNAuthList Authority Token. Accordingly, there is an inherent interaction between these two types of Authority Tokens.

Examples of ACME Challenges requiring two Authority Tokens In the examples that follow, the requesting user is authorized to use a set of telephone numbers (TNs) and may, depending on the specific case, be authorized to assert additional claims and claim values such as Rich Call Data (RCD) items within signed PASSporTs. To support these capabilities, the user obtains both a TNAuthList Authority Token and a JWTClaimConstraints Authority Token from the appropriate Token Authority. These two tokens may be issued by the same Token Authority or by distinct entities. The following sub-sections describe three use-cases that illustrate how the two types of Authority Tokens can be used to form the ACME challenge response to the issuing CA. In all three cases, the TNAuthList Authority Token specifies the TNs, or a subset thereof, for which the user is authorized. The content of the JWTClaimConstraints Authority Token varies per use case based on the user's authority to assert extended PASSporT claims in addition to the authorization provided by the TNAuthList Authority Token.

No Extended Claims Authorized In the first case, the requesting user is authorized to use a set of TN(s), but no other information conveyed in extended PASSporT claims. Accordingly, the JWTClaimConstraints Authority Token contains an EnhancedJWTClaimConstraints extension that prohibits all claims defined by PASSporT extensions, as shown in the following example:

As described in Section 5.5.2, the CA requires two Authority Tokens in the ACME challenge response because the ACME client included both a TNAuthList identifier and a JWTClaimConstraints identifier in the new-order request. A simpler alternative for users not authorized to include extended claims in PASSporTs is to submit a new-order request containing only a TNAuthList identifier. In this case, the absence of a JWTClaimConstraints identifier could trigger local policy in the CA to include the above EnhancedJWTClaimConstraints extension in the issued certificate.

Extended Claims Authorized (same claims for all TNs) In the second case, the user is authorized to assert extended PASSporT claim information, and the additional claim information applies to all TN(s) the user is authorized to use. For example, the user could be authorized to use a single set of rich call data elements such as a company name and call reason for all authorized TNs. In this case, the corresponding JWTClaimConstraints Authority Token contains an EnhancedJWTClaimConstraints extension that permits RCD claim values associated with the authorized name and call reason, and applies these constraints uniformly across the user's authorized TNs, as shown in the following example:

Extended Claims Authorized (different claims per subset of TNs) In the third case, the user is permitted to assert different sets of extended PASSporT claims for distinct subsets of the user's authorized TNs. For example, the user may be authorized to use a calling name and call reason for one subset of authorized TN(s), and a different calling name and call reason for a different subset of authorized TN(s). In this example, the JWTClaimConstraints Authority Token includes permitted values for the RCD claims that are associated with a specific set of TN(s). Additionally, to ensure that the correct set of RCD claims is used with the correct set of TNs, the token includes an EnhancedJWTClaimConstraints permitted value(s) entry for the "orig" claim which identifies the relevant TN(s) to which the RCD claim values apply, as shown in the following example:

In this case, the CA will verify that the TNAuthList extension of the requested certificate is within the scope of both tokens provided in the ACME challenge response.

ACME Procedures when Challenge requires two Authority Tokens Sections 3 and 4 describe the ACME procedures for issuing a certificate based on receiving a new-order request with an "identifier" field containing 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. First, the "identifiers" field in the new-order request is as shown in section 3 with the exception that a TNAuthList identifier is added to the new-order "identifiers" field, as follows:

The CA includes two "authorizations" URLs in the 201 (Created) response to the new-order request, as follows:

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. Verify that the value of the "atc" claim is a well-formed JSON object containing the mandatory key values. If there is an "x5u" parameter verify the "x5u" parameter is a HTTPS URL with a reference to a certificate representing the trusted issuer of authority tokens for the eco-system. If there is an "x5c" parameter verify the certificate array contains a certificate representing the trusted issuer of authority tokens for the eco-system. Verify the JWTClaimConstraints Authority Token signature using the public key of the certificate referenced by the token's "x5u" or "x5c" parameter. Verify that "atc" claim contains a "tktype" identifier with the value "JWTClaimConstraints". Verify that the "atc" claim "tkvalue" identifier contains the equivalent base64url encoded JWTClaimConstraints or EnhancedJWTClaimConstraints certificate extension string value as the Identifier specified in the original challenge. Verify that the remaining claims are valid (e.g., verify that token has not expired) Verify that the "atc" claim "fingerprint" is valid and matches the account key of the client making the request Verify that the "atc" claim "ca" identifier boolean corresponds to the CA boolean in the Basic Constraints extension in the CSR for either CA certificate or 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 "status" in the challenge object MUST be set to "invalid".

Using ACME-issued Certificates with JSON Web Signature JSON Web Signature (JWS, ) objects can include an "x5u" header parameter to refer to a certificate that is used to validate the JWS signature. For example, the STIR PASSporT framework uses "x5u" to indicate the STIR certificate used to validate the PASSporT JWS object. The URLs used in "x5u" are expected to provide the required certificate in response to a GET request, not a POST-as-GET as required for the "certificate" URL in the ACME order object. Thus the current mechanism generally requires the ACME client to download the certificate and host it on a public URL to make it accessible to relying parties. This section defines an optional mechanism for the Certificate Authority (CA) to host the certificate directly and provide a URL that the ACME client owner can directly reference in the "x5u" of their signed PASSporTs. As described in Section 7.4 of when the certificate is ready for making a finalize request, the server will return a 200 (OK) with the updated order object. In this response, an ACME Server can add a newly defined field called "x5u" that can pass this URL to the ACME client for usage in generated PASSporTs as a publicly available URL for PASSporT validation.

x5u (optional, string):: A URL that can be used to reference the certificate in the "x5u" parameter of a JWS object

The publishing of the certificates at the new "x5u" URL should follow the GET request requirement as mentioned above and should be consistent with the timely publication according to the durations of the certificate lifecycle. The following is an example of the use of "x5u" in the response when the certificate status is "valid".

;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://sti-ca.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 PASSporT claims and claim values. The creation, transport, and any storage of this token MUST follow the strictest of security best practices beyond the recommendations of the use of encrypted transport protocols in this document to protect it from getting in the hands of bad actors with illegitimate intent to impersonate telephone numbers. This document inherits the security properties of . Implementations should follow the best practices identified in . 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.

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 .

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