Support for JOSE (JSON Signature and Encryption) Standards

[cyberphone]

I'm not currently a user of OpenAPI but a follower of standards initiatives like OpenBanking/FAPI where members claim that OpenAPI currently does not support JOSE (JSON Signature and Encryption) standards forcing them to use various workarounds.

I wonder if there is anybody out there with knowledge of the OpenAPI platform who could be interested in working with me to integrate the missing support?

There are also enhanced versions of JOSE JWS and JWE in the workings (through the IETF), providing Clear Text support which should be a nice fit for information centric systems, here illustrated by a minute JWS-CT sample:

{
     "@context": "https://example.com/paymentStandard/pay",
     "amount": "255.00",
     "currency": "USD",
     "signature": {
         "alg": "ES256",
         "jwk": {
             "kty": "EC",
             "crv": "P-256",
             "x": "PxlJQu9Q6dOvM4LKoZUh2XIe9-pdcLkvKfBfQk11Sb0",
             "y": "6IDquxrbdq5ABe4-HQ78_dhM6eEBUbvDtdqK31YfRP8"
         },
         "val": "RSLmFihg8QmXxM .... N0lGIdSEYvMMLTL8hEaYV9kW6A"
     }
}

[MikeRalphson]

There was an earlier discussion touching on this here: #550 (comment)

[isamauny]

We are looking at a proposal to the OpenAPI foundation for this exact issue. The idea is to describe in the OpenAPI Specification all the information needed at the consumer side to either create encrypted/signed contents or validate such contents. It should also be descriptive enough that the generation of the JOSE contents can be automated.

Our approach is trust no one. So while you could decrypt and validate contents from the contents of the message you receive, you must have the information of what was the contract in order to validate properly. In other words, you could receive contents which have been tempered with via a MITM attack and are perfectly valid in terms of structure, but not corresponding at all with it should have been.

Clear Text support as described above is very much inline with our thinking.

So yes happy to work with the foundation and Anders on this via FAPI.

[cyberphone]

Would it be possible getting a "second opinion" on an issue where the conveners currently are somewhat divided?

Current (draft) proposal:
  {
      "app-specific-property-1": ...,
      "app-specific-property-2": ...,

      "__cleartext_signature": {
           Signature Object (Cleartext JWS)
      }
  }

Main benefit/argument: By using a fixed name interoperability is easier to achieve. This may be a requirement for pulling through the IETF process. The unusual name eliminates clashes with applications.

 
Alternative solution:
  {
      "app-specific-property-1": ...,
      "app-specific-property-2": ...,

      "app-specific-property-n": {
           Signature Object (Cleartext JWS)
      }
  }

Main benefit/argument: Schema-driven designs do not generally benefit by "hard coded" properties. A signature property could equally well be expressed as "attestation", "authorization", "requestSignature", etc. depending on the application context.

[cyberphone]

@isamauny @MikeRalphson @timburks @danhorst @elazar Should I interpret the silence that a hard coded __cleartext_signature property as in the current draft is your preference, rather than a Signature Object which can be featured under an application specific name?

This is to be decided now, which is why there is of some urgency getting your input!

Thanx,
Anders

[MikeRalphson]

@cyberphone could you link to the current draft?

[cyberphone]

https://xml2rfc.tools.ietf.org/cgi-bin/cat.cgi/.txt?input=4d0c0e0897622dc8cbc21cb706de607c634b2c9689fb1a5ce86337-1518163603

3.  The __cleartext_signature Member

   The "__cleartext_signature" member that is added to the data contains
   the JWS header parameters and the signature value.

   When putting the header parameters into the data to be signed, they
   MUST be labeled with the key "__cleartext_signature", i.e., the
   object to be signed cannot have its own root item that is named
   "__cleartext_signature".

[cyberphone]

Pardon me, the link above apparently expires after a while...
https://xml2rfc.tools.ietf.org/cgi-bin/xml2rfc.cgi?url=https%3A%2F%2Fraw.githubusercontent.com%2Ferdtman%2FCleartext-JOSE%2Fmaster%2Fdraft-erdtman-jose-cleartext-jws.xml

[darrelmiller]

@cyberphone As I understand it, this issue is related to a reserved property name within an object that is a JWT. As such, I don't think either option you describe would have any impact OpenAPI descriptions. If the structure of the JWT token were to be described in an OpenAPI description, then we would likely use JSON schema which could describe both approaches.

[cyberphone]

@darrelmiller The new scheme is called Cleartext JWS and is not a JWT but that doesn't really matter; the question I have is more related to how "hard coded" properties fit the needs and habits of the OpenAPI development community in general.

My take on this is regarding a Cleartext JWS as a Derived Data Type, like dateTime. At least this is how I use it in my own designs. I indeed started with a fixed property but later found out that this was unnecessary and could equally well be addressed by having a suitable "default" at the API level.

