Re: [Acme] Specify which JWS serialization is used

[Logan Widick <[e-mail]>]

How about this: Specify a default format (either "application/jose" for
Compact Serialization, or "application/jose+json" with Flattened
Serialization - I have no preference which one), with optional support for
other formats if needed? Even with JOSE libraries that don't support all
serializations and/or don't provide control over which serialization is
used, a programmer would at least need to know (or experimentally find out)
if a JSON serialization or if the compact one is being produced. If a JSON
serialization is selected as the default, a programmer should be able to
convert between the two JSON serializations easily as needed before and/or
after using a JOSE library. If a JSON format is declared as the default but
the JOSE library only has the compact one, or vice-versa, conversion before
and/or after the JOSE library would be more complex but should still be
doable with guidance.

The directory meta item could be defined as something like:

   - supportedSerializations: An array of supported serialization formats
   as described in {{jws-serialization-formats}}. If this is not specified,
   assume that the server only supports [insert selected default here].

Then, the JWS Serialization Formats section could be changed to something
like the following:

The JSON Web Signature (JWS) specification {{!RFC7515}} contains multiple
JWS serialization formats. When sending an ACME request with a non-empty
body, an ACME client implementation SHOULD use the HTTP Content-Type
{{!RFC7231}} header to indicate which JWS serialization format is used for
encapsulating the ACME request payload.

Each serialization format defined for use in ACME is described with a
content type, and a series of ACME-specific restrictions on root JWS and
nested JWS instances.  A "root JWS" is a JWS used to encapsulate an entire
ACME request payload, and a "nested JWS" is a JWS contained within the ACME
request payload (such as the "externalAccountBinding" described in
{{external-account-binding}} or the "key-change" object described in
{{account-key-roll-over}}). Below are the JWS serialization formats that
are defined for use in ACME:

[same list as before but with the default format coming first]

If no Content-Type is provided, the default serialization type is [insert
selected default here]. Servers MUST support [insert selected default
here]. [NOTE: If a JSON format is selected as the default, say that a
server SHOULD support the other JSON format.] A server MAY support
additional serializations, such as [insert serialization(s) not picked
here], by including a "supportedSerializations" field in the directory
"meta" object as described in {{directory}}.

If a server receives a request using a serialization it does not support,
the server MUST send a response with HTTP status code 415 (Unacceptable
Media Type) and a problem document with error type
"unsupportedSerialization". This problem document SHOULD contain a
"supportedSerializations" array of strings indicating the acceptable
serialization content types.

[TODO: If a client uses the General JSON Serialization but it turns out the
server only supports the Flattened JSON Serialization (or vice-versa),
explain that a 415 response indicates that the client will need to switch
JSON formats]

[TODO: Insert a sentence or two specifying what happens if a supported
serialization is used but the serialization is malformed? Should this be
400 Bad Request + malformed error code + supportedSerializations?]

In the examples below, JWS objects are shown in the Flattened JSON
serialization, with the protected header and payload expressed as
base64url(content) instead of the actual base64-encoded value, so that the
content is readable. [Example readability is a very high priority
regardless of which serialization format is actually chosen as the default,
and the current convention of Flattened JSON + base64url(content) is about
as readable as it gets, so I don't think any changes will need to be made
here]


On Sun, Mar 4, 2018 at 8:33 AM, Jörn Heissler <[e-mail]>
wrote:

> On Sun, Mar 04, 2018 at 07:45:36 -0600, Logan Widick wrote:
> > Good catch. Should it be 415 (Unsupported Media Type) plus which of the
> > following (or which combination of the following):
> >
> >    - A new problem document field (tentatively named
> >    "supportedSerializations": an array of media type strings)?
> >    - A new directory field (tentatively named "supportedSerializations":
> an
> >    array of media type strings)?
> >       - Should this go in the directory's "meta" object, or in the
> >       directory object itself?
> >    - A HTTP header?
> >    - Something else?
>
> I like the directory approach with meta. Then a client could
> use this information before sending the first POST. Else the client
> would need to change an internal state after receiving the error
> message. For my own client, I'm planning to support the OpenPGP smart
> card. It takes 3 seconds to generate a signature. If a signature is
> wasted to find out that the default serialization is not supported, it
> would be annoying. Having to write a configuration file "use compact by
> default for CA foo" would be stupid too.
>
> This, and the problem document field. "supportedSerializations" sounds
> fine.
>
> Should the two features be OPTIONAL?
>
> I don't like HTTP headers, it's quite complicated to parse them correctly.
> JSON is so much easier.
>
>
> Or... specify that flattened MUST BE used :-)
>
> Cheers
> Joern Heissler
>