diff options
Diffstat (limited to 'doc/ci/yaml/signing_examples.md')
| -rw-r--r-- | doc/ci/yaml/signing_examples.md | 20 |
1 files changed, 12 insertions, 8 deletions
diff --git a/doc/ci/yaml/signing_examples.md b/doc/ci/yaml/signing_examples.md index 72e007a749f..e97ade891c4 100644 --- a/doc/ci/yaml/signing_examples.md +++ b/doc/ci/yaml/signing_examples.md @@ -7,12 +7,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Use Sigstore for keyless signing and verification **(FREE SAAS)** The [Sigstore](https://www.sigstore.dev/) project provides a CLI called -[Cosign](https://docs.sigstore.dev/cosign/overview/) which can be used for keyless signing of container images built +[Cosign](https://docs.sigstore.dev/signing/quickstart/) which can be used for keyless signing of container images built with GitLab CI/CD. Keyless signing has many advantages, including eliminating the need to manage, safeguard, and rotate a private key. Cosign requests a short-lived key pair to use for signing, records it on a certificate transparency log, and then discards it. The key is generated through a token obtained from the GitLab server using the OIDC identity of the user who ran the pipeline. This token includes unique claims that certify the token was generated by a CI/CD pipeline. To learn more, -see Cosign [documentation](https://docs.sigstore.dev/cosign/overview/#example-working-with-containers) on keyless signatures. +see Cosign [documentation](https://docs.sigstore.dev/signing/quickstart/#example-working-with-containers) on keyless signatures. For details on the mapping between GitLab OIDC claims and Fulcio certificate extensions, see the GitLab column of [Mapping OIDC token claims to Fulcio OIDs](https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md#mapping-oidc-token-claims-to-fulcio-oids). @@ -30,17 +30,21 @@ You can use Cosign to sign and verify container images and build artifacts. - You must use a version of Cosign that is `>= 2.0.1`. +**Limitations** + +- The `id_tokens` portion of the CI/CD config file must be located in the project that is being built and signed. AutoDevOps, CI files included from another repository, and child pipelines are not supported. Work to remove this limitation is being tracked in [issue 411317](https://gitlab.com/gitlab-org/gitlab/-/issues/411317). + **Best practices**: - Build and sign an image/artifact in the same job to prevent it from being tampered with before it is signed. - When signing container images, sign the digest (which is immutable) instead of the tag. GitLab [ID tokens](../secrets/id_token_authentication.md#id-tokens) can be used by Cosign for -[keyless signing](https://docs.sigstore.dev/cosign/overview/). The token must have +[keyless signing](https://docs.sigstore.dev/signing/quickstart/). The token must have `sigstore` set as the [`aud`](../secrets/id_token_authentication.md#token-payload) claim. The token can be used by Cosign automatically when it is set in the `SIGSTORE_ID_TOKEN` environment variable. -To learn more about how to install Cosign, see [Cosign Installation documentation](https://docs.sigstore.dev/cosign/installation/). +To learn more about how to install Cosign, see [Cosign Installation documentation](https://docs.sigstore.dev/system_config/installation/). ### Signing @@ -49,7 +53,7 @@ To learn more about how to install Cosign, see [Cosign Installation documentatio The example below demonstrates how to sign a container image in GitLab CI. The signature is automatically stored in the same container repository as the image. -To learn more about signing containers, see [Cosign Signing Containers documentation](https://docs.sigstore.dev/cosign/signing_with_containers/). +To learn more about signing containers, see [Cosign Signing Containers documentation](https://docs.sigstore.dev/signing/signing_with_containers/). ```yaml build_and_sign_image: @@ -77,7 +81,7 @@ build_and_sign_image: The example below demonstrates how to sign a build artifact in GitLab CI. You should save the `cosign.bundle` file produced by `cosign sign-blob`, which is used for signature verification. -To learn more about signing artifacts, see [Cosign Signing Blobs documentation](https://docs.sigstore.dev/cosign/signing_with_blobs/#keyless-signing-of-blobs-and-files). +To learn more about signing artifacts, see [Cosign Signing Blobs documentation](https://docs.sigstore.dev/signing/signing_with_blobs/). ```yaml build_and_sign_artifact: @@ -109,7 +113,7 @@ build_and_sign_artifact: | `--certificate-oidc-issuer` | The GitLab instance URL where the image/artifact was signed. For example, `https://gitlab.com`. | | `--bundle` | The `bundle` file produced by `cosign sign-blob`. Only used for verifying build artifacts. | -To learn more about verifying signed images/artifacts, see [Cosign Verifying documentation](https://docs.sigstore.dev/cosign/verify/#keyless-verification-using-openid-connect). +To learn more about verifying signed images/artifacts, see [Cosign Verifying documentation](https://docs.sigstore.dev/verifying/verify/). #### Container images @@ -149,7 +153,7 @@ You can use Sigstore and npm, together with GitLab CI/CD, to digitally sign buil ### About npm provenance -[npm CLI](https://docs.npmjs.com/cli) allows package maintainers to provide users with provenance attestations. Using npm +[npm CLI](https://docs.npmjs.com/cli/) allows package maintainers to provide users with provenance attestations. Using npm CLI provenance generation allows users to trust and verify that the package they are downloading and using is from you and the build system that built it. |