Merge branch 'multi-signature' into 'cleanups'

MarkLodato · MarkLodato · commit cd962c1c1dc0 · 2020-12-08T17:51:40.000-05:00
diff --git a/specification.md b/specification.md
@@ -33,13 +33,16 @@ The signature format is a JSON message of the following form:
   "payload": "<Base64(SERIALIZED_BODY)>",
   "payloadType": "<PAYLOAD_TYPE>",
   "signatures": [{
-    …,
+    "keyid": "<KEYID>",
     "sig": "<Base64(Sign(PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY)))>"
-  }, …]
+  }]
 }
 ```
 
-where:
+Empty fields may be omitted. [Multiple signatures](#multiple-signatures) are
+allowed.
+
+Parameters:
 
 *   SERIALIZED_BODY is the byte sequence to be signed.
 
@@ -55,6 +58,11 @@ where:
     -   https://theupdateframework.com/Root/v1.0.5
     -   etc...
 
+*   KEYID is an optional, unauthenticated hint indicating what key was used to
+    sign the message. It **must not** be used for security decisions.
+
+Functions:
+
 *   PAE() is the
     [PASETO Pre-Authentication Encoding](https://github.com/paragonie/paseto/blob/master/docs/01-Protocol-Versions/Common.md#authentication-padding),
     where parameters `type` and `body` are byte sequences:
@@ -88,6 +96,7 @@ To sign:
     SERIALIZED_BODY.
 -   Sign PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY), base64-encode the result, and
     store it in `sig`.
+-   Optionally, compute a KEYID and store it in `keyid`.
 -   Base64-encode SERIALIZED_BODY and store it in `payload`.
 -   Store PAYLOAD_TYPE in `payloadType`.
 
@@ -116,9 +125,9 @@ valid while avoiding the verifier from having to use [Canonical JSON].
   "payload": "<Base64(CanonicalJson(BODY))>",
   "payloadType": "<URI>/backwards-compatible-json",
   "signatures" : [{
-    …,
-    "sig" : "<Base64(Sign(CanonicalJson(BODY)))>"
-  }, …]
+    "keyid": "<KEYID>",
+    "sig": "<Base64(Sign(CanonicalJson(BODY)))>"
+  }]
 }
 ```
 
@@ -129,6 +138,7 @@ To sign:
 -   BODY **must** be an object type (`{...}`).
 -   Serialize BODY as [Canonical JSON]; call this SERIALIZED_BODY.
 -   Sign SERIALIZED_BODY, base64-encode the result, and store it in `sig`.
+-   Optionally, compute a KEYID and store it in `keyid`.
 -   Base64-encode SERIALIZED_BODY and store it in `payload`.
 -   Store `"<URI>/backwards-compatible-json"` in `payloadType`.
 
@@ -152,6 +162,25 @@ This scheme is safe from rollback attacks because the first byte of
 SERIALIZED_BODY must be 0x7b (`{`) in backwards compatibility mode and 0x02 in
 regular mode.
 
+### Multiple signatures
+
+A file may have more than one signature, which is equivalent to separate files
+with individual signatures.
+
+```json
+{
+  "payload": "<Base64(SERIALIZED_BODY)>",
+  "payloadType": "<PAYLOAD_TYPE>",
+  "signatures": [{
+      "keyid": "<KEYID_1>",
+      "sig": "<SIG_1>"
+    }, {
+      "keyid": "<KEYID_2>",
+      "sig": "<SIG_2>"
+  }]
+}
+```
+
 ### Optional changes to wrapper
 
 The standard wrapper is JSON with an explicit `payloadType`. Optionally,
@@ -286,9 +315,9 @@ over the [Canonical JSON] serialization of BODY.
 {
   "signed": <BODY>,
   "signatures": [{
-    …,
+    "keyid": "<KEYID>",
     "sig": "<Hex(Sign(CanonicalJson(BODY)))>"
-  }, …]
+  }]
 }
 ```
 
@@ -307,11 +336,13 @@ To convert an existing signature to the new format:
 -   `new.payload = base64encode(CanonicalJson(orig.signed))`
 -   `new.payloadType = "<URI>/backwards-compatible-json"`
 -   `new.signatures[*].sig = base64encode(hexdecode(orig.signatures[*].sig))`
+-   `new.signatures[*].keyid = orig.signatures[*].keyid`
 
 To convert a backwards compatible signature to the old format:
 
 -   `old.signed = jsonparse(base64decode(new.payload))`
 -   `old.signatures[*].sig = hexencode(base64decode(new.signatures[*].sig))`
+-   `old.signatures[*].keyid = new.signatures[*].keyid`
 
 ## Testing
 
