Support for message level security

As expressed in issues OAI/sig-security#37 and OAI/sig-security#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 OAI/sig-security#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!