Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update warning when users sign images by tag. #2313

Merged
merged 3 commits into from
Oct 14, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion IMPORT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
30 changes: 17 additions & 13 deletions KEYLESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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

```

Expand Down
19 changes: 13 additions & 6 deletions KMS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
13 changes: 10 additions & 3 deletions PKCS11.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down