Add UTF-8 encoding option to the envelope document and proto.

Signed-off-by: Zhenyu (Adam) Wu <[email protected]>

Author: AdamZWu

envelope.md

@@ -18,7 +18,12 @@ the following form, called the "JSON envelope":
 
 ```json
 {
-  "payload": "<Base64(SERIALIZED_BODY)>",
+  // Arbitrary binary data can be encode in base64.
+  "payload": "<Base64(byte sequence)>",
+  // If the SERIALIZED_BODY is a text string,
+  // it can *instead* be encoded in UTF-8. 
+  // "payloadUtf8": "<Utf-8 encoded text>",
+
   "payloadType": "<PAYLOAD_TYPE>",
   "signatures": [{
     "keyid": "<KEYID>",
@@ -29,9 +34,20 @@ the following form, called the "JSON envelope":
 
 See [Protocol](protocol.md) for a definition of parameters and functions.
 
-Base64() is [Base64 encoding](https://tools.ietf.org/html/rfc4648), transforming
-a byte sequence to a unicode string. Either standard or URL-safe encoding is
-allowed.
+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).
 
 ### Multiple signatures
 
@@ -41,6 +57,7 @@ envelopes with individual signatures.
 ```json
 {
   "payload": "<Base64(SERIALIZED_BODY)>",
+  // Or "payloadUtf8": "<Utf-8 encoded text>",
   "payloadType": "<PAYLOAD_TYPE>",
   "signatures": [{
       "keyid": "<KEYID_1>",
@@ -54,8 +71,8 @@ envelopes with individual signatures.
 
 ### Parsing rules
 
-*   The following fields are REQUIRED and MUST be set, even if empty: `payload`,
-    `payloadType`, `signature`, `signature.sig`.
+*   The following fields are REQUIRED and MUST be set, even if empty:
+    one of (`payload`, `payloadUtf8`), `payloadType`, `signature`, `signature.sig`.
 *   The following fields are OPTIONAL and MAY be unset: `signature.keyid`.
     An unset field MUST be treated the same as set-but-empty.
 *   Producers, or future versions of the spec, MAY add additional fields.

envelope.proto

@@ -4,10 +4,15 @@ package io.intoto;
 
 // An authenticated message of arbitrary type.
 message Envelope {
-  // Message to be signed. (In JSON, this is encoded as base64.)
+  // Message to be signed.
   // REQUIRED.
-  bytes payload = 1;
-
+  oneof payload_encoding {
+    // Raw bytes. In JSON, this is encoded as base64.
+    bytes payload = 1;
+    // Unicode string, where the signed byte stream is the UTF-8 encoding. In JSON, this is a regular unicode string.
+    string payloadUtf8 = 4;
+  }
+  
   // String unambiguously identifying how to interpret payload.
   // REQUIRED.
   string payloadType = 2;