From f699be7ce245d916075b08a596c86d42e64745d9 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Mon, 14 Apr 2025 14:46:38 -0400 Subject: [PATCH 1/5] PGI spec: add supported algorithms section Signed-off-by: William Woodruff --- algorithm-registry.md | 9 +++++--- sigstore-public-deployment-spec.md | 37 ++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 3 deletions(-) diff --git a/algorithm-registry.md b/algorithm-registry.md index 8809e2e..8f016e6 100644 --- a/algorithm-registry.md +++ b/algorithm-registry.md @@ -6,9 +6,10 @@ file **must** be reflected in the `PublicKeyDetails` enumeration in [`sigstore_common.proto`] in [sigstore/protobuf-specs]. Sigstore clients aren't required to support all algorithms in this registry, -and **MAY** support algorithms that aren't in the registry. However, -compatibility with the Sigstore Public Good Instance requires support -for at least one of these algorithms. +and **MAY** support algorithms that aren't in the registry. + +See [Spec: Sigstore Public Deployment](./sigstore-public-deployment-spec.md) +for the algorithms supported by Sigstore's public good instance. ## Signature Algorithms @@ -22,7 +23,9 @@ for at least one of these algorithms. | | rsa-sign-pss-4096-sha256 | sign/verify | | | ECDSA | ecdsa-sha2-256-nistp256 | sign/verify | | | | ecdsa-sha2-384-nistp384 | sign/verify | | +| | ecdsa-sha2-256-nistp384 | sign/verify | Not recommended. | | | ecdsa-sha2-512-nistp521 | sign/verify | | +| | ecdsa-sha2-256-nistp521 | sign/verify | Not recommended. | | EdDSA | ed25519 | sign/verify | | | | ed25519-ph | sign/verify | Recommended only for `hashedrekord`. | | LMS | lms-sha256 | sign/verify | Stateful; signer selects the `H` parameter. Not recommended for keyless signing. | diff --git a/sigstore-public-deployment-spec.md b/sigstore-public-deployment-spec.md index f386eb6..f274592 100644 --- a/sigstore-public-deployment-spec.md +++ b/sigstore-public-deployment-spec.md @@ -191,3 +191,40 @@ The Sigstore project provides the resources necessary to deploy private Sigstore * [sigstore/scaffolding](https://github.com/sigstore/scaffolding) * [sigstore/sigstore-probers](https://github.com/sigstore/sigstore-probers) * [sigstore/policy-controller](https://github.com/sigstore/policy-controller) + +### 5.2 Supported Algorithms + +The Sigstore public good instance supports a subset of the algorithms defined +in the [Algorithm Registry](./algorithm-registry.md). Clients that interoperate +with the public good instance **MUST** support +these algorithms in their respective contexts. + +#### 5.2.1 TUF + +The public good instance uses `ecdsa-sha2-256-nistp256` for all TUF signing keys. + +#### 5.2.2 Fulcio + +The public good instance uses `ecdsa-sha2-384-nistp384` for Fulcio's +certificate chain and `ecdsa-sha2-256-nistp256` for Fulcio's certificate +transparency log. + +Clients may submit Certificate Signing Requests (CSRs) with the following +algorithms: + +* `ecdsa-sha2-256-nistp256` +* `ecdsa-sha2-384-nistp384` +* `ecdsa-sha2-512-nistp521` +* `ed25519` +* `rsa-sign-pkcs1-2048-sha256` +* `rsa-sign-pkcs1-3072-sha256` +* `rsa-sign-pkcs1-4096-sha256` + +#### 5.2.3 Rekor + +The public good instance uses `ecdsa-sha2-256-nistp256` for Rekor's +public key. + +#### 5.2.4 Timestamp Authority + +TODO. From c2980ebeb5d770b0cc9960425d8f3995a24b52e7 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Tue, 15 Apr 2025 18:14:15 -0400 Subject: [PATCH 2/5] add TSA section Signed-off-by: William Woodruff --- sigstore-public-deployment-spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sigstore-public-deployment-spec.md b/sigstore-public-deployment-spec.md index f274592..14148b8 100644 --- a/sigstore-public-deployment-spec.md +++ b/sigstore-public-deployment-spec.md @@ -227,4 +227,5 @@ public key. #### 5.2.4 Timestamp Authority -TODO. +The public good instance uses `ecdsa-sha2-384-nistp384` for the +Timestamp Authority's certificate chain. From 9be15175b5a91276a4710db040e54ccddfa2826d Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Tue, 15 Apr 2025 19:37:25 -0400 Subject: [PATCH 3/5] attempt to better document algorithm purposes Signed-off-by: William Woodruff --- algorithm-registry.md | 55 +++++++++++++++++++++--------- sigstore-public-deployment-spec.md | 16 +++++---- 2 files changed, 47 insertions(+), 24 deletions(-) diff --git a/algorithm-registry.md b/algorithm-registry.md index 8f016e6..6b40f88 100644 --- a/algorithm-registry.md +++ b/algorithm-registry.md @@ -11,25 +11,46 @@ and **MAY** support algorithms that aren't in the registry. See [Spec: Sigstore Public Deployment](./sigstore-public-deployment-spec.md) for the algorithms supported by Sigstore's public good instance. +## Algorithm Purposes + +The following legend describes the purpose of each algorithm below. + +| Symbol | Description | Example | +|--------|-------------| ------- | +| 🔑 | End-user signing (ephemeral or long-lived keys) | A user signing with [`cosign`] | +| 🔗 | TUF metadata signing | [sigstore/root-signing] | +| 🔏 | Certificate authority materials (CA chains) | [Fulcio] | +| 🪵 | Certificate transparency log materials (log keys and inclusion proofs) | Fulcio's [CT log] | +| ⏰ | Timestamp authority materials (TSA chains and signed timestamps) | [sigstore/timestamp-authority] | +| 📝 | Signature transparency log materials (log keys and inclusion proofs) | [Rekor] | +| 👀 | Witness keys and signatures | Third-party log witnesses | + +[`cosign`]: https://github.com/sigstore/cosign +[sigstore/root-signing]: https://github.com/sigstore/root-signing/ +[Fulcio]: https://github.com/sigstore/fulcio +[CT log]: https://github.com/sigstore/fulcio#certificate-transparency +[Rekor]: https://github.com/sigstore/rekor +[sigstore/timestamp-authority]: https://github.com/sigstore/timestamp-authority + ## Signature Algorithms -| Algorithm | Name | Usage | Notes | -|-----------|----------------------------|-------------| -------------------------------------------------------------------------------- | -| RSA | rsa-sign-pkcs1-2048-sha256 | verify only | Not recommended. | -| | rsa-sign-pkcs1-3072-sha256 | sign/verify | | -| | rsa-sign-pkcs1-4096-sha256 | sign/verify | | -| | rsa-sign-pss-2048-sha256 | verify only | Not recommended. | -| | rsa-sign-pss-3072-sha256 | sign/verify | | -| | rsa-sign-pss-4096-sha256 | sign/verify | | -| ECDSA | ecdsa-sha2-256-nistp256 | sign/verify | | -| | ecdsa-sha2-384-nistp384 | sign/verify | | -| | ecdsa-sha2-256-nistp384 | sign/verify | Not recommended. | -| | ecdsa-sha2-512-nistp521 | sign/verify | | -| | ecdsa-sha2-256-nistp521 | sign/verify | Not recommended. | -| EdDSA | ed25519 | sign/verify | | -| | ed25519-ph | sign/verify | Recommended only for `hashedrekord`. | -| LMS | lms-sha256 | sign/verify | Stateful; signer selects the `H` parameter. Not recommended for keyless signing. | -| LM-OTS | lmots-sha256 | sign/verify | One-time use only; signer selects `n` and `w`. | +| Algorithm | Name | Usage | Purpose | Notes | +|-----------|----------------------------|-------------| ------- |--------------------------------------------------------------------------------- | +| RSA | rsa-sign-pkcs1-2048-sha256 | verify only | 🔑 🪵 | Not recommended; not used for CT log materials outside of staging. | +| | rsa-sign-pkcs1-3072-sha256 | sign/verify | 🔑 | | +| | rsa-sign-pkcs1-4096-sha256 | sign/verify | 🔑 | | +| | rsa-sign-pss-2048-sha256 | verify only | 🔑 | Not recommended. | +| | rsa-sign-pss-3072-sha256 | sign/verify | 🔑 | | +| | rsa-sign-pss-4096-sha256 | sign/verify | 🔑 | | +| ECDSA | ecdsa-sha2-256-nistp256 | sign/verify | 🔑 🔗 🪵 📝 | | +| | ecdsa-sha2-384-nistp384 | sign/verify | 🔑 🔏 ⏰ | | +| | ecdsa-sha2-256-nistp384 | verify only | 🔑 | Not recommended due to poor compatibility. | +| | ecdsa-sha2-512-nistp521 | sign/verify | 🔑 | | +| | ecdsa-sha2-256-nistp521 | verify only | 🔑 | Not recommended due to poor compatibility. | +| EdDSA | ed25519 | sign/verify | 🔑 👀 | | +| | ed25519-ph | sign/verify | 🔑 | Recommended only for `hashedrekord`. | +| LMS | lms-sha256 | sign/verify | 🔑 | Stateful; signer selects the `H` parameter. Not recommended for keyless signing. | +| LM-OTS | lmots-sha256 | sign/verify | 🔑 | One-time use only; signer selects `n` and `w`. | ### Parameter configuration for LMS and LM-OTS diff --git a/sigstore-public-deployment-spec.md b/sigstore-public-deployment-spec.md index 14148b8..8413bb5 100644 --- a/sigstore-public-deployment-spec.md +++ b/sigstore-public-deployment-spec.md @@ -212,13 +212,15 @@ transparency log. Clients may submit Certificate Signing Requests (CSRs) with the following algorithms: -* `ecdsa-sha2-256-nistp256` -* `ecdsa-sha2-384-nistp384` -* `ecdsa-sha2-512-nistp521` -* `ed25519` -* `rsa-sign-pkcs1-2048-sha256` -* `rsa-sign-pkcs1-3072-sha256` -* `rsa-sign-pkcs1-4096-sha256` +| Algorithm | Required? | Recommended? | +|------------------------------|-----------|---------------| +| `ecdsa-sha2-256-nistp256` | Yes | Yes | +| `ecdsa-sha2-384-nistp384` | No | Yes | +| `ecdsa-sha2-512-nistp521` | No | Yes | +| `rsa-sign-pkcs1-2048-sha256` | No | No | +| `rsa-sign-pkcs1-3072-sha256` | No | No | +| `rsa-sign-pkcs1-4096-sha256` | No | No | +| `ed25519` | No | Yes | #### 5.2.3 Rekor From aa547284e03a238564a82b6a2375197f734e4327 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Tue, 15 Apr 2025 19:40:33 -0400 Subject: [PATCH 4/5] update algorithms Signed-off-by: William Woodruff --- algorithm-registry.md | 2 +- sigstore-public-deployment-spec.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/algorithm-registry.md b/algorithm-registry.md index 6b40f88..155c622 100644 --- a/algorithm-registry.md +++ b/algorithm-registry.md @@ -47,7 +47,7 @@ The following legend describes the purpose of each algorithm below. | | ecdsa-sha2-256-nistp384 | verify only | 🔑 | Not recommended due to poor compatibility. | | | ecdsa-sha2-512-nistp521 | sign/verify | 🔑 | | | | ecdsa-sha2-256-nistp521 | verify only | 🔑 | Not recommended due to poor compatibility. | -| EdDSA | ed25519 | sign/verify | 🔑 👀 | | +| EdDSA | ed25519 | sign/verify | 🔑 📝 👀 | | | | ed25519-ph | sign/verify | 🔑 | Recommended only for `hashedrekord`. | | LMS | lms-sha256 | sign/verify | 🔑 | Stateful; signer selects the `H` parameter. Not recommended for keyless signing. | | LM-OTS | lmots-sha256 | sign/verify | 🔑 | One-time use only; signer selects `n` and `w`. | diff --git a/sigstore-public-deployment-spec.md b/sigstore-public-deployment-spec.md index 8413bb5..014a8f0 100644 --- a/sigstore-public-deployment-spec.md +++ b/sigstore-public-deployment-spec.md @@ -224,8 +224,12 @@ algorithms: #### 5.2.3 Rekor -The public good instance uses `ecdsa-sha2-256-nistp256` for Rekor's -public key. +The public good instance may use any of the following for Rekor's +public key and signatures: + +* `ecdsa-sha2-256-nistp256` +* `ecdsa-sha2-384-nistp384` +* `ed25519` (beginning with Rekor v2) #### 5.2.4 Timestamp Authority From e4ffb6b0ff368ef69ce8cd6064209f62287dbf97 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Tue, 15 Apr 2025 19:42:09 -0400 Subject: [PATCH 5/5] clarify Rekor versions Signed-off-by: William Woodruff --- sigstore-public-deployment-spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sigstore-public-deployment-spec.md b/sigstore-public-deployment-spec.md index 014a8f0..857f90f 100644 --- a/sigstore-public-deployment-spec.md +++ b/sigstore-public-deployment-spec.md @@ -227,8 +227,8 @@ algorithms: The public good instance may use any of the following for Rekor's public key and signatures: -* `ecdsa-sha2-256-nistp256` -* `ecdsa-sha2-384-nistp384` +* `ecdsa-sha2-256-nistp256` (Rekor v1) +* `ecdsa-sha2-384-nistp384` (Rekor v1) * `ed25519` (beginning with Rekor v2) #### 5.2.4 Timestamp Authority