Add support for x509 certificates in DSSE

envelope.md

@@ -22,7 +22,8 @@ the following form, called the "JSON envelope":
   "payloadType": "<PAYLOAD_TYPE>",
   "signatures": [{
     "keyid": "<KEYID>",
-    "sig": "<Base64(SIGNATURE)>"
+    "sig": "<Base64(SIGNATURE)>",
+    "cert": "<PEM(CERTIFICATE)>"
   }]
 }
 ```
@@ -33,6 +34,8 @@ 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.
 
+PEM() is a [PEM encoding](), transforming a DER (binary) encoded X.509 certificate to a base64 encoding with a one-line header and footer.
+
 ### Multiple signatures
 
 An envelope MAY have more than one signature, which is equivalent to separate
@@ -44,10 +47,12 @@ envelopes with individual signatures.
   "payloadType": "<PAYLOAD_TYPE>",
   "signatures": [{
       "keyid": "<KEYID_1>",
-      "sig": "<SIG_1>"
+      "sig": "<SIG_1>",
+      "cert": "<CERT_1>"
     }, {
       "keyid": "<KEYID_2>",
-      "sig": "<SIG_2>"
+      "sig": "<SIG_2>",
+      "cert": "<CERT_2>"
   }]
 }
 ```
@@ -56,7 +61,7 @@ envelopes with individual signatures.
 
 *   The following fields are REQUIRED and MUST be set, even if empty: `payload`,
     `payloadType`, `signature`, `signature.sig`.
-*   The following fields are OPTIONAL and MAY be unset: `signature.keyid`.
+*   The following fields are OPTIONAL and MAY be unset: `signature.keyid`, `signature.cert`
     An unset field MUST be treated the same as set-but-empty.
 *   Producers, or future versions of the spec, MAY add additional fields.
     Consumers MUST ignore unrecognized fields.

envelope.proto

@@ -32,4 +32,8 @@ message Signature {
   // *Unauthenticated* hint identifying which public key was used.
   // OPTIONAL.
   string keyid = 2;
+
+  // *Unauthenticated* PEM encoded X.509 certificate corresponding to the public key.
+  // OPTIONAL.
+  string cert = 3;
 }

implementation/signing_spec.py

@@ -56,6 +56,9 @@ def keyid(self) -> Optional[str]:
         """Returns the ID of this key, or None if not supported."""
         ...
 
+    def certificate(self) -> Optional[str]:
+        """Returns the certificate of the key, or None if not supported."""
+
 
 class Verifier(Protocol):
     def verify(self, message: bytes, signature: bytes) -> bool:
@@ -66,10 +69,16 @@ def keyid(self) -> Optional[str]:
         """Returns the ID of this key, or None if not supported."""
         ...
 
+class RootPool(Protocol):
+    def verify(self, certificate: bytes) -> bool:
+        """Returns true if `certificate` chains back to the Root pool."""
 
 # Collection of verifiers, each of which is associated with a name.
 VerifierList = Iterable[Tuple[str, Verifier]]
 
+# A root certificate pool.
+Root = RootPool
+
 
 @dataclasses.dataclass
 class VerifiedPayload:
@@ -100,17 +109,20 @@ def Sign(payloadType: str, payload: bytes, signer: Signer) -> str:
     signature = {
         'keyid': signer.keyid(),
         'sig': b64enc(signer.sign(PAE(payloadType, payload))),
+        'cert': signer.cert(),
     }
     if not signature['keyid']:
         del signature['keyid']
+    if not signature['cert']:
+        del signature['cert']
     return json.dumps({
         'payload': b64enc(payload),
         'payloadType': payloadType,
         'signatures': [signature],
     })
 
 
-def Verify(json_signature: str, verifiers: VerifierList) -> VerifiedPayload:
+def Verify(json_signature: str, verifiers: VerifierList, root: RootPool) -> VerifiedPayload:
     wrapper = json.loads(json_signature)
     payloadType = wrapper['payloadType']
     payload = b64dec(wrapper['payload'])
@@ -122,8 +134,9 @@ def Verify(json_signature: str, verifiers: VerifierList) -> VerifiedPayload:
                 verifier.keyid() is not None and
                 signature.get('keyid') != verifier.keyid()):
                 continue
-            if verifier.verify(pae, b64dec(signature['sig'])):
-                recognizedSigners.append(name)
+            if (verifier.verify(pae, b64dec(signature['sig'])) and
+                root.verify(signature['cert'])):
+                    recognizedSigners.append(name)
     if not recognizedSigners:
         raise ValueError('No valid signature found')
     return VerifiedPayload(payloadType, payload, recognizedSigners)

protocol.md

@@ -23,6 +23,7 @@ Name            | Type   | Required | Authenticated
 SERIALIZED_BODY | bytes  | Yes      | Yes
 PAYLOAD_TYPE    | string | Yes      | Yes
 KEYID           | string | No       | No
+CERTIFICATE     | string | No       | No
 
 *   SERIALIZED_BODY: Arbitrary byte sequence to be signed.
 
@@ -52,6 +53,11 @@ KEYID           | string | No       | No
     decisions; it may only be used to narrow the selection of possible keys to
     try.
 
+*   CERTIFICATE: Optional, unauthenticated PEM encoded X.509 certificate for the key
+    used to sign the message. As with Sign(), details are agreed upon
+    out-of-band by the signer and verifier. This ensures the necessary information
+    to verify the signature remains alongside the metadata.
+
 Functions:
 
 *   PAE() is the "Pre-Authentication Encoding", where parameters `type` and
@@ -77,7 +83,7 @@ Functions:
 Out of band:
 
 -   Agree on a PAYLOAD_TYPE and cryptographic details, optionally including
-    KEYID.
+    KEYID and trusted root certificates.
 
 To sign:
 
@@ -90,12 +96,13 @@ To sign:
 
 To verify:
 
--   Receive and decode SERIALIZED_BODY, PAYLOAD_TYPE, SIGNATURE, and KEYID, such
-    as from the recommended [JSON envelope](envelope.md). Reject if decoding
-    fails.
+-   Receive and decode SERIALIZED_BODY, PAYLOAD_TYPE, SIGNATURE, KEYID, and 
+    CERTIFICATE such as from the recommended [JSON envelope](envelope.md). 
+    Reject if decoding fails.
 -   Optionally, filter acceptable public keys by KEYID.
 -   Verify SIGNATURE against PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY). Reject if
     the verification fails.
+-   Optionally, verify the signing key's CERTIFICATE links back to a trusted root.
 -   Reject if PAYLOAD_TYPE is not a supported type.
 -   Parse SERIALIZED_BODY according to PAYLOAD_TYPE. Reject if the parsing
     fails.