Add checkpoint key ID to trust root

This adds a string to represent the checkpoint key ID for a log, which will differ for ed25519 logs. To simplify client implementation, we will provide this string so that clients don't have to compute the checkpoint key ID themselves using the public key. If it's not set, then a client should assume the log ID is equal to the checkpoint key ID, which is true for ecdsa and rsa logs. Ref: sigstore/rekor#2062 Signed-off-by: Hayden Blauzvern <[email protected]>
haydentherapper · Apr 4, 2024 · 9a895c0 · 9a895c0
1 parent 1d62444
commit 9a895c0
Show file tree

Hide file tree

Showing 28 changed files with 651 additions and 314 deletions.
diff --git a/gen/jsonschema/schemas/Bundle.schema.json b/gen/jsonschema/schemas/Bundle.schema.json
@@ -229,7 +229,7 @@
             "additionalProperties": false,
             "type": "object",
             "title": "Checkpoint",
-            "description": "The checkpoint MUST contain a signature of the tree head (root hash), size of the tree and the transparency log's unique identifier (log ID). It MAY also be followed by any optional data. The result is a string,  the format is described here https://github.com/transparency-dev/formats/blob/main/log/README.md The details are here https://github.com/sigstore/rekor/blob/a6e58f72b6b18cc06cefe61808efd562b9726330/pkg/util/signed_note.go#L114 The signature has the same format as InclusionPromise.signed_entry_timestamp. See below for more details."
+            "description": "The checkpoint MUST contain an origin string as a unique log identifier, the tree size, and the root hash. It MAY also be followed by optional data, and clients MUST NOT assume optional data. The checkpoint MUST also contain a signature over the root hash (tree head). The checkpoint MAY contain additional signatures, but the first SHOULD be the signature from the log. Checkpoint contents are concatenated with newlines into a single string. The checkpoint format is described in https://github.com/transparency-dev/formats/blob/main/log/README.md and https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md. An example implementation can be found in https://github.com/sigstore/rekor/blob/main/pkg/util/signed_note.go"
         },
         "dev.sigstore.rekor.v1.InclusionPromise": {
             "properties": {

diff --git a/gen/jsonschema/schemas/Checkpoint.schema.json b/gen/jsonschema/schemas/Checkpoint.schema.json
@@ -11,7 +11,7 @@
             "additionalProperties": false,
             "type": "object",
             "title": "Checkpoint",
-            "description": "The checkpoint MUST contain a signature of the tree head (root hash), size of the tree and the transparency log's unique identifier (log ID). It MAY also be followed by any optional data. The result is a string,  the format is described here https://github.com/transparency-dev/formats/blob/main/log/README.md The details are here https://github.com/sigstore/rekor/blob/a6e58f72b6b18cc06cefe61808efd562b9726330/pkg/util/signed_note.go#L114 The signature has the same format as InclusionPromise.signed_entry_timestamp. See below for more details."
+            "description": "The checkpoint MUST contain an origin string as a unique log identifier, the tree size, and the root hash. It MAY also be followed by optional data, and clients MUST NOT assume optional data. The checkpoint MUST also contain a signature over the root hash (tree head). The checkpoint MAY contain additional signatures, but the first SHOULD be the signature from the log. Checkpoint contents are concatenated with newlines into a single string. The checkpoint format is described in https://github.com/transparency-dev/formats/blob/main/log/README.md and https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md. An example implementation can be found in https://github.com/sigstore/rekor/blob/main/pkg/util/signed_note.go"
         }
     }
 }
diff --git a/gen/jsonschema/schemas/CheckpointKeyId.schema.json b/gen/jsonschema/schemas/CheckpointKeyId.schema.json
@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "$ref": "#/definitions/CheckpointKeyId",
+    "definitions": {
+        "CheckpointKeyId": {
+            "properties": {
+                "keyId": {
+                    "type": "string",
+                    "description": "The key ID in a checkpoint, as a prefix to the signature. SHOULD be 4 bytes long, as a truncated hash.",
+                    "format": "binary",
+                    "binaryEncoding": "base64"
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Checkpoint Key Id",
+            "description": "The checkpoint key ID, following the specification described here for ECDSA and Ed25519 signatures: https://github.com/C2SP/C2SP/blob/main/signed-note.md#signatures For RSA signatures, the key ID will match the ECDSA format of the hashed DER-encoded SPKI public key. Publicly witnessed logs MUST NOT use RSA-signed checkpoints, since witnesses do not support RSA signatures. This is provided for convenience. Clients can also calculate the checkpoint key ID given the log's public key."
+        }
+    }
+}
diff --git a/gen/jsonschema/schemas/ClientTrustConfig.schema.json b/gen/jsonschema/schemas/ClientTrustConfig.schema.json
@@ -24,6 +24,20 @@
             "title": "Client Trust Config",
             "description": "ClientTrustConfig describes the complete state needed by a client to perform both signing and verification operations against a particular instance of Sigstore."
         },
