Add algorithm registry markdown and KnownSignatureAlgorithm enumera…

…tion (#194) * Add `SupportedAlgorithm` enumeration Signed-off-by: Alex Cameron <[email protected]> * Add registry markdown doc Signed-off-by: Alex Cameron <[email protected]> * Regenerate code Signed-off-by: Alex Cameron <[email protected]> * Switch to P521 with SHA-512 Signed-off-by: Alex Cameron <[email protected]> * Make it clear that Sigstore services aren't required to adhere to this registry Signed-off-by: Alex Cameron <[email protected]> * Rename to `KnownSignatureAlgorithm` Signed-off-by: Alex Cameron <[email protected]> * Correct `KnownSignatureAlgorithm` comment Signed-off-by: Alex Cameron <[email protected]> * Note that `ed25519-ph` is used for hashedrekord Signed-off-by: Alex Cameron <[email protected]> * Fix algorithm registry to list SHA-512 with P-521 Signed-off-by: Alex Cameron <[email protected]> * Regenerate code Signed-off-by: Alex Cameron <[email protected]> * Add hash algorithms to registry also Signed-off-by: Alex Cameron <[email protected]> * Add RSA signature algorithms to registry Signed-off-by: Alex Cameron <[email protected]> * gen, protos: more HashAlgorithm variants Signed-off-by: William Woodruff <[email protected]> * protos: indentation Signed-off-by: William Woodruff <[email protected]> * algorithm-registry: clarify the purpose of the Hash Algorithms table Signed-off-by: William Woodruff <[email protected]> * algorithm-registry: add sha2-512 Signed-off-by: William Woodruff <[email protected]> * algorithm-registry: omit sha2-256/192 Signed-off-by: William Woodruff <[email protected]> * switcheroo Signed-off-by: William Woodruff <[email protected]> --------- Signed-off-by: Alex Cameron <[email protected]> Signed-off-by: William Woodruff <[email protected]> Co-authored-by: William Woodruff <[email protected]>
sigstore · Jan 17, 2024 · 017af89 · 017af89
1 parent 2c4d82d
commit 017af89
Show file tree

Hide file tree

Showing 18 changed files with 448 additions and 72 deletions.
diff --git a/docs/algorithm-registry.md b/docs/algorithm-registry.md
@@ -0,0 +1,41 @@
+# Algorithm Registry
+
+This file is designed to act as a source of truth regarding what signing
+algorithms are recommended across the Sigstore ecosystem. Any changes to this
+file **must** be reflected in the `KnownSignatureAlgorithm` enumeration in
+[sigstore_common.proto](../protos/sigstore_common.proto).
+
+Note that Sigstore clients and services aren't required support all algorithms
+in this registry and may support algorithms that aren't in the registry. The
+algorithm registry is more of a guideline than a rule and is meant to serve as
+a secure set of defaults that the community can follow.
+
+Refer to the [Sigstore: Configurable Crypto Algorithms](https://docs.google.com/document/d/18vTKFvTQdRt3OGz6Qd1xf04o-hugRYSup-1EAOWn7MQ/)
+specification for the design rationale for this registry.
+
+## Signature Algorithms
+
+| Algorithm | Name                       | Usage                                             |
+|-----------|----------------------------|---------------------------------------------------|
+| RSA       | rsa-sign-pkcs1-2048-sha256 | verify only                                       |
+|           | rsa-sign-pkcs1-3072-sha256 | sign/verify                                       |
+|           | rsa-sign-pkcs1-4096-sha256 | sign/verify                                       |
+| ECDSA     | ecdsa-sha2-256-nistp256    | sign/verify                                       |
+|           | ecdsa-sha2-384-nistp384    | sign/verify                                       |
+|           | ecdsa-sha2-512-nistp521    | sign/verify                                       |
+| EdDSA     | ed25519                    | sign/verify                                       |
+|           | ed25519-ph                 | sign/verify (recommended only for `hashedrekord`) |
+
+## Hash Algorithms
+
+Generally speaking, these hash algorithms are implied by the above signing suites.
+However, clients *may* need to list or configure them explicitly, e.g. for custom
+signing schemes or as part of a `hashedrekord` entry.
+
+| Algorithm | Name         |
+|-----------|--------------|
+| SHA2      | sha2-256     |
+|           | sha2-384     |
+|           | sha2-512     |
+| SHA3      | sha3-256     |
+|           | sha3-384     |
diff --git a/gen/jsonschema/schemas/Bundle.schema.json b/gen/jsonschema/schemas/Bundle.schema.json
@@ -110,7 +110,11 @@
                 "algorithm": {
                     "enum": [
                         "HASH_ALGORITHM_UNSPECIFIED",
-                        "SHA2_256"
+                        "SHA2_256",
+                        "SHA2_384",
+                        "SHA2_512",
+                        "SHA3_256",
+                        "SHA3_384"
                     ],
                     "type": "string",
                     "title": "This package defines commonly used message types within the Sigstore\n community.",

diff --git a/gen/jsonschema/schemas/HashOutput.schema.json b/gen/jsonschema/schemas/HashOutput.schema.json
@@ -7,7 +7,11 @@
                 "algorithm": {
                     "enum": [
                         "HASH_ALGORITHM_UNSPECIFIED",
-                        "SHA2_256"
+                        "SHA2_256",
+                        "SHA2_384",
+                        "SHA2_512",
+                        "SHA3_256",
+                        "SHA3_384"
                     ],
                     "type": "string",
                     "title": "This package defines commonly used message types within the Sigstore\n community.",

diff --git a/gen/jsonschema/schemas/Input.schema.json b/gen/jsonschema/schemas/Input.schema.json
@@ -156,7 +156,11 @@
                 "algorithm": {
                     "enum": [
                         "HASH_ALGORITHM_UNSPECIFIED",
-                        "SHA2_256"
+                        "SHA2_256",
+                        "SHA2_384",
+                        "SHA2_512",
+                        "SHA3_256",
+                        "SHA3_384"
                     ],
                     "type": "string",
                     "title": "This package defines commonly used message types within the Sigstore\n community.",
@@ -552,7 +556,11 @@
                 "hashAlgorithm": {
                     "enum": [
                         "HASH_ALGORITHM_UNSPECIFIED",
-                        "SHA2_256"
+                        "SHA2_256",
+                        "SHA2_384",
+                        "SHA2_512",
+                        "SHA3_256",
+                        "SHA3_384"
                     ],
                     "type": "string",
                     "title": "This package defines commonly used message types within the Sigstore\n community.",

diff --git a/gen/jsonschema/schemas/MessageSignature.schema.json b/gen/jsonschema/schemas/MessageSignature.schema.json
@@ -26,7 +26,11 @@
                 "algorithm": {
                     "enum": [
                         "HASH_ALGORITHM_UNSPECIFIED",
-                        "SHA2_256"
+                        "SHA2_256",
+                        "SHA2_384",
+                        "SHA2_512",
+                        "SHA3_256",
+                        "SHA3_384"
                     ],
                     "type": "string",
                     "title": "This package defines commonly used message types within the Sigstore\n community.",

diff --git a/gen/jsonschema/schemas/TransparencyLogInstance.schema.json b/gen/jsonschema/schemas/TransparencyLogInstance.schema.json
@@ -11,7 +11,11 @@
                 "hashAlgorithm": {
                     "enum": [
                         "HASH_ALGORITHM_UNSPECIFIED",
-                        "SHA2_256"
+                        "SHA2_256",
+                        "SHA2_384",
+                        "SHA2_512",
+                        "SHA3_256",
+                        "SHA3_384"
                     ],
                     "type": "string",
                     "title": "This package defines commonly used message types within the Sigstore\n community.",

diff --git a/gen/jsonschema/schemas/TrustedRoot.schema.json b/gen/jsonschema/schemas/TrustedRoot.schema.json
@@ -206,7 +206,11 @@
                 "hashAlgorithm": {
                     "enum": [
                         "HASH_ALGORITHM_UNSPECIFIED",
-                        "SHA2_256"
+                        "SHA2_256",
+                        "SHA2_384",
+                        "SHA2_512",
+                        "SHA3_256",
+                        "SHA3_384"
                     ],
                     "type": "string",
                     "title": "This package defines commonly used message types within the Sigstore\n community.",