Rate-Limited Token Issuance Protocol

Internet-Draft	Rate-Limited Tokens	July 2023
Hendrickson, et al.	Expires 11 January 2024	[Page]

Abstract

This document specifies a variant of the Privacy Pass issuance protocol that allows for tokens to be rate-limited on a per-origin basis. This enables origins to use tokens for use cases that need to restrict access from anonymous clients.¶

1. Introduction

This document specifies a variant of the Privacy Pass issuance protocol (as defined in [ARCH]) that allows for tokens to be rate-limited on a per-origin basis. This enables origins to use tokens for use cases that need to restrict access from anonymous clients.¶

The base Privacy Pass issuance protocol [ISSUANCE] defines stateless anonymous tokens, which can either be publicly verifiable or not.¶

This variant builds upon the publicly verifiable issuance protocol that uses RSA Blind Signatures [BLINDSIG], and allows tokens to be rate-limited on a per-origin basis. This means that a client will only be able to receive a limited number of tokens associated with a given origin server within a fixed period of time.¶

This issuance protocol registers the Rate-Limited Blind RSA token type (Section 11.1), to be used with the PrivateToken HTTP authentication scheme defined in [AUTHSCHEME].¶

1.1. Motivation

A client that wishes to keep its IP address private can hide its IP address using a proxy service or a VPN. However, doing so severely limits the client's ability to access services and content, since servers might not be able to enforce their policies without a stable and unique client identifier.¶

Privacy Pass tokens in general allow clients to provide anonymous attestation of various properties. The tokens generated by the basic issuance protocol ([ISSUANCE]) can be used to verify that a client meets a particular bar for attestation, but cannot be used by a redeeming server to rate-limit specific clients. This is because there is no mechanism in the issuance protocol to link repeated client token requests in order to apply rate-limiting.¶

There are several use cases for rate-limiting anonymous clients that are common on the Internet. These routinely use client IP address tracking, among other characteristics, to implement rate-limiting.¶

One example of this use case is rate-limiting website accesses to a client to help prevent abusive behavior. Operations that are sensitive to abuse, such as account creation on a website or logging into an account, often employ rate-limiting as a defense-in-depth strategy. Additional verification can be required by these pages when a client exceeds a set rate-limit.¶

Another example of this use case is a metered paywall, where an origin limits the number of page requests from each unique user over a period of time before the user is required to pay for access. The origin typically resets this state periodically, say, once per month. For example, an origin may serve ten (major content) requests in a month before a paywall is enacted. Origins may want to differentiate quick refreshes from distinct accesses.¶

For some applications, the basic issuance protocol from [ISSUANCE] could be used to implement rate limits. In particular, the 'Joint Attester and Issuer' model from [ARCH] could be used to restrict the number of tokens issued to individual clients over a time window. However, in this deployment model, the Attester and Issuer would learn all origins used by a specific client, thereby coupling sensitive attestation and redemption contexts. In some cases this might be a significant portion of browsing history.¶

1.2. Protocol Overview

The issuance protocol defined in this document decouples sensitive information in the attestation context, such as the client identity, from the information in the redemption context, such as the origin. It does so by employing the 'Split Origin, Attester, Issuer' model. In this model, the Issuer learns redemption information like origin identity (used to determine per-origin rate limit policies), and the Attester learns attestation information like client identity (used to keep track of the previous instances of token issuance).¶

Figure 1 shows how this interaction works for client requests that are within the rate limit. The Client's token request to the Attester (constructed according to Section 5.3, and forwarded to the Issuer according to Section 5.4) contains encrypted information that the Issuer uses to identify the relevant rate limit policy to apply. This rate limit policy is returned to the Attester (according to Section 5.5), which then checks whether or not the Client is within this policy. If yes, the Attester forwards the issuer token response to the Client so that the resulting token can be redeemed by the Origin.¶

                                                     +-----------+
      Client                                         |   Origin  |
        |                    Challenge               |           |
        <-------------------------------------------------+      |
        |                                            |           |
        |          +-------------+                   |           |
        |          |   Attester  |                   |           |
        |          |             |                   |           |
        |          | Attest      |    +----------+   |           |
        +----------------->      |    |  Issuer  |   |           |
        |          |             |    |          |   |           |
        |   TokenRequest         |    |          |   |           |
        |   + Anon Origin ID     |    |          |   |           |
        | [ + Encrypted Origin ] |    |          |   |           |
        +----------------->      |    |          |   |           |
        |          |             |    |          |   |           |
        |          |       TokenRequest          |   |           |
        |          |      [ + Encrypted origin ] |   |           |
        |          |     +------------------->   |   |           |
        |          |             |    |          |   |           |
        |          |             |    |          |   |           |
        |          |       TokenResponse         |   |           |
        |          |      [ + Rate limit ]       |   |           |
        |          |     <-------------------+   |   |           |
        |          |             |    |          |   |           |
        |          |  in limit?  |    |          |   |           |
        |          |     yes     |    |          |   |           |
        |          |             |    |          |   |           |
        |   TokenResponse        |    |          |   |           |
        <-----------------+      |    |          |   |           |
        |          |             |    |          |   |           |
        |          +-------------+    +----------+   |           |
        |                                            |           |
        |                    Redeem                  |           |
        +------------------------------------------------->      |
                                                     |           |
                                                     +-----------+