+        "dev.sigstore.common.v1.CheckpointKeyId": {
+            "properties": {
+                "keyId": {
+                    "type": "string",
+                    "description": "The key ID in a checkpoint, as a prefix to the signature. SHOULD be 4 bytes long, as a truncated hash.",
+                    "format": "binary",
+                    "binaryEncoding": "base64"
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Checkpoint Key Id",
+            "description": "The checkpoint key ID, following the specification described here for ECDSA and Ed25519 signatures: https://github.com/C2SP/C2SP/blob/main/signed-note.md#signatures For RSA signatures, the key ID will match the ECDSA format of the hashed DER-encoded SPKI public key. Publicly witnessed logs MUST NOT use RSA-signed checkpoints, since witnesses do not support RSA signatures. This is provided for convenience. Clients can also calculate the checkpoint key ID given the log's public key."
+        },
         "dev.sigstore.common.v1.DistinguishedName": {
             "properties": {
                 "organization": {
@@ -244,6 +258,11 @@
                     "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
                     "additionalProperties": false,
                     "description": "The unique identifier for this transparency log."
+                },
+                "checkpointKeyId": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.CheckpointKeyId",
+                    "additionalProperties": false,
+                    "description": "The key identifier for the log used in the checkpoint. Optional, not provided for logs that do not generate checkpoints. For logs that do generate checkpoints, if not set, assume log_id equals checkpoint_key_id. MUST be set for logs generating Ed25519 signatures."
                 }
             },
             "additionalProperties": false,

diff --git a/gen/jsonschema/schemas/InclusionProof.schema.json b/gen/jsonschema/schemas/InclusionProof.schema.json
@@ -47,7 +47,7 @@
             "additionalProperties": false,
             "type": "object",
             "title": "Checkpoint",
-            "description": "The checkpoint MUST contain a signature of the tree head (root hash), size of the tree and the transparency log's unique identifier (log ID). It MAY also be followed by any optional data. The result is a string,  the format is described here https://github.com/transparency-dev/formats/blob/main/log/README.md The details are here https://github.com/sigstore/rekor/blob/a6e58f72b6b18cc06cefe61808efd562b9726330/pkg/util/signed_note.go#L114 The signature has the same format as InclusionPromise.signed_entry_timestamp. See below for more details."
+            "description": "The checkpoint MUST contain an origin string as a unique log identifier, the tree size, and the root hash. It MAY also be followed by optional data, and clients MUST NOT assume optional data. The checkpoint MUST also contain a signature over the root hash (tree head). The checkpoint MAY contain additional signatures, but the first SHOULD be the signature from the log. Checkpoint contents are concatenated with newlines into a single string. The checkpoint format is described in https://github.com/transparency-dev/formats/blob/main/log/README.md and https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md. An example implementation can be found in https://github.com/sigstore/rekor/blob/main/pkg/util/signed_note.go"
         }
     }
 }
diff --git a/gen/jsonschema/schemas/Input.schema.json b/gen/jsonschema/schemas/Input.schema.json
@@ -138,6 +138,20 @@
             "title": "Verification Material",
             "description": "VerificationMaterial captures details on the materials used to verify signatures. This message may be embedded in a DSSE envelope as a signature extension. Specifically, the `ext` field of the extension will expect this message when the signature extension is for Sigstore. This is identified by the `kind` field in the extension, which must be set to application/vnd.dev.sigstore.verificationmaterial;version=0.1 for Sigstore. When used as a DSSE extension, if the `public_key` field is used to indicate the key identifier, it MUST match the `keyid` field of the signature the extension is attached to."
         },
