Re: [Acme] Specify which JWS serialization is used

[Martin Thomson <[e-mail]>]

That's a bit silly.  I'll follow-up with httpbis.  I think that's an
error, though probably only an error of omission.  7694 was so fixated
on solving the content-coding issue, it neglected the obvious
accompanying fix.

On Mon, Mar 5, 2018 at 9:38 AM, Richard Barnes <[e-mail]> wrote:
> How about Accept?  It looks like 7694 gives the server a way to specify
> encodings, but not the content type.  But 7231 says that Accept only replies
> to response media types.
>
> On Sun, Mar 4, 2018 at 5:33 PM, Martin Thomson <[e-mail]>
> wrote:
>>
>> 415 is for the case where a client provides bad request content, so yes.
>> See rfc7694 for details.
>>
>>  406 is for failed conneg. Not something you expect to see much here.
>>
>>
>> On 5 Mar. 2018 09:25, "Richard Barnes" <[e-mail]> wrote:
>>
>> The lengths of the emails in this thread illustrate the complexity risk
>> here :)
>>
>> In the interest of simplicity, I would really like to stick to Flattened
>> JSON unless someone has **strong** objections.
>>
>> Logan, to your point about library compatibility, two notes: (1) it's OK
>> if we front-run libraries a little.  It's not hard for libraries to upgrade;
>> this is only formatting, no crypto changes needed.  (2) Empirically, this
>> must not be too big a blocker for people, since as Jacob notes, Let's
>> Encrypt only supports Flattened JSON right now and they've got a bunch of
>> clients talking to them.
>>
>> As far as headers / response codes: You're correct that 406 is wrong / 415
>> is right.  But ISTM that Accept is still the right header to say what is
>> right.  So the server should return 415+Accept.  Copying Thomson to check
>> our work here.
>>
>> --Richard
>>
>> On Sun, Mar 4, 2018 at 10:43 AM, Logan Widick <[e-mail]>
>> wrote:
>>>
>>> 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
>>>
>>>
>>
>>
>