Re: [jose] issue #25 TEXT

[Mike Jones <[e-mail]>]

Per my action item from the last call, I propose the following text to address issue #25:

8.  Detached Content

In some contexts, it is useful integrity protect content that is not itself contained in a JWS object.  There are two suggested ways of accomplishing this using JWS objects.

One way is create a JWS object containing the payload in the normal fashion, but then delete the payload representation, and send this modified object to the recipient, rather than the JWS.  This method assumes that the recipient has access to the exact payload used in the JWS.  When using the JWS Compact Serialization, the deletion is accomplished by replacing the second field (which contains BASE64URL(JWS Payload)) value with the empty string; when using the JWS JSON Serialization, the deletion is accomplished by deleting the "payload" member.  To use the modified object, the recipient reconstructs the JWS by re-inserting the payload representation into the modified object, and uses the resulting JWS in the usual manner.  Note that this method needs no support from JWS libraries, as applications can use this method by modifying the inputs and outputs of standard JWS libraries.

Another way to accomplish this is to have the JWS Payload be or include a cryptographic hash of the detached content.  The application might also include an identifier for the hash algorithm used in the JWS payload.  To use this JWS, the recipient validates the JWS in the usual way and verifies that the hash value contained in the JWS payload matches a cryptographic hash of the detached content computed by the recipient.  This method also needs no support from JWS libraries.

                                                            -- Mike

From: Jim Schaad [mailto:[e-mail]]
Sent: Sunday, September 29, 2013 1:08 PM
To: Mike Jones
Cc: [e-mail]
Subject: issue #25 TEXT

The following provides suggested text for addressing Issue #25

Jim


Text for the JWS document:

Section 7.2.1  Detached Content

Applications can do detached content with the JSON serialization.  Detached content has the benefit of allowing the content to be transmitted in a more natural format, and to avoid the expansion associated with applying the base64 transformation.  It has the downside that how the content is serialized into a text string is not preserved and therefore some type of canonicalization process may need to be applied by both the sender and the recipient.  In some circumstances this is not an issue (signing a binary file), while in other circumstances it can be problematic (end of line characters or ordering of JSON objects).  Applications cannot rely on this feature to be implemented by libraries but need to do it themselves.

On serialization, the application removes the payload value from the JSON structure before writing it out.  The contents of the signed field are then transmitted separately from the JWS structure.  For instance, the JWS serialized JSON structure could be transmitted as an HTTP header field, while the content is transmitted as  the content of the HTTP body.

On deserialization, the application obtains the to be signed value from where it is transferred, applies the necessary canonicalization and encoding to it before creating the "payload" member of the JSON structure and passing the resulting object to the library for processing.


Text for the JWE document:

Section 7.2.1 Detached Content

Applications can do detached content with the JSON serialization.  Detached content has the benefit of allowing the content to be transmitted in a more natural format, and to avoid the expansion associated with applying the base64 transformation.  Since the output of the encryption process is always an octet string, there are no canonicalization issues associated with transporting the encrypted string separately from the encryption header.

On serialization, the application removes the "ciphertext" field from the JSON structure before writing it out.  The contents of the "ciphertext" field then have the base64 encoding removed and it is transmitted separated from the JWE structure.  For instance, the JWE serialized JSON structure could be transmitted as an HTTP header field, while the cipher  text could be transmitted using binary transfer encoding as the HTTP body.

On deserialization, the application obtains the cipher text from where it was transferred, applies the base64 transfer encoding and places it in the "ciphertext" member of the JWE JSON structure.  The resulting object is then passed to the JOSE library for process.