Draft: draft-ietf-acme-acme

Commentary: This change is designed to partially address the JWS serialization format issues raised in the and threads on the mailing list . This change uses the Content - Type header to specify JWS serialization formats , and includes restrictions on the serializations . It does n't include converting between serializations , or how to handle inner  messages . In short , this change should be a cleaner version of that still allows the compact serialization . Specifically , this change requires ACME implementations to use the HTTP Content - Type header to indicate the JWS serialization format used for the request body . The change also specifies restrictions on the specific serialization formats when used with ACME ( do n't use unencoded payloads , do n't use detached payloads , do n't use unprotected headers ) . In addition , the change prohibits multiple signatures in JWS objects used for ACME purposes . This change does n't include advice on how to convert between the JWS serializations . Converting between  serializations may be needed if , for example , an ACME implementation uses a JWS library that does n't support all JWS serializations and/or does n't provide programmers with control over what JWS serialization is produced . In such cases , programmers may have to convert between  serializations before and/or after using said pre - existing JWS library . I have started a draft of a separate JOSE serialization conversion guide at The separate conversion guide is designed to not be ACME - specific . Accordingly , the separate conversion guide includes things like unencoded payloads , detached payloads , unprotected headers , and JWEs . One thing that is not included in this change is how the serialization format requirements should be applied to a " nested " JWS like the one found in a key change or an external account binding . Should a " nested " JWS be required to use the same serialization as the " outer "  ? If a nested JWS should follow the outer JWS serialization format , the following additional changes may need to be made : Change the new " JWS Serialization Formats " section ( introduced in this pull request ) . For example , the list in that section could be changed to the following : Content - Type " application / jose " : A JWS of this Content - Type MUST meet the following criteria : The JWS Compact Serialization { { ! RFC7515 } } MUST be used . The JWS Payload MUST NOT be detached . The JWS Unencoded Payload Option { { ! RFC7797 } } MUST NOT be used . A JWS placed anywhere inside the payload of a JWS of this Content - Type MUST meet the above criteria as well . Content - Type " application /  " : A JWS of this Content - Type MUST meet the following criteria : Either the JWS Flattened JSON { { ! RFC7515 } } or the JWS General JSON { { ! RFC7515 } } Serialization MUST be used . The JWS Payload MUST NOT be detached . The JWS Unencoded Payload Option { { ! RFC7797 } } MUST NOT be used . The JWS Unprotected Header { { ! RFC7515 } } SHOULD NOT be used . A JWS placed anywhere inside the payload of a JWS of this Content - Type MUST meet the above criteria as well . Update the specifications for the nested JWS : Right now , " externalAccountBinding " can be an object . If this JWS must follow the same guidelines as the outer  , " externalAccountBinding " could be an " object or string " , depending on whether a  or compact serialization is used . If I understand correctly , the payload of the outer  for the " keyChange " ( Account Key Roll - Over ) endpoint is not a JSON object like in the other ACME requests . Instead , the payload for the " outer "  for this endpoint is merely this nested JWS itself . If this understanding is correct , I do n't think any changes have to be made . If this understanding is not correct , I am not sure what changes may have to be made . 
 I verified locally that this branch passes  tests . For some reason , I do n't have permission to re - run  . I 'm about to send another PR on top of this one to fix a minor bug , so CI will run then .
Paragraph (version B):
The JWS MUST NOT have multiple signatures.
Paragraph (version A):
In the examples below, JWS objects are shown in the JSON or 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.
Paragraph (version B):
The JWS Compact Serialization RFC7515 MUST be used.
Paragraph (version B):
Either the JWS Flattened JSON Serialization RFC7515 or the JWS
General JSON Serialization RFC7515 MUST be used.
Paragraph (version B):
The JWS Unprotected Header RFC7515 SHOULD NOT be used.
Paragraph (version B):
In the examples below, JWS objects are shown in the General JSON or
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.