Figure 1: Successful rate-limited issuance

Figure 2 shows how this interaction works for client requests that exceed the rate limit. The Client's request to the Issuer and the Issuer's response to the Attester are the same. However, in this scenario, the Client is not within the rate limit, so the Attester responds to the Client with an error instead of the issuer's token response.¶

                                                     +-----------+
      Client                                         |   Origin  |
        |                    Challenge               |           |
        <-------------------------------------------------+      |
        |                                            |           |
        |          +-------------+                   |           |
        |          |   Attester  |                   |           |
        |          |             |                   |           |
        |          | Attest      |    +----------+   |           |
        +----------------->      |    |  Issuer  |   |           |
        |          |             |    |          |   |           |
        |   TokenRequest         |    |          |   |           |
        |   + Anon Origin ID     |    |          |   |           |
        | [ + Encrypted Origin ] |    |          |   |           |
        +----------------->      |    |          |   |           |
        |          |             |    |          |   |           |
        |          |       TokenRequest          |   |           |
        |          |      [ + Encrypted origin ] |   |           |
        |          |     +------------------->   |   |           |
        |          |             |    |          |   |           |
        |          |             |    |          |   |           |
        |          |       TokenResponse         |   |           |
        |          |       + Rate limit          |   |           |
        |          |     <-------------------+   |   |           |
        |          |             |    |          |   |           |
        |          |  in limit?  |    |          |   |           |
        |          |      no     |    |          |   |           |
        |          |             |    |          |   |           |
        |        Error           |    |          |   |           |
        <-----------------+      |    |          |   |           |
        |          |             |    |          |   |           |
        |          +-------------+    +----------+   |           |
        X                                            |           |
  issuance failed                                    +-----------+

Figure 2: Failed rate-limited issuance

Each Issuer defines a window of time over which Attesters enforce rate limits, defined in the Issuer configuration directory (Section 3). This window might be as long as a month, or as short as an hour, depending on the use case. The window is the same across all Origins that work with the Issuer; if multiple window lengths are needed, then the entity running the Issuer can run multiple Issuers with different Issuer names, one for each window length.¶

The window begins upon a Client's first token request to the Attester for that Issuer and ends after the window time elapses, after which the Client's rate limit state is reset. Issuers indicate which rate limit to use for a given request by parsing the Client's encrypted Origin. Attesters enforce the rate limit based on the value indicated by the Issuer, and maintaining the count of accesses by a client to a corresponding Client's Origin Alias (see Section 2).¶

Along with the rate limit for the Origin, Issuers include a value generated with a per-Origin secret in their responses, which allows Attesters to ensure that the Client's Origin Alias indicated by the Client maps to exactly one Origin as seen by the Issuer; this value that is used to validate the Client's Origin Alias is called the Issuer's Origin Alias (see Section 2). Issuers can rotate the per-Origin secret they use as desired. If a rotation event happens during a Client's active policy window, the Attester would compute a different Issuer's Origin Alias and mistakenly conclude that the Client is accessing a new Origin. To mitigate this, Clients provide a stable Client's Origin Alias in their request to the Attester, which is constant for all requests to that Origin. This allows the Attester to detect when Issuer rotation events occur without affecting Client rate limits.¶

                          Per-Origin
                         secret rotate
Issuer:      -----+------------X----------+------------> Time
                  |         policy        |
Client            |         window        |
Token Requests:   *--------------*--------|
                  |              |        |
                  v              v        |
            Issuer Origin  Issuer Origin  |
                ID x           ID y       |
                  |                       |
            (policy start)          (policy end)

Figure 3: Issuer policy window rotation

Unlike the basic issuance protocol [ISSUANCE], the rate-limited issuance protocol in this document has additional functional and state requirements for Client, Attester, and Issuer. Section 5.1.2 describes the state that the Attester must track in order to enforce these limits, Section 5.1.1 describes the Client state necessary for successive token requests with the Attester, and Section 5.1.3 describes the state necessary for the Issuer to apply rate limits. The functional description of each participant in this protocol is explained in Section 5 ¶

1.3. Properties and Requirements

For rate-limited token issuance, the Attester, Issuer, and Origin as defined in [ARCH] each have partial knowledge of the Client's identity and actions, and each entity only knows enough to serve its function (see Section 2 for more about the pieces of information):¶

The Attester knows the Client's identity and learns the Client's public key (Client Key), the Issuer being targeted (Issuer Name), the period of time for which the Issuer's policy is valid (Issuer Policy Window), the number of tokens the Issuer is willing to issue within the current policy window, and the number of tokens issued to a given Client for the claimed Origin in the policy window. The Attester does not know the identity of the Origin the Client is trying to access (Origin Name), but knows a Client-anonymized identifier for it (Client's Origin Alias).¶
The Issuer knows a per-Origin secret (Issuer Origin Secret) and policy about client access, and learns the Origin's identity (Origin Name) during issuance. The Issuer does not learn the Client's identity or information about the Client's access pattern.¶
The Origin knows the Issuer to which it will delegate an incoming Client (Issuer Name), and can verify that any tokens presented by the Client were signed by the Issuer. The Origin does not learn which Attester was used by a Client for issuance.¶

Since an Issuer applies policies on behalf of Origins, a Client is required to reveal the Origin's identity to the delegated Issuer. It is a requirement of this protocol that the Attester not learn the Origin's identity so that, despite knowing the Client's identity, an Attester cannot track and concentrate information about Client activity.¶

