From b6ec4d4bfc65a64fb049248f94556ff69d793f86 Mon Sep 17 00:00:00 2001 From: "Zhenyu (Adam) Wu" <85357044+AdamZWu@users.noreply.github.com> Date: Mon, 30 Oct 2023 15:46:52 -0400 Subject: [PATCH] Update envelope.md Co-authored-by: Mark Lodato --- envelope.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/envelope.md b/envelope.md index ec83513..4114884 100644 --- a/envelope.md +++ b/envelope.md @@ -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