Clarified the intent of the listed instances in the trusted_root (#80)

* Clarified the intent of the listed instances in the trusted_root message. The semantics around valid_for was not properly explained and could lead to confusion. Signed-off-by: Fredrik Skogman <[email protected]> * Update protos/sigstore_trustroot.proto Co-authored-by: Hayden B <[email protected]> Signed-off-by: Fredrik Skogman <[email protected]> * Updated generated files Signed-off-by: Fredrik Skogman <[email protected]> --------- Signed-off-by: Fredrik Skogman <[email protected]> Co-authored-by: Hayden B <[email protected]>
sigstore · May 18, 2023 · 5ef5406 · 5ef5406
1 parent 91485b4
commit 5ef5406
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 16 deletions.
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/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-typescript/src/__generated__/sigstore_trustroot.ts b/gen/pb-typescript/src/__generated__/sigstore_trustroot.ts
diff --git a/protos/sigstore_trustroot.proto b/protos/sigstore_trustroot.proto
@@ -26,7 +26,7 @@ option java_outer_classname = "TrustRootProto";
 // transparency log.
 // See https://www.rfc-editor.org/rfc/rfc9162.html#name-log-parameters
 // for more details.
-// The incluced parameters are the minimal set required to identify a log,
+// The included parameters are the minimal set required to identify a log,
 // and verify an inclusion promise.
 message TransparencyLogInstance {
         // The base URL at which can be used to URLs for the client.
@@ -55,7 +55,8 @@ message CertificateAuthority {
         // but it MAY be shorter. Clients MUST check timestamps against *both*
         // the `valid_for` time range *and* the entire certificate chain.
         //
-        // The TimeRange should be considered valid *inclusive* of the endpoints.
+        // The TimeRange should be considered valid *inclusive* of the
+        // endpoints.
         dev.sigstore.common.v1.TimeRange valid_for = 4;
 }
 
@@ -67,15 +68,23 @@ message CertificateAuthority {
 // to capture the complete/global set of trusted verification materials.
 // When verifying an artifact, based on the artifact and policies, a selection
 // of keys/authorities are expected to be extracted and provided to the
-// verification function. This way the set of keys/authorities kan be kept to
+// verification function. This way the set of keys/authorities can be kept to
 // a minimal set by the policy to gain better control over what signatures
 // that are allowed.
+//
+// The embedded transparency logs, CT logs, CAs and TSAs MUST include any
+// previously used instance -- otherwise signatures made in the past cannot
+// be verified.
+// The currently used instances MUST NOT have their 'end' timestamp set in
+// their 'valid_for' attribute for easy identification.
+// All the listed instances SHOULD be sorted by the 'valid_for' in ascending
+// order, that is, the oldest instance first and the current instance last.
 message TrustedRoot {
         // MUST be application/vnd.dev.sigstore.trustedroot+json;version=0.1
         string media_type = 1;
         // A set of trusted Rekor servers.
         repeated TransparencyLogInstance tlogs = 2;
-        // A set of trusted certificate authorites (e.g Fulcio), and any
+        // A set of trusted certificate authorities (e.g Fulcio), and any
         // intermediate certificates they provide.
         // If a CA is issuing multiple intermediate certificate, each
         // combination shall be represented as separate chain. I.e, a single