An Issuer expects an Attester to verify its Clients' identities correctly, but an Issuer cannot confirm an Attester's efficacy or the Attester-Client relationship directly without learning the Client's identity. Similarly, an Origin does not know the Attester's identity, but ultimately relies on the Attester to correctly verify or authenticate a Client for the Origin's policies to be correctly enforced. An Issuer therefore chooses to issue tokens to only known and reputable Attesters; the Issuer can employ its own methods to determine the reputation of a Attester.¶

An Attester is expected to employ a stable Client identifier, such as an IP address, a device identifier, or an account at the Attester, that can serve as a reasonable proxy for a user with some creation and maintenance cost on the user.¶

For the Issuance protocol, a Client is expected to create and maintain stable and explicit secrets for time periods that are on the scale of Issuer policy windows. Changing these secrets arbitrarily during a policy window can result in token issuance failure for the rest of the policy window; see Section 5.1.1 for more details. A Client can use a service offered by its Attester or a third-party to store these secrets, but it is a requirement of this protocol that the Attester not be able to learn these secrets.¶

The privacy guarantees of this issuance protocol, specifically those around separating the identity of the Client from the names of the Origins that it accesses, are based on the expectation that there is not collusion between the entities that know about Client identity and those that know about Origin identity. Clients choose and share information with Attesters, and Origins choose and share policy with Issuers; however, the Attester is generally expected to not be colluding with Issuers or Origins. If this occurs, it can become possible for an Attester to learn or infer which Origins a Client is accessing, or for an Origin to learn or infer the Client identity. For further discussion, see Section 9.5.¶

Table 1
Field Name	Value
issuer-policy-window	Issuer Policy Window as a JSON number
issuer-request-uri	Issuer Request URI resource URL as a JSON string
encap-keys	List of Encapsulation Key values, each as a base64url encoded EncapsulationKey value

5. Issuance Protocol

This section describes the Issuance protocol for a Client to request and receive a token from an Issuer. Token issuance involves a Client, Attester, and Issuer, with the following steps:¶

The Client sends a token request containing a token request, encrypted origin name, and one-time-use public key and signature to the Attester¶
The Attester validates the request contents, specifically checking the request signature, and proxies the request to the Issuer¶
The Issuer validates the request against the signature, and processes its contents, and produces a token response sent back to the Attester¶
The Attester verifies the response and proxies the response to the Client¶

The Issuance protocol is designed such that Client, Attester, and Issuer learn only what is necessary for completing the protocol; see Section 8.5 for more details.¶

The Issuance protocol has a number of underlying cryptographic dependencies for operation:¶

RSA Blind Signatures [BLINDSIG], for issuing and constructing Tokens. This support is the same as used in the base publicly verifiable token issuance protocol [ISSUANCE]¶
[HPKE], for encrypting the origin server name in transit between Client and Issuer across the Attester.¶
Signatures with key blinding, as described in [KEYBLINDING], for verifying correctness of Client requests.¶

Clients and Issuers are required to implement all of these dependencies, whereas Attesters are required to implement signature with key blinding support.¶

5.1. State Requirements

The Issuance protocol requires each participating endpoint to maintain some necessary state, as described in this section.¶

5.1.1. Client State

A Client is required to have the following information, derived from a given TokenChallenge:¶

Origin Name, a hostname referring to the Origin [RFC6454]. This is the name of the Origin that issued the token challenge. One or more names can be listed in the TokenChallenge.origin_info field. Rate-limited token issuance relies on the client selecting a single origin name from this list if multiple are present.¶
Token Key, a blind signature public key specific to the Origin. This key is owned by the Issuer identified by the TokenChallenge.issuer_name.¶
Issuer Encapsulation Key, a public key used to encrypt request information corresponding to the Issuer identified by TokenChallenge.issuer_name.¶

Clients maintain a stable Client Key that they use for all communication with a specific Attester. Client Key is a public key, where the corresponding private key Client Secret is known only to the client.¶

If the client loses this (Client Key, Client Secret), they may generate a new tuple. The Attester will enforce if a client is allowed to use this new Client Key. See Section 5.1.2 for details on this enforcement.¶

Clients also need to be able to generate an Client's Origin Alias value that corresponds to the pair of Origin Name and Issuer Name, to send in requests to the Attester.¶

Client's Origin Alias MUST be a stable and unpredictable 32-byte value computed by the Client. Clients MUST NOT change this value across token requests for the same Origin Name and Issuer Name. See Section 5.6 for a discussion of Attester behavior if a collision is detected.¶

One possible mechanism for implementing this identifier is for the Client to store a mapping between the pair of (Origin Name, Issuer Name) and a randomly generated Client's Origin Alias for future requests. Alternatively, the Client can compute a PRF keyed by a per-client secret (Client Secret) over the Origin Name and Issuer Name, e.g., Client's Origin Alias = HKDF(secret=Client Secret, salt="", info=(Origin Name, Issuer name)).¶

5.1.2. Attester State

An Attester is required to maintain state for every authenticated Client. The mechanism of identifying a Client is specific to each Attester, and is not defined in this document. As examples, the Attester could use device-specific certificates or account authentication to identify a Client.¶

