Skip to content

Commit b6ec4d4

Browse files
AdamZWuMarkLodato
andauthored
Update envelope.md
Co-authored-by: Mark Lodato <[email protected]>
1 parent 8cf47ba commit b6ec4d4

File tree

1 file changed

+16
-14
lines changed

1 file changed

+16
-14
lines changed

envelope.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -32,20 +32,22 @@ the following form, called the "JSON envelope":
3232

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

35-
Arbitrary binary data can be encode in [Base64](https://tools.ietf.org/html/rfc4648),
36-
as a unicode string and enclosed in the envelope using the `payload` key.
37-
Either standard or URL-safe encoding is allowed.
38-
39-
However, if the serialized payload body is a text string, it can *instead* be
40-
encoded in [UTF-8](https://tools.ietf.org/html/rfc3629) and enclosed in the
41-
envelope using the `payloadUtf8` key. The UTF-8 encoding has a lower overhead
42-
than Base64 for texts, and is more friendly for compression algorithms.
43-
44-
Note:
45-
46-
1. Use either the `payload` or `payloadUtf8` key in an envelope, not both;
47-
2. The choice of payload encoding does not impact
48-
[the signing or the signatures](protocol.md#signature-definition).
35+
Exactly one of `payload` or `payloadUtf8` MUST be set:
36+
37+
- `payload` supports arbitrary SERIALIZED_BODY.
38+
[Base64Encode()](https://tools.ietf.org/html/rfc4648) transforms a byte
39+
sequence to a Unicode string. Base64 has a fixed 33% space overhead but
40+
supports payloads that are not necessarily valid UTF-8. Either standard or
41+
URL-safe encoding is allowed.
42+
43+
- `payloadUtf8` only supports valid
44+
[UTF-8](https://tools.ietf.org/html/rfc3629) SERIALIZED_BODY. `Utf8Decode()`
45+
converts that UTF-8 byte sequence to a Unicode string. Regular JSON string
46+
escaping applies, but this is usually more compact and amenable to
47+
compression than Base64.
48+
49+
Note: The choice of `payload` vs `payloadUtf8` does not impact the
50+
[the signing or the signatures](protocol.md#signature-definition).
4951

5052
### Multiple signatures
5153

0 commit comments

Comments
 (0)