Require inclusion proofs, make promises optional (#84)

* Require inclusion proofs, make promises optional The log always generates inclusion proofs, so we will make it a requirement that clients verify the proof. Promises will be deprecated over time, but for now, we'll make them optional. Fixes #82 Ref sigstore/rekor#1566 Signed-off-by: Hayden Blauzvern <[email protected]> * Bump version Signed-off-by: Hayden Blauzvern <[email protected]> * Update client verification requirements for promises Signed-off-by: Hayden Blauzvern <[email protected]> --------- Signed-off-by: Hayden Blauzvern <[email protected]>
sigstore · Jul 3, 2023 · b532639 · b532639
1 parent 5ef5406
commit b532639
Show file tree

Hide file tree

Showing 15 changed files with 84 additions and 48 deletions.
diff --git a/gen/pb-go/bundle/v1/sigstore_bundle.pb.go b/gen/pb-go/bundle/v1/sigstore_bundle.pb.go
diff --git a/gen/pb-go/rekor/v1/sigstore_rekor.pb.go b/gen/pb-go/rekor/v1/sigstore_rekor.pb.go
diff --git a/gen/pb-go/trustroot/v1/sigstore_trustroot.pb.go b/gen/pb-go/trustroot/v1/sigstore_trustroot.pb.go
diff --git a/gen/pb-python/pyproject.toml b/gen/pb-python/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "sigstore-protobuf-specs"
-version = "0.1.0"
+version = "0.2.0"
 description = "A library for serializing and deserializing Sigstore messages"
 readme = "README.md"
 license = { file = "LICENSE" }

diff --git a/gen/pb-python/sigstore_protobuf_specs/dev/sigstore/bundle/v1/__init__.py b/gen/pb-python/sigstore_protobuf_specs/dev/sigstore/bundle/v1/__init__.py
diff --git a/gen/pb-python/sigstore_protobuf_specs/dev/sigstore/rekor/v1/__init__.py b/gen/pb-python/sigstore_protobuf_specs/dev/sigstore/rekor/v1/__init__.py
diff --git a/gen/pb-python/sigstore_protobuf_specs/dev/sigstore/trustroot/v1/__init__.py b/gen/pb-python/sigstore_protobuf_specs/dev/sigstore/trustroot/v1/__init__.py
diff --git a/gen/pb-ruby/lib/sigstore_protobuf_specs/version.rb b/gen/pb-ruby/lib/sigstore_protobuf_specs/version.rb
@@ -16,6 +16,6 @@
 
 module Dev
   module Sigstore
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end
diff --git a/gen/pb-typescript/package.json b/gen/pb-typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sigstore/protobuf-specs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "code-signing for npm packages",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

diff --git a/gen/pb-typescript/src/__generated__/sigstore_bundle.ts b/gen/pb-typescript/src/__generated__/sigstore_bundle.ts
diff --git a/gen/pb-typescript/src/__generated__/sigstore_rekor.ts b/gen/pb-typescript/src/__generated__/sigstore_rekor.ts
diff --git a/gen/pb-typescript/src/__generated__/sigstore_trustroot.ts b/gen/pb-typescript/src/__generated__/sigstore_trustroot.ts
diff --git a/protos/sigstore_bundle.proto b/protos/sigstore_bundle.proto
@@ -31,8 +31,8 @@ option java_outer_classname = "BundleProto";
 // The primary message ('Bundle') MUST be versioned, by populating the
 // 'media_type' field. Semver-ish (only major/minor versions) scheme MUST
 // be used. The current version as specified by this file is:
-// application/vnd.dev.sigstore.bundle+json;version=0.1
-// The semantic version is thus '0.1'.
+// application/vnd.dev.sigstore.bundle+json;version=0.2
+// The semantic version is thus '0.2'.
 
 // Various timestamped counter signatures over the artifacts signature.
 // Currently only RFC3161 signatures are provided. More formats may be added
@@ -53,15 +53,22 @@ message VerificationMaterial {
                 dev.sigstore.common.v1.PublicKeyIdentifier public_key = 1 [(google.api.field_behavior) = REQUIRED];
                 dev.sigstore.common.v1.X509CertificateChain x509_certificate_chain = 2 [(google.api.field_behavior) = REQUIRED];
         }
-        // This is the inclusion promise and/or proof, where
-        // the timestamp is coming from the transparency log.
+        // This is the inclusion proof, where the timestamp is coming from
+        // the transparency log.
+        // Client verification libraries MAY provide an option to support v0.1
+        // bundles for backwards compatibility, which may contain an inclusion
+        // promise and not an inclusion proof. In this case, the client MUST
+        // validate the promise.
+        // Verifiers SHOULD NOT allow v0.1 bundles if they're used in an
+        // ecosystem which never produced them.
         repeated dev.sigstore.rekor.v1.TransparencyLogEntry tlog_entries = 3;
         // Timestamp verification data, over the artifact's signature.
         TimestampVerificationData timestamp_verification_data = 4;
 }
 
 message Bundle {
         // MUST be application/vnd.dev.sigstore.bundle+json;version=0.1
+        // or application/vnd.dev.sigstore.bundle+json;version=0.2
         // when encoded as JSON.
         string media_type = 1;
         // When a signer is identified by a X.509 certificate, a verifier MUST

diff --git a/protos/sigstore_rekor.proto b/protos/sigstore_rekor.proto
@@ -46,7 +46,7 @@ message Checkpoint {
 }
 
 // InclusionProof is the proof returned from the transparency log. Can
-// be used for on line verification against the log.
+// be used for offline or online verification against the log.
 message InclusionProof {
         // The index of the entry in the log.
         int64 log_index = 1 [(google.api.field_behavior) = REQUIRED];
@@ -87,7 +87,7 @@ message InclusionPromise {
 // attributes (excluding the payload) that are required for verifying the
 // inclusion promise. The inclusion promise (called SignedEntryTimestamp in
 // the response from Rekor) is similar to a Signed Certificate Timestamp
-// as described here https://www.rfc-editor.org/rfc/rfc9162#name-signed-certificate-timestam.
+// as described here https://www.rfc-editor.org/rfc/rfc6962.html#section-3.2.
 message TransparencyLogEntry {
         // The index of the entry in the log.
         int64 log_index = 1 [(google.api.field_behavior) = REQUIRED];
@@ -100,11 +100,13 @@ message TransparencyLogEntry {
         // The UNIX timestamp from the log when the entry was persisted.
         int64 integrated_time = 4 [(google.api.field_behavior) = REQUIRED];
         // The inclusion promise/signed entry timestamp from the log.
-        InclusionPromise inclusion_promise = 5 [(google.api.field_behavior) = REQUIRED];
-        // The inclusion proof can be used for online verification that the
-        // entry was appended to the log, and that the log has not been
+        // Required for v0.1 bundles, and MUST be verified.
+        // Optional for >= v0.2 bundles, and SHOULD be verified when present.
+        InclusionPromise inclusion_promise = 5;
+        // The inclusion proof can be used for offline or online verification
+        // that the entry was appended to the log, and that the log has not been
         // altered.
-        InclusionProof inclusion_proof = 6;
+        InclusionProof inclusion_proof = 6 [(google.api.field_behavior) = REQUIRED];
         // Optional. The canonicalized transparency log entry, used to
         // reconstruct the Signed Entry Timestamp (SET) during verification.
         // The contents of this field are the same as the `body` field in

diff --git a/protos/sigstore_trustroot.proto b/protos/sigstore_trustroot.proto
@@ -27,7 +27,7 @@ option java_outer_classname = "TrustRootProto";
 // See https://www.rfc-editor.org/rfc/rfc9162.html#name-log-parameters
 // for more details.
 // The included parameters are the minimal set required to identify a log,
-// and verify an inclusion promise.
+// and verify an inclusion proof/promise.
 message TransparencyLogInstance {
         // The base URL at which can be used to URLs for the client.
         string base_url = 1;