Skip to content

Commit b38b8f7

Browse files
jiparisjiparis
authored
chore(docs): improve signing documentation (#1069)
Signed-off-by: Jose I. Paris <[email protected]>
1 parent 073f63e commit b38b8f7

File tree

1 file changed

+24
-14
lines changed

1 file changed

+24
-14
lines changed

‎docs/docs/reference/signing.md‎

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,27 +15,37 @@ Some of these signing methods are inherited from the amazing Sigstore community
1515
[their documentation](https://docs.sigstore.dev/signing/signing_with_blobs/#signing-with-a-key) on the usage of the `--key` argument for key references.
1616
:::
1717

18-
| Method | Signing (`chainloop att push`) | Verifying (`chainloop wf run describe --verify true`) |
19-
|------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
20-
| Cosign key | `--key cosign.key` | `--key cosign.pub` |
21-
| KMS | `--key awskms://<KeyID>` | `--key awskms://<KeyID>` |
22-
| PKCS#11 | `--key pkcs11://<KeyId>` | `--key pkcs11://<KeyId>` |
23-
| Kubernetes secret | `--key k8s://<namespace>/<secretName>` (where `cosign.key` and `cosign.password` secrets are expected) | `--key k8s://<namespace>/<secretName>` (where `cosign.pub` is expected) |
24-
| Gitlab secret | `--key gitlab://<project>` (it will look for `COSIGN_PRIVATE_KEY`, `COSIGN_PASSWORD` variables) | `--key gitlab://<project>` (it will look for `COSIGN_PUBLIC_KEY` variable) |
25-
| Ephemeral (file based CA) | Configure your CA in [your deployment](https://github.com/chainloop-dev/chainloop/blob/main/deployment/chainloop/templates/controlplane/file_ca.secret.yaml) and omit the `--key` when pushing your attestation. | Use `--cert cert.pem --cert-chain my-root.pem` in the `describe` command |
26-
| Ephemeral ([EJBCA](https://github.com/Keyfactor/ejbca-ce)) | Connect your EJBCA instance to your Chainloop deployment using [these settings](https://github.com/chainloop-dev/chainloop/blob/main/deployment/chainloop/templates/controlplane/ejbca_ca.secret.yaml). Omit `--key` when pushing the attestation. | Use your verification material with `--cert` and `--cert-chain` options in the `wf run describe` command. <br/>See [bundles](#bundles) |
27-
| [SignServer](https://www.signserver.org/) | You can sign with your instance of SignServer with `--key signserver://host/worker` | Both signing certificate and chain must be provided out of band. Use `--cert signingcert.pem --cert-chain root.pem` to verify. <br/>See [bundles](#bundles) |
28-
29-
#### Bundles
30-
When signing with a verification method that supports it (like ephemeral certificates), you can download the verification material, to be used later during the verification process.
18+
### Signing with a local key
19+
These methods require setting up a key and/or KMS authentication in the local environment (laptop, CI system ...).
20+
21+
| Method | Signing (`chainloop att push`) | Verifying (`chainloop wf run describe --verify true`) |
22+
|-------------------|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
23+
| Cosign key | `--key cosign.key` | `--key cosign.pub` |
24+
| KMS | `--key awskms://<KeyID>` | `--key awskms://<KeyID>` |
25+
| PKCS#11 | `--key pkcs11://<KeyId>` | `--key pkcs11://<KeyId>` |
26+
| Kubernetes secret | `--key k8s://<namespace>/<secretName>` (where `cosign.key` and `cosign.password` secrets are expected) | `--key k8s://<namespace>/<secretName>` (where `cosign.pub` is expected) |
27+
| Gitlab secret | `--key gitlab://<project>` (it will look for `COSIGN_PRIVATE_KEY`, `COSIGN_PASSWORD` variables) | `--key gitlab://<project>` (it will look for `COSIGN_PUBLIC_KEY` variable) |
28+
29+
### Keyless signing
30+
These methods don't require any special setup in the client. For the verification command, you must make sure you get the CA certificate chain out-of-band, as it will be required to validate the ephemeral signing certificate.
31+
32+
| Method | Signing (`chainloop att push`) | Verifying (`chainloop wf run describe --verify true`) |
33+
|------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|
34+
| Ephemeral (file based CA) | Configure your CA in [your deployment](https://github.com/chainloop-dev/chainloop/blob/main/deployment/chainloop/templates/controlplane/file_ca.secret.yaml) and omit the `--key` when pushing your attestation. | See [bundles](#bundles) |
35+
| Ephemeral ([EJBCA](https://github.com/Keyfactor/ejbca-ce)) | Connect your EJBCA instance to your Chainloop deployment using [these settings](https://github.com/chainloop-dev/chainloop/blob/main/deployment/chainloop/templates/controlplane/ejbca_ca.secret.yaml). Omit `--key` when pushing the attestation. | See [bundles](#bundles) |
36+
| [SignServer](https://www.signserver.org/) | You can sign with your instance of SignServer with `--key signserver://host/worker` | See [bundles](#bundles) |
37+
38+
39+
### Bundles
40+
When signing with a verification method that supports it (like keyless with ephemeral certificates), you can download the verification material used for signing, to be used later during the verification process.
3141

3242
Just add `--bundle my-bundle.json` to the `push` command. Then, you can use the material to verify the attestation:
3343
```
3444
> cat my-bundle.json | jq -r ".verificationMaterial.x509CertificateChain.certificates.[].rawBytes" | base64 --decode | openssl x509 -inform DER -outform PEM -out cert.pem
3545
> chainloop wf run describe --digest ... --verify true --cert cert.pem --cert-chain my-root.pem
3646
```
3747

38-
#### Not yet supported
48+
### Not yet supported
3949

4050
The following methods are work in progress and **not yet supported**.
4151

0 commit comments

Comments
 (0)