Support for message level security

[pleothaud]

As expressed in issues #37 and #20 there is a need for describing signed and encrypted requests and response using OpenAPI. I would like to propose the following mechanisms to support message level security in OAS.

This proposal comes after some preliminary works summarized in the Google doc at https://docs.google.com/document/d/13THkz7867blJ464ohpz9MUrhMQp-28Cx77JvDHlyurc from OAI Google Drive (I can give access to this doc to who needs it)

The problem with the proposal in this document is that it was too complex and did not follow the Open API philosophy, so I tried here to put in place something more standard, mimicking the Security Scheme / Security Requirement mechanism people are used to.

Let's take an example that shows how you could describe required requests signature and provided responses signature using JWT tokens (as you can see it uses the key description mechanism proposed by @whitlockjc in issue #20) :

# ...
components:

 keys:
 # Keys taken from Google's OIDC Discover Document (https://accounts.google.com/.well-known/openid-configuration)
 google-oauth-v3-1:
 description: "JSON Web Key used by Google for signing JWTs: https://www.googleapis.com/oauth2/v3/certs#/keys/0"
 type: JWK
 metadata:
 kid: 0905d6f9cd9b0f1f852e8b207e8f673abca4bf75
 e: AQAB
 kty: RSA
 alg: RS256
 n: yyeEmeK35F8P54ozfpsF79n59ZsOrcZdxQWsxrzm0qjdA5r_b-be-cQnWAw_2AoGdeWHX-Cz7uPFDMdEwzLGlpv3SELi34h8PkzjyO7xlbhsNs-ICnqUyUTA7CovKtpJ47PjiQnXcaRNCFUQbli8VlEqbVLuqFjC98igICpNYR-iiVIm0VCFtkq0p8vf1yQ493Pnx2Bm8fUx6SkeJ7wKPWQq_K4e6ZH40JWLk6c1U9W5qPKeckevdNLrdZY5lsTZ5zrRvuRBoIeZfp9bKSZGMtEja4xSCDKLrkcpb4qf6Ywx9rsZ4b8eHSLpVvUzNsj3GS7qK5flHzoccovhPVBbbQ
 use: sig

 messageSecurityOperations:
 signedJWTrequestOperation:
 securityType: signedJWTRequest
 alg:
 - PS256
 - PS512
 pubKeyRef:
 - jku+kid
 mandatoryStandardClaims:
 - iss
 - aud
 - iat
 - exp
 - jti
 
 signedJwtResponseOperation:
 securityType: signedJWTResponse
 pubKey: 
 $ref: '#/components/keys/google-oauth-v3-1'
 
 messageSecuritySchemes:
 highSensitivityScheme-PostPutPatch:
 requestSecurity:
 $ref: '#/components/messageSecurityOperations/signedJWTrequestOperation'
 responseSecurity:
 200:
 $ref: '#/components/messageSecurityOperations/signedJwtResponseOperation'
# ...

As you can see, there are two objects added in the components top level object:

• messageSecurityOperations, which is a Map of messageSecurityOperations describing the elementary signature and encryption operations that are required on API requests or performed as API responses
• messageSecuritySchemes which is a Map of messageSecuritySchemes, each security scheme stating which messageSecurityOperation must be applied to the request before consuming the API and which messageSecurityOperation will be applied to the operation's responses, based on the response HTTP status code (all of these referencing the messageSecurityOperations declared in the messageSecurityOperations object

Once these objects declared in the components object, it becomes possible to reference a messageSecurityScheme directly from an Operation, just like this:

# ...
paths:
 /pets:
 post:
 description: Creates a new pet in the store. Duplicates are allowed
 operationId: addPet
 messageSecurity: highSensitiveProfile-PostPutPatch
 requestBody:
 description: Pet to add to the store
 required: true
 content:
 application/jwt:
 schema:
 $ref: '#/components/schemas/NewPet'
 responses:
 '200':
 description: pet response
 content:
 application/jwt:
 schema:
 $ref: '#/components/schemas/Pet'
 default:
 description: unexpected error
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/Error'
# ...

where the messageSecurity: highSensitivityScheme-PostPutPatch field of the post operation object specifies which message security scheme to apply to the operation (on requests and responses).

There are a few message level security operations that could be described this way:

• Request Security Schemes

1. JWSRequest (standard JWS compact signature)
2. JWSDetachedRequest (request body unchanged, signature passed in a HTTP header)
3. SignedJWTRequest (signed JWT)
4. HTTPSigRequest (HTTPSignature standard description)
5. EncryptedJWTRequest (encrypted JWT)
6. JWERequest (standard compact JWE encrypted message)

• Response Security Schemes

1. JWSResponse
2. JWSDetachedResponse
3. SignedJWTResponse
4. HTTPSigResponse
5. EncryptedJWTResponse
6. JWEResponse

If you feel comfortable with the presented structure of message level security description I can create separate issues for each of these message level security operations, specifying mandatory and optional attributes that could describe these operations.

Happy to discuss!

[cyberphone]