+        "dev.sigstore.common.v1.CheckpointKeyId": {
+            "properties": {
+                "keyId": {
+                    "type": "string",
+                    "description": "The key ID in a checkpoint, as a prefix to the signature. SHOULD be 4 bytes long, as a truncated hash.",
+                    "format": "binary",
+                    "binaryEncoding": "base64"
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Checkpoint Key Id",
+            "description": "The checkpoint key ID, following the specification described here for ECDSA and Ed25519 signatures: https://github.com/C2SP/C2SP/blob/main/signed-note.md#signatures For RSA signatures, the key ID will match the ECDSA format of the hashed DER-encoded SPKI public key. Publicly witnessed logs MUST NOT use RSA-signed checkpoints, since witnesses do not support RSA signatures. This is provided for convenience. Clients can also calculate the checkpoint key ID given the log's public key."
+        },
         "dev.sigstore.common.v1.DistinguishedName": {
             "properties": {
                 "organization": {
@@ -422,7 +436,7 @@
             "additionalProperties": false,
             "type": "object",
             "title": "Checkpoint",
-            "description": "The checkpoint MUST contain a signature of the tree head (root hash), size of the tree and the transparency log's unique identifier (log ID). It MAY also be followed by any optional data. The result is a string,  the format is described here https://github.com/transparency-dev/formats/blob/main/log/README.md The details are here https://github.com/sigstore/rekor/blob/a6e58f72b6b18cc06cefe61808efd562b9726330/pkg/util/signed_note.go#L114 The signature has the same format as InclusionPromise.signed_entry_timestamp. See below for more details."
+            "description": "The checkpoint MUST contain an origin string as a unique log identifier, the tree size, and the root hash. It MAY also be followed by optional data, and clients MUST NOT assume optional data. The checkpoint MUST also contain a signature over the root hash (tree head). The checkpoint MAY contain additional signatures, but the first SHOULD be the signature from the log. Checkpoint contents are concatenated with newlines into a single string. The checkpoint format is described in https://github.com/transparency-dev/formats/blob/main/log/README.md and https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md. An example implementation can be found in https://github.com/sigstore/rekor/blob/main/pkg/util/signed_note.go"
         },
         "dev.sigstore.rekor.v1.InclusionPromise": {
             "properties": {
@@ -586,6 +600,11 @@
                     "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
                     "additionalProperties": false,
                     "description": "The unique identifier for this transparency log."
+                },
+                "checkpointKeyId": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.CheckpointKeyId",
+                    "additionalProperties": false,
+                    "description": "The key identifier for the log used in the checkpoint. Optional, not provided for logs that do not generate checkpoints. For logs that do generate checkpoints, if not set, assume log_id equals checkpoint_key_id. MUST be set for logs generating Ed25519 signatures."
                 }
             },
             "additionalProperties": false,

diff --git a/gen/jsonschema/schemas/TransparencyLogEntry.schema.json b/gen/jsonschema/schemas/TransparencyLogEntry.schema.json
@@ -67,7 +67,7 @@
             "additionalProperties": false,
             "type": "object",
             "title": "Checkpoint",
-            "description": "The checkpoint MUST contain a signature of the tree head (root hash), size of the tree and the transparency log's unique identifier (log ID). It MAY also be followed by any optional data. The result is a string,  the format is described here https://github.com/transparency-dev/formats/blob/main/log/README.md The details are here https://github.com/sigstore/rekor/blob/a6e58f72b6b18cc06cefe61808efd562b9726330/pkg/util/signed_note.go#L114 The signature has the same format as InclusionPromise.signed_entry_timestamp. See below for more details."
+            "description": "The checkpoint MUST contain an origin string as a unique log identifier, the tree size, and the root hash. It MAY also be followed by optional data, and clients MUST NOT assume optional data. The checkpoint MUST also contain a signature over the root hash (tree head). The checkpoint MAY contain additional signatures, but the first SHOULD be the signature from the log. Checkpoint contents are concatenated with newlines into a single string. The checkpoint format is described in https://github.com/transparency-dev/formats/blob/main/log/README.md and https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md. An example implementation can be found in https://github.com/sigstore/rekor/blob/main/pkg/util/signed_note.go"
         },
         "dev.sigstore.rekor.v1.InclusionPromise": {
             "properties": {

diff --git a/gen/jsonschema/schemas/TransparencyLogInstance.schema.json b/gen/jsonschema/schemas/TransparencyLogInstance.schema.json
@@ -30,13 +30,32 @@
                     "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
                     "additionalProperties": false,
                     "description": "The unique identifier for this transparency log."
+                },
+                "checkpointKeyId": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.CheckpointKeyId",
+                    "additionalProperties": false,
+                    "description": "The key identifier for the log used in the checkpoint. Optional, not provided for logs that do not generate checkpoints. For logs that do generate checkpoints, if not set, assume log_id equals checkpoint_key_id. MUST be set for logs generating Ed25519 signatures."
                 }
             },
             "additionalProperties": false,
             "type": "object",
             "title": "Transparency Log Instance",
             "description": "TransparencyLogInstance describes the immutable parameters from a transparency log. 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 proof/promise."
         },