Attesters need to enforce that Clients don't change their Client Key frequently, to ensure Clients can't regularly evade the per-client policy as seen by the issuer. Attesters MUST NOT allow Clients to change their Client Key more than once within a policy window, or in the subsequent policy window after a previous Client Key change. Changing the secret will reset the client's policy window and thus can be used to exceed rate limits. One way to mitigate this is for the Attester to penalize clients that register new secrets too frequently. Alternative schemes where the Attester stores the encrypted (Client Key, Client Secret) tuple on behalf of the client are possible but not described here.¶

The Attester keeps track of Clients and Issuers that are not trusted, due to problems like changing Client Keys frequently, etc, as penalized entities (see Section 5.6).¶

Attesters are expected to know both the Issuer Policy Window and current Issuer Encapsulation Key for any Issuer Name to which they allow access. This information can be retrieved using the URIs defined in Section 3. The current Issuer Encapsulation Key value is used to check the value of the issuer_encap_key_id in Client-generated requests (Section 5.3) to reject requests where clients are using unique key IDs. Such unique keys could indicate a key-targeting attack that intends de-anonymize a client to the Issuer. In order to handle encapsulation key rotation, the Attester needs to know the current key value and the previou key value, and remember the last time the value changed to ensure that it does not happen too frequently (such as no more than once per policy window, or no more than once per day).¶

For each Client-Issuer pair, an Attester maintains a policy window start and end time for each Issuer from which a Client requests a token.¶

