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]>
sigstore · Apr 4, 2024 · 43de29d · 43de29d
1 parent 1d62444
commit 43de29d
Show file tree

Hide file tree

Showing 28 changed files with 326 additions and 167 deletions.
diff --git a/gen/jsonschema/schemas/Bundle.schema.json b/gen/jsonschema/schemas/Bundle.schema.json
@@ -136,7 +136,7 @@
             "properties": {
                 "keyId": {
                     "type": "string",
-                    "description": "The unique id of the log, represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2",
+                    "description": "The unique identity of the log, represented by its public key.",
                     "format": "binary",
                     "binaryEncoding": "base64"
                 }
@@ -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
@@ -41,7 +41,7 @@
             "properties": {
                 "keyId": {
                     "type": "string",
-                    "description": "The unique id of the log, represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2",
+                    "description": "The unique identity of the log, represented by its public key.",
                     "format": "binary",
                     "binaryEncoding": "base64"
                 }
@@ -243,7 +243,12 @@
                 "logId": {
                     "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
                     "additionalProperties": false,
-                    "description": "The unique identifier for this transparency log."
+                    "description": "The unique identifier for this transparency log. Represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2"
+                },
+                "checkpointKeyId": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
+                    "additionalProperties": false,
+                    "description": "The checkpoint key identifier for the log used in a 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. Follows 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, 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. SHOULD be set for logs generating Ed25519 signatures. SHOULD be 4 bytes long, as a truncated hash."
                 }
             },
             "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
@@ -182,7 +182,7 @@
             "properties": {
                 "keyId": {
                     "type": "string",
-                    "description": "The unique id of the log, represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2",
+                    "description": "The unique identity of the log, represented by its public key.",
                     "format": "binary",
                     "binaryEncoding": "base64"
                 }
@@ -422,7 +422,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": {
@@ -585,7 +585,12 @@
                 "logId": {
                     "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
                     "additionalProperties": false,
-                    "description": "The unique identifier for this transparency log."
+                    "description": "The unique identifier for this transparency log. Represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2"
+                },
+                "checkpointKeyId": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
+                    "additionalProperties": false,
+                    "description": "The checkpoint key identifier for the log used in a 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. Follows 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, 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. SHOULD be set for logs generating Ed25519 signatures. SHOULD be 4 bytes long, as a truncated hash."
                 }
             },
             "additionalProperties": false,

diff --git a/gen/jsonschema/schemas/LogId.schema.json b/gen/jsonschema/schemas/LogId.schema.json
@@ -6,7 +6,7 @@
             "properties": {
                 "keyId": {
                     "type": "string",
-                    "description": "The unique id of the log, represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2",
+                    "description": "The unique identity of the log, represented by its public key.",
                     "format": "binary",
                     "binaryEncoding": "base64"
                 }

diff --git a/gen/jsonschema/schemas/TransparencyLogEntry.schema.json b/gen/jsonschema/schemas/TransparencyLogEntry.schema.json
@@ -48,7 +48,7 @@
             "properties": {
                 "keyId": {
                     "type": "string",
-                    "description": "The unique id of the log, represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2",
+                    "description": "The unique identity of the log, represented by its public key.",
                     "format": "binary",
                     "binaryEncoding": "base64"
                 }
@@ -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
@@ -29,7 +29,12 @@
                 "logId": {
                     "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
                     "additionalProperties": false,
-                    "description": "The unique identifier for this transparency log."
+                    "description": "The unique identifier for this transparency log. Represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2"
+                },
+                "checkpointKeyId": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
+                    "additionalProperties": false,
+                    "description": "The checkpoint key identifier for the log used in a 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. Follows 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, 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. SHOULD be set for logs generating Ed25519 signatures. SHOULD be 4 bytes long, as a truncated hash."
                 }
             },
             "additionalProperties": false,
@@ -41,7 +46,7 @@
             "properties": {
                 "keyId": {
                     "type": "string",
-                    "description": "The unique id of the log, represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2",
+                    "description": "The unique identity of the log, represented by its public key.",
                     "format": "binary",
                     "binaryEncoding": "base64"
                 }

diff --git a/gen/jsonschema/schemas/TrustedRoot.schema.json b/gen/jsonschema/schemas/TrustedRoot.schema.json
@@ -63,7 +63,7 @@
             "properties": {
                 "keyId": {
                     "type": "string",
-                    "description": "The unique id of the log, represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2",
+                    "description": "The unique identity of the log, represented by its public key.",
                     "format": "binary",
                     "binaryEncoding": "base64"
                 }
@@ -235,7 +235,12 @@
                 "logId": {
                     "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
                     "additionalProperties": false,
-                    "description": "The unique identifier for this transparency log."
+                    "description": "The unique identifier for this transparency log. Represented as the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. See https://www.rfc-editor.org/rfc/rfc6962#section-3.2"
+                },
+                "checkpointKeyId": {
+                    "$ref": "#/definitions/dev.sigstore.common.v1.LogId",
+                    "additionalProperties": false,
+                    "description": "The checkpoint key identifier for the log used in a 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. Follows 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, 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. SHOULD be set for logs generating Ed25519 signatures. SHOULD be 4 bytes long, as a truncated hash."
                 }
             },
             "additionalProperties": false,