The keyid parameter

[Takahiko Kawasaki]

It seems preferable to recommend including the keyid parameter (RFC 9421 HTTP Message Signatures, Section 2.3. Signature Parameters) to the signature metadata of HTTP message signatures.

When used with the mandatory created and tag parameters, the keyid parameter will appear in the Signature-Input HTTP field as shown below.

GET /api/userinfo HTTP/1.1
Host: trial.authlete.net
User-Agent: curl/8.7.1
Accept: */*
Authorization: Bearer 4rSgHO6sdlBL4z_1l4bAmED2CG40zblXlc3YDqrqdu8
Signature-Input: sig=("@method" "@target-uri" "authorization")\
 ;created=1728051074\
 ;keyid="ScIdKFzAj93vywpwjrfi3wrj5oHmHbHfmPT5IPTLmVc"\
 ;tag="fapi-2-request"
Signature: sig=:yx+SthCcbAu7R7rV1DoZX8ILLURmHwNTlRXMbnJVRHWXwyHQQPmPnLLhNx9tHeqG8Mp1SeN4CSB38QDwKfkkqA==:

The reason for recommending the use of keyid is that it is the only vendor-neutral means for key identification.

Without the keyid parameter, the resource server’s implementation would have to identify the key based on its own custom rules, significantly reducing interoperability. As a result, fintech client applications would need to agree on different key identification methods for each finantial institution they communicate with. Additionally, without the keyid parameter, while not impossible, it would become considerably difficult to support the use case mentioned in the first paragraph of RFC 9421 HTTP Message Signatures, Section 4.3. Multiple Signatures, where “a signer may include multiple signatures signing the same message components with different keys or algorithms to support verifiers with different capabilities.”

‌

[Takahiko Kawasaki]

The resource server (https://fapidev-rs.authlete.net) used in the FAPI 2.0 HTTP Signing Demo in FAPI Issue 633 implements OAuth 2.0 Protected Resource Metadata. Its metadata endpoint (https://fapidev-rs.authlete.net/.well-known/oauth-protected-resource) returns a very simple JSON as shown below:

{
  "resource": "https://fapidev-rs.authlete.net",
  "jwks_uri": "https://fapidev-rs.authlete.net/api/rsc/jwks"
}

The jwks_uri property in the JSON points to the location of the the resource server’s JWK Set document (https://fapidev-rs.authlete.net/api/rsc/jwks), which includes the verification key for verifying HTTP message signatures in responses from the resource server. The key point is that the value of the kid parameter in the single JWK within the JWK Set document (tsq5sQwuoADZ3iARLOreaYaIa9mG5TnV11zpRRjuA0k) matches the value of the keyid parameter in the Signature-Input HTTP field in the resource response.

When a client attempts to obtain the public key for verifying the HTTP message signature in the resource response, the keyid parameter in the signature metadata (RFC 9421: HTTP Message Signatures, Section 2.3. Signature Parameters) is useful.

The FAPI 2.0 HTTP Signing specification does not specify how to distribute public keys for client applications to verify HTTP message signatures in resource responses. As of this writing, OAuth 2.0 Protected Resource Metadata appears to be the only standardized, vendor-neutral method available for distributing resource server’s keys.