Support for message level security
See original GitHub issueAs 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 ofmessageSecurityOperation
s describing the elementary signature and encryption operations that are required on API requests or performed as API responsesmessageSecuritySchemes
which is a Map ofmessageSecurityScheme
s, each security scheme stating whichmessageSecurityOperation
must be applied to the request before consuming the API and whichmessageSecurityOperation
will be applied to the operation’s responses, based on the response HTTP status code (all of these referencing themessageSecurityOperation
s declared in themessageSecurityOperations
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
- JWSRequest (standard JWS compact signature)
- JWSDetachedRequest (request body unchanged, signature passed in a HTTP header)
- SignedJWTRequest (signed JWT)
- HTTPSigRequest (HTTPSignature standard description)
- EncryptedJWTRequest (encrypted JWT)
- JWERequest (standard compact JWE encrypted message)
- Response Security Schemes
- JWSResponse
- JWSDetachedResponse
- SignedJWTResponse
- HTTPSigResponse
- EncryptedJWTResponse
- 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!
Issue Analytics
- State:
- Created 4 years ago
- Reactions:1
- Comments:8
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!
I think I understand what you are meaning now.
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?