OpenAPI-Specification

OpenAPI-Specification copied to clipboard

It doesn't appear that Swagger has a way of describing that the message payload can be placed in an encryption envelop. Is there plans to add that in the future?

Something like this:

{
  "securePayload": {
   "key": "AES public symmetric key",
   "iv": "AES initialization vector",
   "payload": "AES encrypted payload"
  }
}

No requests have been made for it so far (as far as I recall). We can definitely consider this for the next version. More details would help with the consideration (never assume everyone knows what you're trying to do :wink:).

Parent issue #586

Potentially this can also go under #585.

Using the JOSE standards https://tools.ietf.org/html/rfc7516 it is possible to use standard HTTP headers to define all the metadata needed to encrypt payloads. This should be possible to describe with the header parameters and response headers.

@darrelmiller That (having a header) might work if encryption is for the entire payload. How about inline encryption for part of the payload, say one property in response in encrypted? How should that be represented? If the encrypted property in response schema is annotated somehow to indicate that it is encrypted and packaged according to JOSE, it would help in response processing. Thoughts?

Is this just handled at the HTTP layer?

@RobDolinMS While HTTP (or rather HTTPS) allow encrypting everything, this is just on the transport layer.

There might be cases where encrypted content needs to be passed on by one of the communication partners (which doesn't even have the key) to/from someone else, maybe together with some non-encrypted metadata.

In this case a wrapper like in the initial post might be useful, with a way to define in OpenAPI both how the unencrypted parts and how the encrypted parts look (after decryption/before encryption).

@sdatspun2 does the JWT representation technique shown in JSON Schema draft 2020-12 address your use case, or do you need something more general?

@curtisdurrett does this need to incorporate technologies outside of the JOSE set of specifications, or can we close this in favor of #1464?

@handrews That question was raised in 2016! I am not sure. If in a payload you have multiple properties that require encryption or signature, how would that work? Is there an example?

@sdatspun2 I honestly don't know enough about this area to say- there is an example of the JWT representation in that link I've provided. Does it look useful?

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.