Support for message level security

As expressed in issues #1464 and #1881 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 #1881) :

# ...
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!

[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!

[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?