For each tuple of (Client Key, Client's Origin Alias, policy window), the Attester maintains the following state:¶

A counter of successful tokens issued¶
Whether or not a previous request was rejected by the Issuer¶
The previous rate limit provided by the Issuer¶
The last received Issuer's Origin Alias value for this Client's Origin Alias, if any¶

The Issuer-provided rate limit for a single Origin is intended to not change more frequently than once per policy window. If the Attester detects a change of rate limit multiple times for the state kept for a single policy window, it SHOULD reject tokens issued in the remainder of the policy window.¶

5.1.3. Issuer State

Issuers maintain a stable Issuer Origin Secret that they use in calculating values returned to the Attester for each origin. If this value changes, it will open up a possibility for Clients to request extra tokens for an Origin without being limited, within a policy window. See Section 10.1 for details about generating and rotating the Issuer Origin Secret.¶

Issuers are expected to have the private key that corresponds to Issuer Encapsulation Key, which allows them to decrypt the Origin Name values in requests.¶

For each Origin, Issuers need to know what rate limit to enforce during a policy window. Issuers SHOULD NOT use unique values for specific Origins, which would allow Attesters to recognize an Origin being accessed by multiple Clients. Each Origin limit is allowed to change, but SHOULD NOT change more often than once per policy window, to ensure that the limit is useful.¶

5.2. Issuance HTTP Headers

The Issuance protocol defines four new HTTP headers that are used in requests and responses between Clients, Attesters, and Issuers (see Section 11.2).¶

The "Sec-Token-Origin-Alias" is an Item Structured Header [RFC8941]. Its value MUST be a Byte Sequence. This header is sent both on Client-to-Attester requests (Section 5.3) and on Issuer-to-Attester responses (Section 5.5). Its ABNF is:¶

    Sec-Token-Origin-Alias = sf-binary

The "Sec-Token-Client" is an Item Structured Header [RFC8941]. Its value MUST be a Byte Sequence. This header is sent on Client-to-Attester requests (Section 5.3), and contains the bytes of Client Key. Its ABNF is:¶

    Sec-Token-Client = sf-binary

The "Sec-Token-Request-Blind" is an Item Structured Header [RFC8941]. Its value MUST be a Byte Sequence. This header is sent on Client-to-Attester requests (Section 5.3), and contains a per-request nonce value. Its ABNF is:¶

    Sec-Token-Request-Blind = sf-binary

The "Sec-Token-Limit" is an Item Structured Header [RFC8941]. Its value MUST be an Integer. This header is sent on Issuer-to-Attester responses (Section 5.5), and contains the number of times a Client can retrieve a token for the requested Origin within a policy window, as set by the Issuer. Its ABNF is:¶

    Sec-Token-Limit = sf-integer

5.3. Client-to-Attester Request

The Client and Attester MUST use a secure and Attester-authenticated HTTPS connection. They MAY use mutual authentication or mechanisms such as TLS certificate pinning, to mitigate the risk of channel compromise; see Section 8 for additional about this channel.¶

5.3.1. Client behavior

Requests to the Attester need to indicate the Issuer Name to which issuance requests will be forwarded. Attesters SHOULD provide Clients with a URI template that contains one variable that contains the Issuer Name, "issuer", using Level 3 URI template encoding as defined in Section 1.2 of [RFC6570].¶

An example of an Attester URI templates is shown below:¶

https://attester.net/token-request{?issuer}

Attesters and Clients MAY agree on other mechanisms to specify the Issuer Name in requests.¶

The Client first creates an issuance request message for a random value nonce using the input TokenChallenge challenge and the Issuer key identifier key_id as follows:¶

nonce = random(32)
context = SHA256(challenge)
token_input = concat(0x0003, nonce, context, key_id)
blinded_msg, blind_inv = rsabssa_blind(pkI, token_input)

The Client then uses Client Key to generate its one-time-use request public key request_key and blind request_blind as described in Section 7.1.¶

The Client then computes token_key_id as the least significant byte of the Token Key ID, where the Token Key ID is generated as SHA256(public_key) and public_key is a DER-encoded SubjectPublicKeyInfo object carrying Token Key. The Client then constructs a InnerTokenRequest value, denoted origin_token_request, combining token_key_id, blinded_msg, and a padded representation of the origin name as follows:¶

struct {
  uint8_t token_key_id;
  uint8_t blinded_msg[Nk];
  uint8_t padded_origin_name<0..2^16-1>;
} InnerTokenRequest;

This structure is initialized and then encrypted using Issuer Encryption Key, producing encrypted_token_request, as described in Section 6.¶

Finally, the Client uses Client Secret to produce request_signature as described in Section 7.1.2.¶

The Client then constructs a TokenRequest structure. This TokenRequest structure is based on the publicly verifiable token issuance path in [ISSUANCE], adding fields for the encrypted origin name and request signature.¶

struct {
   uint16_t token_type = 0x0003;
   uint8_t request_key[Npk];
   uint8_t issuer_encap_key_id[32];
   uint8_t encrypted_token_request<1..2^16-1>;
   uint8_t request_signature[Nsig];
} TokenRequest;

The structure fields are defined as follows:¶

"token_type" is a 2-octet integer, which matches the type in the challenge.¶
"request_key" is the request_key value generated above.¶
"issuer_encap_key_id" is a collision-resistant hash that identifies the Issuer Encryption Key, generated as SHA256(EncapsulationKey).¶
"encrypted_token_request" is an encrypted structure that contains an InnerTokenRequest value, calculated as described in Section 6.¶
"request_signature" is computed as described in Section 7.1.2.¶

The Client then generates an HTTP POST request to send through the Attester to the Issuer, with the TokenRequest as the body. The media type for this request is "message/token-request". The Client includes the "Sec-Token-Origin-Alias" header, whose value is Client's Origin Alias; the "Sec-Token-Client" header, whose value is Client Key; and the "Sec-Token-Request-Blind" header, whose value is request_blind. The Client sends this request to the Attester's proxy URI. An example request is shown below, where the Issuer Name is "issuer.net" and the Attester URI template is "https://attester.net/token-request{?issuer}"¶

:method = POST
:scheme = https
:authority = attester.net
:path = /token-request?issuer=issuer.net
accept = message/token-response
cache-control = no-cache, no-store
content-type = message/token-request
content-length = <Length of TokenRequest>
sec-token-origin-alias = Client's Origin Alias
sec-token-client = Client Key
sec-token-request-blind = request_blind

<Bytes containing the TokenRequest>

5.3.2. Attester behavior

Upon receiving a request from a Client, the Attester checks if the Client has been penalized based on incorrect behavior using this protocol (see Section 5.6). If the Client is not trusted, the Attester rejects the request with an appropriate HTTP 4xx error.¶

If this Issuer for the token request is not known to or trusted by the Attester, including if the Issuer has been penalized (see Section 5.6), the Attester rejects the request with an appropriate HTTP error.¶

If the Attester detects a token_type in the TokenRequest that it does not recognize or support, it MUST reject the request with an HTTP 400 error.¶

The Attester also checks to validate that the issuer_encap_key_id in the client's TokenRequest matches a known Issuer Encapsulation Key public key for the Issuer. For example, the Attester can fetch this key using the API defined in Section 3. This check is done to help ensure that the Client has not been given a unique key that could allow the Issuer to fingerprint or target the Client. If the key does not match, the Attester rejects the request with an HTTP 400 error. Note that this can lead to failures in the event of Issuer Issuer Encapsulation Key rotation; see Section 9 for considerations.¶

The Attester finally validates the Client's stable mapping request as described in Section 7.2. If this fails, the Attester MUST return an HTTP 400 error to the Client.¶

If the Attester accepts the request, it will look up the state stored for this Client. It will look up the count of previously generate tokens for this Client using the same Client's Origin Alias. See Section 5.1.2 for more details.¶

If the Attester has stored state that a previous request for this Client's Origin Alias was rejected by the Issuer in the current policy window, it SHOULD reject the request without forwarding it to the Issuer.¶

If the Attester detects this Client has changed their Client Key more frequently than allowed as described in Section 5.1.2, it SHOULD reject the request without forwarding it to the Issuer, and also use this event to penalize the Client (see Section 5.6).¶

5.4. Attester-to-Issuer Request

The Attester and the Issuer MUST use a secure and Issuer-authenticated HTTPS connection for all requests. Also, Issuers MUST authenticate Attesters, either via mutual TLS or another form of application-layer authentication. They MAY additionally use mechanisms such as TLS certificate pinning, to mitigate the risk of channel compromise; see Section 8 for additional about this channel.¶

5.4.1. Attester behavior

Assuming all checks in Section 5.3 succeed, the Attester generates an HTTP POST request to send to the Issuer with the Client's TokenRequest as the body. The Attester MUST NOT add information that will uniquely identify a Client, or associate the request with a small set of possible Clients. Extensions to this protocol MAY allow Attesters to add information that can be used to separate large populations, such as providing information about the country or region to which a Client belongs. An example request is shown below.¶

:method = POST
:scheme = https
:authority = issuer.net
:path = /token-request
accept = message/token-response
cache-control = no-cache, no-store
content-type = message/token-request
content-length = <Length of TokenRequest>

<Bytes containing the TokenRequest>

5.4.2. Issuer behavior

Upon receipt of the forwarded request, the Issuer validates the following conditions:¶

The TokenRequest contains a supported token_type¶
The TokenRequest.issuer_encap_key_id correspond to known Issuer Encapsulation Keys held by the Issuer.¶
The TokenRequest.encrypted_token_request can be decrypted using the Issuer's private key (the private key associated with Issuer Encapsulation Key), and contains a valid InnerTokenRequest whose unpadded origin name matches an Origin Name that is served by the Issuer. The Origin name associated with the InnerTokenRequest value might be the empty string "", as described in Section 6, in which case the Issuer applies a cross-origin policy if supported. If a cross-origin policy is not supported, this condition is not met.¶

If any of these conditions is not met, the Issuer MUST return an HTTP 400 error to the Attester, which will forward the error to the client.¶

The Issuer determines the correct Issuer Key by using the decrypted Origin Name and InnerTokenRequest.token_key_id values. If there is no Token Key whose truncated key ID matches InnerTokenRequest.token_key_id, the Issuer MUST return an HTTP 401 error to Attester, which will forward the error to the client. The Attester learns that the client's view of the Origin key was invalid in the process.¶

5.5. Token Issuance Response

5.5.1. Issuer behavior

If the Issuer is willing to give a token to the Client, the Issuer decrypts TokenRequest.encrypted_token_request to discover a InnerTokenRequest value. If this fails, the Issuer rejects the request with a 400 error. Otherwise, the Issuer validates and processes the token request with Issuer Origin Secret corresponding to the designated Origin as described in Section 7.3. If this fails, the Issuer rejects the request with a 400 error. Otherwise, the output is index_key.¶

The Issuer completes the issuance flow by computing a blinded response as follows:¶

blind_sig = rsabssa_blind_sign(skP, InnerTokenRequest.blinded_msg)

skP is the private key corresponding to the per-Origin Token Key, known only to the Issuer. The Issuer then encrypts blind_sig to the Client as described in Section 6.2, yielding encrypted_token_response.¶

The Issuer generates an HTTP response with status code 200 whose body consists of blind_sig, with the content type set as "message/token-response", the index_key set in the "Sec-Token-Origin-Alias" header, and the limit of tokens allowed for a Client for the Origin within a policy window set in the "Sec-Token-Limit" header. This limit SHOULD NOT be unique to a specific Origin, such that the Attester could use the value to infer which Origin the Client is accessing (see Section 9).¶

:status = 200
content-type = message/token-response
content-length = <Length of blind_sig>
sec-token-origin-alias = index_key
sec-token-limit = Token limit

<Bytes containing the encrypted_token_response>

5.5.2. Attester behavior

For all non-successful responses from the Issuer, the Attester forwards the HTTP response unmodified to the Client as the response to the original request for this issuance.¶

Upon receipt of a successful (2xx) response from the Issuer, the Attester extracts the "Sec-Token-Origin-Alias" header, and uses the value to determine Issuer's Origin Alias as described in Section 7.4.¶

If the "Sec-Token-Origin-Alias" header is missing in a successful (2xx) response from the Issuer, the Attester MUST count this towards penalizing the Issuer (see Section 5.6). The token response MUST continue to be processed, however, to prevent a malicious Issuer from using a token issuance failure as a signal to the requesting Origin.¶

If the Issuer's Origin Alias derived from the value in the "Sec-Token-Origin-Alias" header was previously received in a response for a request with a different Client's Origin Alias within the same policy window, the Attester MUST count this towards penalizing the Issuer or Client (see Section 5.6). The token response MUST continue to be processed, however, to prevent a malicious Issuer from using a token issuance failure as a signal to the requesting Origin.¶

The Attester then stores the Issuer's Origin Alias alongside the state for the Anonymous Origin ID to compare on future token issuances.¶

The Attester also extracts the "Sec-Token-Limit" header, and compares the limit against the previous count of accesses for this Client for the Client's Origin Alias. If the count is greater than or equal to the limit, the Attester drops the token and responds to the client with an HTTP 429 (Too Many Requests) error.¶

When the Attester detects successful token issuance, it MUST increment the counter in its state for the number of tokens issued to the Client for the Client's Origin Alias.¶

5.5.3. Client behavior

Upon receipt, the Client decrypts the blind_sig from encrypted_token_response as described in Section 6.2. If successful, the Client then processes the response as follows:¶

authenticator = rsabssa_finalize(pkI, token_input, blind_sig, blind_inv)

If this succeeds, the Client then constructs a token as described in [AUTHSCHEME] as follows:¶

struct {
    uint16_t token_type = 0x0003
    uint8_t nonce[32];
    uint8_t context[32];
    uint8_t token_key_id[Nid];
    uint8_t authenticator[Nk]
} Token;

5.6. Penalization of Invalid Clients and Issuers

When an Attester encounters incorrect and potentially malicious behavior by either Clients or Issuers, it needs to "penalize" them. This involves keeping state about invalid protocol events, and determining when a particular Client or Issuer has exceeded a threshold for such events.¶

Each category of invalid events can have a different threshold, and can apply to Clients, Issuers, or both. Different penalization events are described below, with suggested thresholds. This list is not exhaustive.¶

Client Key changing more than once over any two consecutive policy windows for a single Client, based on the Attester's view of Client identity. This is a Client-specific penalization event. A RECOMMENDED threshold for penalizing the Client based on this is one event; a well-behaved Client will never change keys this frequently.¶
Issuer responses missing the "Sec-Token-Origin-Alias" header on a 2xx response. This is an Issuer-specific penalization event. A RECOMMENDED threshold for penalizing the Issuer based on this is ten events across all Clients; a well-behaved Issuer will never generate such responses, but it can be useful for an Attester to have a small tolerance for errors before penalizing an Issuer entirely.¶
Issuer's Origin Alias (from Issuer) collision across two Anonymous Origin IDs for a particular Client within a single policy window. This penalization event is applicable for both Clients and Issuers. A RECOMMENDED threshold for penalizing the Issuer is ten events across different Clients. A RECOMMENDED threshold for penalizing the Client is two events across multiple Issuers, or five events with a single Issuer. If many events are seen for a single Issuer, it is likely that the Issuer is compromised or malicious; while if such events are seen for a specific Client, it is likely that the Client is is compromised or malicious.¶

Once a Client or Issuer passes the threshold for penalization, the Attester rejects future requests from that Client or for that Issuer. This SHOULD only be reset after a sufficient period of time (such as at least one policy window), and based on either manual review or another validation process determined by the Attester. Penalization indicates that a Client or Issuer might be malicious or compromised, and so ought not to be trusted until further validation that the error or attack has been mitigated.¶

6. Encrypting Origin Token Requests and Responses

Clients encapsulate token request information to the Issuer using the Issuer Encapsulation Key. Issuers decrypt the token request using their corresponding private key. This process yields the decrypted token request as well as a shared encryption context between Client and Issuer. Issuers encapsulate their token response to the Client using an ephemeral key derived from this shared encryption context. This process ensures that the Attester learns neither the token request or response information.¶

Client to Issuer encapsulation is described in Section 6.1, and Issuer to Client encapsulation is described in Section 6.2.¶

6.1. Client to Issuer Encapsulation

Given a EncapsulationKey (Issuer Encapsulation Key), Clients produce encrypted_token_request using the following values:¶

the one octet key identifier from the Name Key, keyID, with the corresponding KEM identified by kemID, the public key from the configuration, pkI, and;¶
a selected combination of KDF, identified by kdfID, and AEAD, identified by aeadID.¶

Beyond the key configuration inputs, Clients also require the following inputs defined in Section 5.3: token_key_id, blinded_msg, request_key, origin_name, and issuer_encap_key_id.¶

Together, these are used to encapsulate an InnerTokenRequest and produce an encrypted token request (encrypted_token_request).¶

origin_name contains the name of the origin that initiated the challenge, as taken from the TokenChallenge.origin_info field. If the TokenChallenge.origin_info field is empty, origin_name is set to the empty string "".¶

The process for generating encrypted_token_request from blinded_msg, request_key, and origin_name values is as follows:¶

Compute an [HPKE] context using pkI, yielding context and encapsulation key enc.¶
Construct associated data, aad, by concatenating the values of keyID, kemID, kdfID, aeadID, and all other values of the TokenRequest structure.¶
Pad origin_name with N zero bytes, where N = 31 - ((L - 1) % 32) and L is the length of origin_name. If L is 0, N = 32. Denote this padding process as the function pad.¶
Encrypt (seal) the padded origin_name with aad as associated data using context, yielding ciphertext ct.¶
Concatenate the values of aad, enc, and ct, yielding encrypted_token_request.¶

Note that enc is of fixed-length, so there is no ambiguity in parsing this structure.¶

In pseudocode, this procedure is as follows:¶

enc, context = SetupBaseS(pkI, "InnerTokenRequest")
aad = concat(encode(1, keyID),
             encode(2, kemID),
             encode(2, kdfID),
             encode(2, aeadID),
             encode(2, token_type),
             encode(Npk, request_key),
             encode(32, issuer_encap_key_id))
padded_origin_name = pad(origin_name)
inner_token_request_enc = concat(encode(1, token_key_id),
                                 encode(Nk, blinded_msg),
                                 encode(2, len(padded_origin_name)),
                                 encode(len(padded_origin_name), padded_origin_name))
ct = context.Seal(aad, inner_token_request_enc)
encrypted_token_request = concat(enc, ct)

Issuers reverse this procedure to recover the InnerTokenRequest value by computing the AAD as described above and decrypting encrypted_token_request with their private key skI (the private key corresponding to pkI). The origin_name value is recovered from InnerTokenRequest.padded_origin_name by stripping off padding bytes. In pseudocode, this procedure is as follows:¶

enc, ct = parse(encrypted_token_request)
aad = concat(encode(1, keyID),
             encode(2, kemID),
             encode(2, kdfID),
             encode(2, aeadID),
             encode(2, token_type),
             encode(Npk, request_key),
             encode(32, issuer_encap_key_id))
context = SetupBaseR(enc, skI, "TokenRequest")
inner_token_request_enc, error = context.Open(aad, ct)

The InnerTokenRequest.blinded_msg, InnerTokenRequest.token_key_id, and unpadded origin_name values are used by the Issuer as described in Section 5.4.¶

6.2. Issuer to Client Encapsulation

Given an HPKE context context computed in Section 6.1, Issuers encapsulate their token response blind_sig, yielding an encrypted token response encrypted_token_response, to the Client as follows:¶

Export a secret secret from context, using the string "OriginTokenResponse" as context. The length of this secret is max(Nn, Nk), where Nn and Nk are the length of AEAD key and nonce associated with context.¶
Generate a random value of length max(Nn, Nk) bytes, called response_nonce.¶
Extract a pseudorandom key prk using the Extract function provided by the KDF algorithm associated with context. The ikm input to this function is secret; the salt input is the concatenation of enc (from enc_request) and response_nonce¶
Use the Expand function provided by the same KDF to extract an AEAD key key, of length Nk - the length of the keys used by the AEAD associated with context. Generating key uses a label of "key".¶
Use the same Expand function to extract a nonce nonce of length Nn - the length of the nonce used by the AEAD. Generating nonce uses a label of "nonce".¶
Encrypt blind_sig, passing the AEAD function Seal the values of key, nonce, empty aad, and a pt input of request, which yields ct.¶
Concatenate response_nonce and ct, yielding an Encapsulated Response enc_response. Note that response_nonce is of fixed-length, so there is no ambiguity in parsing either response_nonce or ct.¶

In pseudocode, this procedure is as follows:¶

secret = context.Export("OriginTokenResponse", Nk)
response_nonce = random(max(Nn, Nk))
salt = concat(enc, response_nonce)
prk = Extract(salt, secret)
aead_key = Expand(prk, "key", Nk)
aead_nonce = Expand(prk, "nonce", Nn)
ct = Seal(aead_key, aead_nonce, "", blind_sig)
encrypted_token_response = concat(response_nonce, ct)

Clients decrypt encrypted_token_response by reversing this process. That is, they first parse enc_response into response_nonce and ct. They then follow the same process to derive values for aead_key and aead_nonce.¶

The client uses these values to decrypt ct using the Open function provided by the AEAD. Decrypting might produce an error, as follows:¶

blind_sig, error = Open(aead_key, aead_nonce, "", ct)

7. Issuer's Origin Alias Computation

This section describes the Client, Attester, and Issuer behavior in computing Issuer's Origin Alias, the stable mapping based on client identity and origin name. At a high level, this functionality computes y = F(x, k), where x is a per-Client secret and k is a per-Origin secret, subject to the following constraints:¶

The Attester only learns y if the Client in possession of x engages with the protocol;¶
The Attester prevents a Client with private input x from running the protocol for input x' that is not equal to x;¶
The Issuer does not learn x, nor does it learn when two requests correspond to the same private value x; and¶
Neither the Client nor Attester learn k.¶

The interaction between Client, Attester, and Issuer in computing this functionality is shown below.¶

Client               Attester                Issuer
    (request, signature)
  ---------------------->
                           (request, signature)
                         ---------------------->
                                (response)
                         <----------------------

The protocol for computing this functionality is divided into sections for each of the participants. Section 7.1 describes Client behavior for initiating the computation with its per-Client secret, Section 7.2 describes Attester behavior for verifying Client requests, Section 7.3 describes Issuer behavior for computing the mapping with its per-Origin secret, and Section 7.4 describes the final Attester step for computing the client-origin index.¶

The index computation is based on a signature scheme with key blinding and unblinding support, denoted BKS, as described in Section 3 of [KEYBLINDING]. Such a scheme has the following functions:¶

BKS-KeyGen(): Generate a random private and public key pair (sk, pk).¶
BKS-BlindKeyGen(): Generate a random blinding key bk.¶
BKS-BlindPublicKey(pk, bk, ctx): Produce a blinded public key based on the input public key pk, blind key bk, and context ctx.¶
BKS-UnblindPublicKey(pk, bk, ctx): Produce an unblinded public key based on the input blinded public key pk, blind bk, and context ctx.¶
BKS-Verify(pk, msg, sig): Verify signature sig over input message msg against the public key pk, producing a boolean value indicating success.¶
BKS-BlindKeySign(sk_sign, sk_blind, ctx, msg): Sign input message msg with signing key sk_sign, blind key sk_blind, and context ctx and produce a signature of size Nsig bytes.¶
BKS-SerializePrivatekey(sk): Serialize a private key to a byte string of length Nsk.¶
BKS-DeserializePrivatekey(buf): Attempt to deserialize a private key from an Nsk-byte string buf. This function can fail if buf does not represent a valid private key.¶
BKS-SerializePublicKey(pk): Serialize a public key to a byte string of length Npk.¶
BKS-DeserializePublicKey(buf): Attempt to deserialize a public key of length Npk. This function can fail if buf does not represent a valid public key.¶

Additionally, each BKS scheme has a corresponding hash function, denoted Hash. The implementation of each of these functions depends on the issuance protocol token type. See Section 11.1 for more details.¶

7.1. Client Behavior

This section describes the Client behavior for generating an one-time-use request key and signature. Clients provide their Client Secret as input to the request key generation step, and the rest of the token request inputs to the signature generation step.¶

7.1.1. Request Key

Clients produce request_key by masking Client Key and Client Secret with a randomly chosen blind. Let pk_sign and sk_sign denote Client Key and Client Secret, respectively. This process is done as follows:¶

Generate a random blind key, sk_blind.¶
Blind pk_sign with sk_blind to compute a blinded public key, request_key.¶
Output the blinded public key.¶