+        "dev.sigstore.common.v1.CheckpointKeyId": {
+            "properties": {
+                "keyId": {
+                    "type": "string",
+                    "description": "The key ID in a checkpoint, as a prefix to the signature. SHOULD be 4 bytes long, as a truncated hash.",
+                    "format": "binary",
+                    "binaryEncoding": "base64"
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Checkpoint Key Id",
+            "description": "The checkpoint key ID, following the specification described here for ECDSA and Ed25519 signatures: https://github.com/C2SP/C2SP/blob/main/signed-note.md#signatures For RSA signatures, the key ID will match the ECDSA format of the hashed DER-encoded SPKI public key. Publicly witnessed logs MUST NOT use RSA-signed checkpoints, since witnesses do not support RSA signatures. This is provided for convenience. Clients can also calculate the checkpoint key ID given the log's public key."
+        },
         "dev.sigstore.common.v1.LogId": {
             "properties": {
                 "keyId": {

diff --git a/gen/jsonschema/schemas/TrustedRoot.schema.json b/gen/jsonschema/schemas/TrustedRoot.schema.json
@@ -46,6 +46,20 @@
             "title": "Trusted Root",
             "description": "TrustedRoot describes the client's complete set of trusted entities. How the TrustedRoot is populated is not specified, but can be a combination of many sources such as TUF repositories, files on disk etc. The TrustedRoot is not meant to be used for any artifact verification, only 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 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. All the listed instances SHOULD be sorted by the 'valid_for' in ascending order, that is, the oldest instance first. Only the last instance is allowed to have their 'end' timestamp unset. All previous instances MUST have a closed interval of validity. The last instance MAY have a closed interval. Clients MUST accept instances that overlaps in time, if not clients may experience problems during rotations of verification materials. To be able to manage planned rotations of either transparency logs or certificate authorities, clienst MUST accept lists of instances where the last instance have a 'valid_for' that belongs to the future. This should not be a problem as clients SHOULD first seek the trust root for a suitable instance before creating a per artifact trust root (that is, a sub-set of the complete trust root) that is used for verification."
         },
+        "dev.sigstore.common.v1.CheckpointKeyId": {
+            "properties": {
+                "keyId": {
+                    "type": "string",
+                    "description": "The key ID in a checkpoint, as a prefix to the signature. SHOULD be 4 bytes long, as a truncated hash.",
+                    "format": "binary",
+                    "binaryEncoding": "base64"
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "Checkpoint Key Id",
+            "description": "The checkpoint key ID, following the specification described here for ECDSA and Ed25519 signatures: https://github.com/C2SP/C2SP/blob/main/signed-note.md#signatures For RSA signatures, the key ID will match the ECDSA format of the hashed DER-encoded SPKI public key. Publicly witnessed logs MUST NOT use RSA-signed checkpoints, since witnesses do not support RSA signatures. This is provided for convenience. Clients can also calculate the checkpoint key ID given the log's public key."
+        },
         "dev.sigstore.common.v1.DistinguishedName": {
             "properties": {
                 "organization": {
@@ -236,6 +250,11 @@
                     "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
                     "additionalProperties": false,
                     "description": "The unique identifier for this transparency log."
+                },
+                "checkpointKeyId": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.CheckpointKeyId",
+                    "additionalProperties": false,
+                    "description": "The key identifier for the log used in the checkpoint. Optional, not provided for logs that do not generate checkpoints. For logs that do generate checkpoints, if not set, assume log_id equals checkpoint_key_id. MUST be set for logs generating Ed25519 signatures."
                 }
             },
             "additionalProperties": false,