Skip to content

Commit

Permalink
Update envelope.md
Browse files Browse the repository at this point in the history
Co-authored-by: Mark Lodato <[email protected]>
  • Loading branch information
AdamZWu and MarkLodato authored Oct 30, 2023
1 parent 8cf47ba commit b6ec4d4
Showing 1 changed file with 16 additions and 14 deletions.
30 changes: 16 additions & 14 deletions envelope.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,20 +32,22 @@ the following form, called the "JSON envelope":

See [Protocol](protocol.md) for a definition of parameters and functions.

Arbitrary binary data can be encode in [Base64](https://tools.ietf.org/html/rfc4648),
as a unicode string and enclosed in the envelope using the `payload` key.
Either standard or URL-safe encoding is allowed.

However, if the serialized payload body is a text string, it can *instead* be
encoded in [UTF-8](https://tools.ietf.org/html/rfc3629) and enclosed in the
envelope using the `payloadUtf8` key. The UTF-8 encoding has a lower overhead
than Base64 for texts, and is more friendly for compression algorithms.

Note:

1. Use either the `payload` or `payloadUtf8` key in an envelope, not both;
2. The choice of payload encoding does not impact
[the signing or the signatures](protocol.md#signature-definition).
Exactly one of `payload` or `payloadUtf8` MUST be set:

- `payload` supports arbitrary SERIALIZED_BODY.
[Base64Encode()](https://tools.ietf.org/html/rfc4648) transforms a byte
sequence to a Unicode string. Base64 has a fixed 33% space overhead but
supports payloads that are not necessarily valid UTF-8. Either standard or
URL-safe encoding is allowed.

- `payloadUtf8` only supports valid
[UTF-8](https://tools.ietf.org/html/rfc3629) SERIALIZED_BODY. `Utf8Decode()`
converts that UTF-8 byte sequence to a Unicode string. Regular JSON string
escaping applies, but this is usually more compact and amenable to
compression than Base64.

Note: The choice of `payload` vs `payloadUtf8` does not impact the
[the signing or the signatures](protocol.md#signature-definition).

### Multiple signatures

Expand Down

0 comments on commit b6ec4d4

Please sign in to comment.