Update warning when users sign images by tag. (#2313)

* Update warning when users sign images by tag.

See #2047.

Signed-off-by: Zachary Newman <zjn@chainguard.dev>

* Fix lots of docs

Signed-off-by: Zachary Newman <zjn@chainguard.dev>

* Add test cases for no-digest warning message

Also explicitly check for Digest being set, rather than Tag not being set. This
doesn't actually make a difference because name.ParseReference just throws away
the tag in such cases (maybe a bug), but it does make the intent clearer.

Signed-off-by: Zachary Newman <zjn@chainguard.dev>

Signed-off-by: Zachary Newman <zjn@chainguard.dev>

IMPORT.md

@@ -13,5 +13,5 @@ Public key written to import-cosign.pub
 ### Sign a container with imported keypair
 
 ```shell
-$ cosign sign --key import-cosign.key dlorenc/demo
+$ cosign sign --key import-cosign.key $IMAGE_DIGEST
 ```

KEYLESS.md

@@ -8,12 +8,19 @@ Try it out!
 This signature mode relies on the Sigstore Public Good Instance, which is rapidly heading toward a GA release!
 We don't have a date yet, but follow along on the [GitHub project](https://github.com/orgs/sigstore/projects/5).
 
+The following examples use this image:
+
+```shell
+$ IMAGE=gcr.io/dlorenc-vmtest2/demo
+$ IMAGE_DIGEST=$IMAGE@sha256:97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36
+```
+
 ## Usage
 
 Keyless signing:
 
 ```shell
-$ COSIGN_EXPERIMENTAL=1 cosign sign gcr.io/dlorenc-vmtest2/demo
+$ COSIGN_EXPERIMENTAL=1 cosign sign $IMAGE_DIGEST
 Generating ephemeral keys...
 Retrieving signed certificate...
 Your browser will now be opened to:
@@ -24,7 +31,7 @@ Pushing signature to: gcr.io/dlorenc-vmtest2/demo:sha256-97fc222cee7991b5b061d4d
 Keyless verifying:
 
 ```shell
-$ COSIGN_EXPERIMENTAL=1 cosign verify gcr.io/dlorenc-vmtest2/demo
+$ COSIGN_EXPERIMENTAL=1 cosign verify $IMAGE
 The following checks were performed on all of these signatures:
   - The cosign claims were validated
   - The claims were present in the transparency log
@@ -73,21 +80,18 @@ and producing an identity token.  Currently this supports Google and GitHub.
 From a GCE VM, you can use the VM's service account identity to sign an image:
 
 ```shell
-$ cosign sign --identity-token=$(
-    gcloud auth print-identity-token \
-        --audiences=sigstore) \
-    gcr.io/dlorenc-vmtest2/demo
+$ 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
-$ cosign sign --identity-token=$(
-    gcloud auth print-identity-token \
+$ IDENTITY_TOKEN=$(gcloud auth print-identity-token \
         --audiences=sigstore \
         --include-email \
-        --impersonate-service-account my-sa@my-project.iam.gserviceaccount.com) \
-    gcr.io/dlorenc-vmtest2/demo
+        --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
@@ -138,7 +142,7 @@ To use this instance, follow the steps below:
 1. `gsutil cp -r gs://tuf-root-staging/root.json .`
 1. `cd tuf-root-staging`
 1. `cosign initialize --mirror=tuf-root-staging --root=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}`
+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.
@@ -157,10 +161,10 @@ We need to clear the local TUF root data and re-initialize with the default prod
 If you're running your own sigstore services flags are available to set your own endpoint's, e.g
 
 ```
- COSIGN_EXPERIMENTAL=1 go run cmd/cosign/main.go sign -oidc-issuer "https://oauth2.example.com/auth" \
+ COSIGN_EXPERIMENTAL=1 cosign sign -oidc-issuer "https://oauth2.example.com/auth" \
                         -fulcio-url "https://fulcio.example.com" \
                         -rekor-url "https://rekor.example.com"  \
-                        ghcr.io/jdoe/somerepo/testcosign
+                        $IMAGE_DIGEST
 
 ```
 

KMS.md

@@ -33,13 +33,20 @@ jnVtSyKZxNzBfNMLLtVxdu8q+AigrGCS2KPmejda9bICTcHQCRUrD5OLGQ==
 
 ### Signing and Verification
 
+For the following examples, we have:
+
+```shell
+$ IMAGE=gcr.io/dlorenc-vmtest2/demo
+$ IMAGE_DIGEST=$IMAGE@sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd
+```
+
 To sign and verify using a key managed by a KMS provider, you can pass a provider-specific URI to the `--key` command:
 
 ```shell
-$ cosign sign --key <some provider>://<some key> gcr.io/dlorenc-vmtest2/demo
+$ cosign sign --key <some provider>://<some key> $IMAGE_DIGEST
 Pushing signature to: gcr.io/dlorenc-vmtest2/demo:sha256-410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd.cosign
 
-$ cosign verify --key <some provider>://<some key> gcr.io/dlorenc-vmtest2/demo
+$ cosign verify --key <some provider>://<some key> $IMAGE
 
 Verification for gcr.io/dlorenc-vmtest2/demo --
 The following checks were performed on each of these signatures:
@@ -54,7 +61,7 @@ You can also export the public key and verify against that file:
 
 ```shell
 $ cosign public-key --key <some provider>://<some key> > kms.pub
-$ cosign verify --key kms.pub gcr.io/dlorenc-vmtest2/demo
+$ cosign verify --key kms.pub $IMAGE
 ```
 
 ### Providers
@@ -104,8 +111,8 @@ $ export AWS_CMK_ID=$(aws kms create-key --customer-master-key-spec RSA_4096 \
                                          --description "Cosign Signature Key Pair" \
                                          --query KeyMetadata.KeyId --output text)
 
-$ cosign sign --key awskms:///${AWS_CMK_ID} docker.io/davivcgarcia/hello-world:latest
-$ cosign verify --key awskms:///${AWS_CMK_ID} docker.io/davivcgarcia/hello-world:latest | jq .
+$ cosign sign --key awskms:///${AWS_CMK_ID} $IMAGE_DIGEST
+$ cosign verify --key awskms:///${AWS_CMK_ID} $IMAGE | jq .
 ```
 
 ### GCP
@@ -140,7 +147,7 @@ The following environment variables must be set to let cosign authenticate to Az
 
 To create a key using `cosign generate-key-pair --kms azurekms://[VAULT_NAME][VAULT_URI]/[KEY]` you will need a user which has permissions to create keys in Key Vault. For example `Key Vault Crypto Officer` role.
 
-To sign images using `cosign sign --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] [IMAGE]` you will need a user which has permissions to the sign action such as the `Key Vault Crypto User` role.
+To sign images using `cosign sign --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] [IMAGE DIGEST]` you will need a user which has permissions to the sign action such as the `Key Vault Crypto User` role.
 
 ### Hashicorp Vault
 

PKCS11.md

@@ -3,6 +3,13 @@
 The `cosign` command line tool optionally supports PKCS11 tokens for signing.
 This support is enabled through the [crypto11](https://github.com/ThalesIgnite/crypto11) and the [pkcs11](https://github.com/miekg/pkcs11) libraries, which are not included in the standard release. Use [`make cosign-pivkey-pkcs11key`](https://github.com/sigstore/cosign/blob/a8d1cc1132d4a019a62ff515b9375c8c5b98a5c5/Makefile#L52), or `go build -tags=pkcs11key`, to build `cosign` with support for PKCS11 tokens.
 
+For the following examples, we have:
+
+```shell
+$ IMAGE=gcr.io/dlorenc-vmtest2/demo
+$ IMAGE_DIGEST=$IMAGE@sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd
+```
+
 ## Quick Start
 
 ### Setup
@@ -55,14 +62,14 @@ If `pin-value` is not present in the URI, `cosign` expects the PIN to be set usi
 You can then use the normal `cosign` commands to sign images and blobs with your PKCS11 key.
 
 ```shell
-$ cosign sign --key "<PKCS11_URI>" gcr.io/dlorenc-vmtest2/demo
+$ cosign sign --key "<PKCS11_URI>" $IMAGE_DIGEST
 Pushing signature to: gcr.io/dlorenc-vmtest2/demo:sha256-410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd.sig
 ```
 
 To verify, you can either use the PKCS11 token key directly:
 
 ```shell
-$ cosign verify --key "<PKCS11_URI>" gcr.io/dlorenc-vmtest2/demo
+$ cosign verify --key "<PKCS11_URI>" $IMAGE
 Verification for gcr.io/dlorenc-vmtest2/demo --
 The following checks were performed on each of these signatures:
 - The cosign claims were validated
@@ -77,7 +84,7 @@ Or export the public key and verify against that:
 ```shell
 $ cosign public-key --key "<PKCS11_URI>" > pub.key
 
-$ cosign verify --key pub.key gcr.io/dlorenc-vmtest2/demo
+$ cosign verify --key pub.key $IMAGE_DIGEST
 Verification for gcr.io/dlorenc-vmtest2/demo --
 The following checks were performed on each of these signatures:
 - The cosign claims were validated