It is correct that https://datatracker.ietf.org/doc/draft-cavage-http-signatures is the only of the described schemes supporting REST? UK's Open Banking signature scheme does not include URI and Method although they are fundamental parts of a REST request.

[pleothaud]

HI Anders,

Yes at the moment it is the only scheme supporting URI/Method/HTTP headers signatrure available (while still in draft).

There was a proposal from Richer, Bradley and Tschofenig from the Oauth WG at IETF about that (https://tools.ietf.org/html/draft-ietf-oauth-signed-http-request-03) but it's been expired for 3 years now... Seems that IETF guys did not like the needed canonicalization of the HTP request :-)

As you know I'm thinking of proposing to the OAuth WG something simpler, based on the fact that you add Method + URI + a selection of HTTP headers in the JOSE header and then use the detached unencoded payload mechanism. Just running after time to write this down, as always :-(

Thanks,

Philippe

[cyberphone]

Hi Philippe,
You will anyway need to canonicalize the URI and the HTTP headers. Here is my take on the latter:
https://tools.ietf.org/html/draft-rundgren-signed-http-requests-00#section-6.8

BTW, canonicalization of the JSON body is not dead, it is just resting a bit :)
It works like a charm on 5 platforms so the team behind it is currently trying to establish an "informational" RFC. This is not a "full standard" but I think it suffices for getting it off ground.

[pleothaud]

Mmmm no actually and that's the beauty of it :-)

As the info from the HTTP message you want to integrity protect is written in the JOSE header to some extent the canonicalization process lays in how you store the information in the JOSE header.

So when you verify the signature of the JWS you ensure that all the info in the JOSE header was not modified during transit.

Then all you've got to do is verifying that this info semantically matches the received HTTP message!

This has to be refined, a proper definition of what "semantically matches" means should be provided, but this should work and would be so easier, IMHO

[cyberphone]

This has to be refined, a proper definition of what "semantically matches" means should be provided, but this should work and would be so easier, IMHO

This is the URI and Header canonicalization I referred to. The data is created by the sender but must be compared by the receiver using "live" HTTP data from the server. The algorithm I showed is essentially the same as HTTP Signatures uses. I believe this part was the reason the previous attempt you mentioned didn't got through. Some people claim this is impossible since proxies modify data. Since HTTP Signatures and a similar solution from Amazon actually is heavily used, this is obviously exaggerated. Or to be more correct: Requiring that everything must work on any platform without adjustments is counter productive. Android Apps typically does not run on all versions of Android either.

The difference between detached JSON and canonicalized JSON is another discussion. They both have downsides. Detached JSON is a loss in the proxy world, for WebSockets and doesn't lend itself to serialization.

[pleothaud]

Semantic match is a different beast than byte to byte equality after transformation required by canonicalization processes. Set-Cookie addition by reverse proxies is an example of problem with canonicalization (and BTW as Set-Cookie expires is an unquoted RFC 822 date containing a comma, concatenating Set-Cookie values with a comma can be a problem: this is why you generate a Set-Cookie header by cookie) that can be easily overcome by semantic matching.

Anyway, this discussion about HTTP Signature is not totally in the scope of this issue :-)

I'll send you a PM about this.

[cyberphone]

I think I understand what you are meaning now.

• You sign HTTP header data as is but in a Base64Url-safe way
• After verifying the signature you try to match the signed data with the actual potentially somewhat changed data

I would be a bit cautious about trying to standardize such a scheme. If the data is HTTP-compliant it should be possible to canonicalize the data the way HTTP Signatures, Amazon and I suggest. If it is not HTTP-compliant, I wouldn't bother. If an intermediary adds a Set-Cookie I don't see how that could work with any scheme unless you treat each cookie as a separate item. Maybe that is a better approach; consider all concatenated headers as separate elements during canonicalization?

[albertvp]

Hi all, is there any conclusion from the meeting?

I think that encryption keys management should be treated as a separate service, like user session. But instead of Authorization headers, where you can specify a global token, might be nice to select or send a keyID within the request. This assumes that the dynamic specification of the key can switch to a different security level. If no key provided then no encryption is done.

Another important thing for me is how to specify which fields are encrypted and which are "public". So every attribute that contains sensitive information has to be included on the encrypted part, and the rest will be raw to perform searches with no key. A really cool thing might be to include in the ui-docs the payload transformation process (encrypt/decrypt) by default, so you still have inputs where to put raw values and decrypt the response to show again raw values.

I'm not really familiar to JOSE, but hope to provide another point of view, thank you!

[MikeRalphson]

Adding an updated IETF draft link - https://datatracker.ietf.org/doc/draft-ietf-httpbis-message-signatures/

[handrews]

HTTP Signatures are now RFC9241, so we will support them in the context of the SAF concept (#5310 . They are also required for GNAP auth supprt.

[cyberphone]

RFC9241 is fine, but it is incompatible the EU Digital Identity Wallet: https://lists.w3.org/Archives/Public/ietf-http-wg/2026JulSep/0216.html