Subject: [jose] FW: issue #25 TEXT

From: "Jim Schaad" <[email-masked]>
Date: Mon, 7 Oct 2013 16:06:23 -0700

From: Jim Schaad [mailto:[email-masked]] 
Sent: Sunday, September 29, 2013 1:08 PM
To: Mike Jones ([email-masked])
Cc: [email-masked]
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.