@@ -32,20 +32,22 @@ the following form, called the "JSON envelope":
32
32
33
33
See [ Protocol] ( protocol.md ) for a definition of parameters and functions.
34
34
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 ) .
49
51
50
52
### Multiple signatures
51
53
0 commit comments