diff --git a/content/en/cosign/keyless.md b/content/en/cosign/keyless.md deleted file mode 100644 index 3816d6fd..00000000 --- a/content/en/cosign/keyless.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: "Keyless Signatures" -category: "Cosign" -position: 122 ---- - -This page explains how the keyless signatures work in Cosign. This signature mode relies on the Sigstore Public Good Instance. - -## Quickstart - -> NOTE: You will need access to a container registry for cosign to work with. [ttl.sh](https://ttl.sh/) offers free, short-lived (ie: hours), anonymous container image hosting if you just want to try these commands out. - -Using `ttl.sh` and [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane) for to prepare the image that we want to sign, run the following: - -```shell -$ SRC_IMAGE=busybox -$ SRC_DIGEST=$(crane digest busybox) -$ IMAGE_URI=ttl.sh/$(uuidgen | head -c 8 | tr 'A-Z' 'a-z') -$ crane cp $SRC_IMAGE@$SRC_DIGEST $IMAGE_URI:1h -$ IMAGE_URI_DIGEST=$IMAGE_URI@$SRC_DIGEST -``` - -Using the image that we prepared above, run through the following to perform Keyless signing and Keyless verifying. - -### Keyless Signing - -```shell -$ COSIGN_EXPERIMENTAL=1 cosign sign $IMAGE_URI_DIGEST -Generating ephemeral keys... -Retrieving signed certificate... - - Note that there may be personally identifiable information associated with this signed artifact. - This may include the email address associated with the account with which you authenticate. - This information will be used for signing this artifact and will be stored in public transparency logs and cannot be removed later. - By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs. - -Are you sure you want to continue? (y/[N]): y -Your browser will now be opened to: -https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&code_challenge=Dl6DvO9FOJ2G2rb0isnG5-S1hAbcQV6PkJgDlDyFqGM&code_challenge_method=S256&nonce=2KyBdYtLSqyLGOwUkt1ij1Fiu30&redirect_uri=http%3A%2F%2Flocalhost%3A55362%2Fauth%2Fcallback&response_type=code&scope=openid+email&state=2KyBdXb8zadBfqMdbVoAIz88OBy -Successfully verified SCT... -tlog entry created with index: 12151804 -Pushing signature to: ttl.sh/ace19e66 -``` - -### Keyless verifying - -```shell -$ COSIGN_EXPERIMENTAL=1 cosign verify $IMAGE_URI_DIGEST -Verification for ttl.sh/ace19e66@sha256:7b3ccabffc97de872a30dfd234fd972a66d247c8cfc69b0550f276481852627c -- -The following checks were performed on each of these signatures: - - The cosign claims were validated - - Existence of the claims in the transparency log was verified offline - - Any certificates were verified against the Fulcio roots. - -[{"critical":{"identity":{"docker-reference":"ttl.sh/ace19e66"},"image":{"docker-manifest-digest":"sha256:7b3ccabffc97de872a30dfd234fd972a66d247c8cfc69b0550f276481852627c"},"type":"cosign container image signature"},"optional": null}] -``` - -The rest of the flags (annotations, claims, tlog, etc.) should all work the same. - -## Overview - -This uses ephemeral keys and certificates, which are signed automatically by the `fulcio` CA. -Signatures are stored in the `rekor` transparency log, which automatically provides an attestation -as to when the signature was created. - -Information on the `fulcio` CA can be found in the [fulcio repository](https://github.com/sigstore/fulcio). - -### OAuth Flows - -Cosign supports two OAuth flows today: the standard flow and the device flow. - -When there is no terminal attached (non-interactive mode), Cosign will automatically use the device flow -where a link is printed to stdout. -This link must be opened in a browser to complete the flow. - -### Identity Tokens - -In automated environments, Cosign also supports directly using OIDC Identity Tokens from specific issuers. -These can be supplied on the command line with the `--identity-token` flag. -The `audiences` field must contain `sigstore`. - -Cosign also has support for detecting some of these automated environments -and producing an identity token. Currently this supports Google Compute Engine, GitHub Actions and SPIFFE tokens. - -#### On GCP - -From a GCE VM, you can use the VM's service account identity to sign an image: - -```shell -$ IDENTITY_TOKEN=$(gcloud auth print-identity-token --audiences=sigstore) -$ cosign sign --identity-token=$IDENTITY_TOKEN $IMAGE_DIGEST -``` - -From outside a GCE VM, you can impersonate a GCP IAM service account to sign an image: - -```shell -$ IDENTITY_TOKEN=$(gcloud auth print-identity-token \ - --audiences=sigstore \ - --include-email \ - --impersonate-service-account my-sa@my-project.iam.gserviceaccount.com) -$ cosign sign --identity-token=$IDENTITY_TOKEN $IMAGE_DIGEST -``` - -In order to impersonate an IAM service account, your account must have the -`roles/iam.serviceAccountTokenCreator` role. - -**Note**: On Google Cloud Build, standard identity tokens are not supported through the GCE metadata server. -Cosign has a special flow for this case, where you can instruct the Cloud Build service account to impersonate -another service account. -To configure this flow: - -1. Create a service account to use for signatures (the email address will be present in the certificate subject). -2. Grant the Cloud Build service account the `roles/iam.serviceAccountTokenCreator` role for this target account. -3. Set the `GOOGLE_SERVICE_ACCOUNT_NAME` environment variable to the name of the target account in your cloudbuild.yaml -4. Sign images in GCB, without keys! - -### Timestamps - -Signature timestamps are checked in the [rekor](https://github.com/sigstore/rekor) transparency log. Rekor's `IntegratedTime` is signed as part of its `signedEntryTimestamp`. Cosign verifies the signature over the timestamp and checks that the signature was created while the certificate was valid. - -> TODO: Add more documentation here - -## Public Staging Environment - -There is a public staging environment that is running Fulcio, Rekor and OIDC issuer. - -**NOTE** The staging environment provides no SLO guarantees nor the same protection of the root key material for TUF. This environment is meant for development and testing only, PLEASE do not use for production purposes. - -The endpoints are as follows: - -* https://fulcio.sigstage.dev -* https://rekor.sigstage.dev -* https://oauth2.sigstage.dev/auth - -These instances are operated and maintained in the same manner as the public production environment for Sigstore. - -### Usage - -To use this instance, follow the steps below: - -1. `rm -r ~/.sigstore` -1. `curl -O https://raw.githubusercontent.com/sigstore/root-signing/main/staging/repository/1.root.json` -1. `cosign initialize --mirror=https://tuf-repo-cdn.sigstore.dev --root=1.root.json` -1. `COSIGN_EXPERIMENTAL=1 cosign sign --oidc-issuer "https://oauth2.sigstage.dev/auth" --fulcio-url "https://fulcio.sigstage.dev" --rekor-url "https://rekor.sigstage.dev" ${IMAGE_DIGEST}` -1. `COSIGN_EXPERIMENTAL=1 cosign verify --rekor-url "https://rekor.sigstage.dev" ${IMAGE}` - -* Steps 1-4 configures your local environment to use the staging keys and certificates. -* Step 5 specify the staging environment with flags needed for signing. -* Step 6 specify the staging environment with flags needed for verifying. - -#### Revert Back to Production - -We need to clear the local TUF root data and re-initialize with the default production TUF root data. - -1. `rm -r ~/.sigstore` -1. `cosign initialize` - -## Custom Components - -For configuring Cosign to work with custom components, checkout the [Configuring Cosign with Custom Components](https://docs.sigstore.dev/cosign/custom_components/) docs to find out how to achieve this. - -### Custom Root Cert - -You can override the public good instance CA using the environment variable `SIGSTORE_ROOT_FILE`, e.g. - -```shell -export SIGSTORE_ROOT_FILE="/home/jdoe/myrootCA.pem" -``` diff --git a/content/en/cosign/openid_signing.md b/content/en/cosign/openid_signing.md index c467b669..5d464e1f 100644 --- a/content/en/cosign/openid_signing.md +++ b/content/en/cosign/openid_signing.md @@ -99,10 +99,6 @@ In order to impersonate an IAM service account, your account must have the `role 3. Set the `GOOGLE_SERVICE_ACCOUNT_NAME` environment variable to the name of the target account in your cloudbuild.yaml 4. Sign images in GCB, without keys! -### Timestamps - -Signature timestamps are checked in the [rekor](https://github.com/sigstore/rekor) transparency log. Rekor's `IntegratedTime` is signed as part of its `signedEntryTimestamp`. Cosign verifies the signature over the timestamp and checks that the signature was created while the certificate was valid. - ## Upcoming work * Root CA hardening: We should use intermediate certs rather than the root, and support chained verification. diff --git a/content/en/cosign/overview.md b/content/en/cosign/overview.md index d1dd7f07..72569e30 100644 --- a/content/en/cosign/overview.md +++ b/content/en/cosign/overview.md @@ -36,7 +36,7 @@ The bundle contains signing metadata, including the signature and certificate. The Cosign command requests a certificate from the Sigstore certificate authority, Fulcio. Fulcio checks your identity by using an authentication protocol (OpenID Connect) to confirm your email address. If your identity is correct, Fulcio grants a short-lived, time-stamped certificate. The certificate is bound to the public key to attest to your identity. This activity is logged using the Sigstore transparency and timestamping log, Rekor. -Note that you don’t need to use a key to sign. Currently, you can authenticate with Google, GitHub, or Microsoft, which will associate your identity with a short-lived signing key. For more information, read [Keyless Signatures](/cosign/keyless/). +Note that you don’t need to use a key to sign. Currently, you can authenticate with Google, GitHub, or Microsoft, which will associate your identity with a short-lived signing key. For more information about Cosign's additional options and features, run the command: @@ -63,24 +63,44 @@ $ cosign verify-blob --bundle cosign.bundle --certificate-identity=name@e To verify, Cosign queries the transparency log (Rekor) to compare the public key bound to the certificate, and checks the timestamp on the signature against the artifact’s entry in the transparency log. The signature is valid if its timestamp falls within the small window of time that the key pair and certificate issued by the certificate authority were valid. -### Working with containers +## Example: Working with containers -Signing and verifying a container is similar to working with blobs. The Cosign command to sign a container image is: +> NOTE: In this example, we will create a container using [ttl.sh](https://ttl.sh/). It offers free, short-lived (as in minutes or hours), anonymous container image hosting so you can try out signing and verifying commands in a sample workflow + +To use `ttl.sh` and [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane) to prepare the image to sign, run the following: ``` -$ cosign sign +$ SRC_IMAGE=busybox +$ SRC_DIGEST=$(crane digest busybox) +$ IMAGE_URI=ttl.sh/$(uuidgen | head -c 8 | tr 'A-Z' 'a-z') +$ crane cp $SRC_IMAGE@$SRC_DIGEST $IMAGE_URI:1h +$ IMAGE_URI_DIGEST=$IMAGE_URI@$SRC_DIGEST ``` -This works the same as signing a blob, but the signature and certificate are attached as container metadata. +### Keyless signing of a container -To verify a signed container image, use the following command: +The following code signs the created container image. The command to sign container images is `cosign sign `. For our example, `` is `$IMAGE_URI_DIGEST`. Note that for containers, there is no bundle as there is with blobs, as the signature and certificate are attached directly to the container: + +``` +$ cosign sign $IMAGE_URI_DIGEST +``` + +### Keyless verifying of a container + +This works similarly to verifying a blob, but there is no need to place the certificate and signature on the `cosign verify` command. To verify a signed container image, use the following command: ``` $ cosign verify --certificate-identity=name@example.com --certificate-oidc-issuer=https://accounts.example.com ``` -### Signing with a generated key +> Note that for our example we use the `regexp` versions of the identity options: + +``` +cosign verify $IMAGE_URI_DIGEST --certificate-identity-regexp=.* --certificate-oidc-issuer-regexp=.* +``` + +## Signing with a generated key It is recommended that you use keyless signing, as a main feature of Sigstore is to make signatures invisible infrastructure that do not require key management. However, Sigstore allows you to use an existing key or generate a key if you prefer. @@ -97,19 +117,19 @@ $ cosign sign --key cosign.key user/demo Enter password for private key: Pushing signature to: index.docker.io/user/demo:sha256-87ef60f558bad79be4def8.sig ``` +## SCM Integration -### Other Formats +Cosign integrates natively with source code management (SCM) systems like GitHub and GitLab. You can use the official [GitHub Actions Cosign installer](https://github.com/marketplace/actions/cosign-installer) or use Cosign to generate and work safely with [SCM secrets](/cosign/git_support/) with native API integration. -Cosign is useful not only for blobs, containers, and container-related artifacts; it can also be used for other file types. +## Attestations -To learn how to sign SBOMs, WASM modules, Tekton bundles and more, review [Signing Other Types](/cosign/other_types/). For more information about blobs, review [Working with Blobs](/cosign/working_with_blobs/). +In addition to signatures, Cosign can be used with [In-Toto Attestations](https://github.com/in-toto/attestation). -### SCM Integration +Attestations provide an additional semantic-layer on top of plain cryptographic signatures that can be used in policy systems. Learn more in the [Attestations](/cosign/attestation) documentation. -Cosign integrates natively with source code management (SCM) systems like GitHub and GitLab. You can use the official [GitHub Actions Cosign installer](https://github.com/marketplace/actions/cosign-installer) or use cosign to generate and work safely with [SCM secrets](/cosign/git_support/) with native API integration. +## Other Formats -### Attestations +Cosign is useful not only for blobs, containers, and container-related artifacts; it can also be used for other file types. -In addition to signatures, Cosign can be used with [In-Toto Attestations](https://github.com/in-toto/attestation). +To learn how to sign SBOMs, WASM modules, Tekton bundles and more, review [Signing Other Types](/cosign/other_types/). For more information about blobs, review [Signing Blobs](/cosign/signing_with_blobs/). For containers, see [Signing Containers](/cosign/signing_with_containers/). -Attestations provide an additional semantic-layer on top of plain cryptographic signatures that can be used in policy systems. diff --git a/content/en/cosign/public_deployment.md b/content/en/cosign/public_deployment.md new file mode 100644 index 00000000..2e2a9c07 --- /dev/null +++ b/content/en/cosign/public_deployment.md @@ -0,0 +1,40 @@ +--- +title: "Public Deployment" +category: "Cosign" +position: 122 +--- + +There is a public staging environment, or deployment, that is running Fulcio, Rekor and OIDC issuer. + +**NOTE** The staging environment provides neither SLO guarantees nor the same protection of the root key material for TUF. This environment is meant for development and testing only. It is not appropriate to use for production purposes. + +The endpoints are as follows: + +* https://fulcio.sigstage.dev +* https://rekor.sigstage.dev +* https://oauth2.sigstage.dev/auth + +These instances are operated and maintained in the same manner as the public production environment for Sigstore. + +### Usage + +To use this instance, follow the steps below: + +1. `rm -r ~/.sigstore` +1. `curl -O https://raw.githubusercontent.com/sigstore/root-signing/main/staging/repository/1.root.json` +1. `cosign initialize --mirror=https://tuf-repo-cdn.sigstore.dev --root=1.root.json` +1. `cosign sign --oidc-issuer "https://oauth2.sigstage.dev/auth" --fulcio-url "https://fulcio.sigstage.dev" --rekor-url "https://rekor.sigstage.dev" ${IMAGE_DIGEST}` +1. `cosign verify --rekor-url "https://rekor.sigstage.dev" ${IMAGE}` --certificate-identity=name@example.com + --certificate-oidc-issuer=https://accounts.example.com + +* Steps 1-4 configure your local environment to use the staging keys and certificates. +* Step 5 specifies the staging environment with flags needed for signing. +* Step 6 specifies the staging environment with flags needed for verifying. + +#### Revert Back to Production + +In order to revert, we need to clear the local TUF root data and re-initialize with the default production TUF root data. + +1. `rm -r ~/.sigstore` +1. `cosign initialize` + diff --git a/content/en/cosign/timestamps.md b/content/en/cosign/timestamps.md new file mode 100644 index 00000000..17e62860 --- /dev/null +++ b/content/en/cosign/timestamps.md @@ -0,0 +1,9 @@ +--- +title: "Timestamps" +category: "Cosign" +position: 113 +--- + +> Note: This document is a work in progress. + +Signature timestamps are checked in the [Rekor](https://github.com/sigstore/rekor) transparency log. Rekor's `IntegratedTime` is signed as part of its `signedEntryTimestamp`. Cosign verifies the signature against the timestamp and checks that the signature was created while the certificate was valid. diff --git a/content/en/cosign/verify.md b/content/en/cosign/verify.md index 397cb8a4..097ebb66 100644 --- a/content/en/cosign/verify.md +++ b/content/en/cosign/verify.md @@ -210,6 +210,17 @@ MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgrKKtyws86/APoULh/zXk4LONqII AcxvLtLEgRjRI4TKnMAXtIGp8K4X4CTWPEXMqSYZZUa2I1YvHyLLY2bEzA== -----END PUBLIC KEY----- ``` +## Custom Components + +For configuring Cosign to work with custom components, checkout the [Configuring Cosign with Custom Components](https://docs.sigstore.dev/cosign/custom_components/) docs to find out how to achieve this. + +### Custom Root Cert + +You can override the public good instance CA using the environment variable `SIGSTORE_ROOT_FILE` by running the following. + +``` +export SIGSTORE_ROOT_FILE="/home/jdoe/myrootCA.pem" +``` ## Experimental Features