However, in the actual draft a default does not make sense since it describes a data structure, not an API.

[cyberphone]

@darrelmiller After reading your blog, I came up with a highly related question:: How do "restafarians" envision signed REST requests and particularly in an OpenAPI context?

[cyberphone]

A free-standing Signature Object can also be used for signing JSON arrays:

["Hi there!",2003,{
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "censDzcMEkgiePz6DXB7cDuwFemshAFR90UNVQFCg8Q",
    "y": "xq8rze6ewG0-eVcSF72J77gKiD0IHnzpwHaU7t6nVeY"
  },
  "val": "gOIohCbkhQOftFjqHgqRuRG1qqROSzwTiW8C7FUAQzojtqtpVoOz7BOYYNRQ7e09EfDlejz7jHumAvlAlQ6txw"
}]

[pleothaud]

Hi there,

I'm Philippe Leothaud a colleague of @isamauny at 42Crunch, and I'm working atm on a proposal to explore how we could extend OAS so that it can describe JOSE-signed and JOSE-encrypted content.

With "regular" Jose artefacts, it happens that signed and/or encrypted content have a specific content-type, namely :
- the "application/jose" media type which can be used to indicate that the content is a JWS or JWE using the JWS Compact Serialization or the JWE Compact Serialization.
- the "application/jose+json" media type which can be used to indicate that the content is a JWS or JWE using the JWS JSON Serialization or the JWE JSON Serialization (general or flattened)

The JWT RFC (7519) also defines a specific content-type for JWTs, "application/jwt".

For these media types, we could therefore extend the Open API mediaType Object so that it can contain a cryptographicDefinitionsUrl field that will allow for the retrieval of the cryptographic contraints that must be fulfilled to consume the API (authorized algorithms, key to be used for encryption, authorised key type and key reference mechanisms for signature) as well as the description of the cryptographic operations computed on the API responses so that the client will know how to decrypt/verify the signature of the responses.

Another way to use signatures is to use the unencoded payload option for JWS (signatures) described by RFC 7797, leave the body of the request/response unchanged (aplication/json media type) and then pass the signature as a detached signature in a specific HTTP header (x-jws-signature is at least the name used by UK's OpenBanking). This means that you remove the payload part from the signature and the rest of the base64url encoded structure in such a header.

Here also, extending the header Open API object with the same cryptographicDefinitionsUrl field should be enough to describe the cryptographic contract.

As far as I understand, cleartext JOSE will not change content-types from regular JOSE so it should fit in the proposal.

Also, I'm to meet (hopefully) @cyberphone next week to understand better the Cleartext JOSE spec.

Last, I should have finished my proposal document by tomorrow, I will then pass it to @isamauny so that she can introduce it to the OAS group.

Thanks,

Philippe

PS: sorry for all the crypto mumbo-jumbo, all will be properly explained in my doc :-)

[cyberphone]

Hi Philippe e.t al.
Open Banking UK is a relevant application for this discussion. Here is a scaled down version of a payment operation:

POST /payments HTTP/1.1
x-jws-signature: TGlmZSdzIGEgam91cm5 ... leSBhg6fttg6gh88bfxmlf5bdDrA3
Content-Type: application/json

{
  "amount": "259.99",
  "currency": "GBP"
}

This scheme has (in my opinion NB) a number of shortcomings like:

• Ties signatures to HTTP
• Does not permit signed objects to be embedded in other objects
• Does not easily facilitate serialization of signed data
• Shrouds header data in Base64Url

A Cleartext JWS counterpart would address all the issues above:

POST /payments HTTP/1.1
Content-Type: application/json

{
  "amount": "259.99",
  "currency": "GBP",
  "signature": {
    "alg": "RS256",
    "kid": "#45233",
    "val": "Mtqlw2PPUoZSO4DAHNzZ9gk_ ... z8HsK3fE1jux6jFVrrhwSZiRaW6M"
  }
}

Remaining Problem
Strictly speaking none of those schemes properly represent a signed REST request since requests like above are only fully characterized by the HTTP Body, URL, and HTTP Verb. There are essentially three different ways of dealing with this issue:

• Current solution: ignore it. Well, Amazon do use something similar to the "right" way below
• The "right" way: https://tools.ietf.org/html/draft-cavage-http-signatures-09
• The "heretic" way: https://cyberphone.github.io/doc/web/yasmin.html

[pleothaud]

Hi Anders,

I propose we talk face to face about that next week, as discussing in this thread might be bothering to other OAS people (like comparing advantages and disadvantages of detached, enveloping and enveloped signatures...).

Just wanted to add that supporting the http-signatures standard could just be accomplished in a similar manner than I propose to support the detached signature/HTTP header OpenBanking is using: by extending the header object so that you can refer to the description of requirements to the to-be-used Signature header draft-cavage-http-signatures defines and relies on.

Thanks,

Philippe