diff --git a/CODEOWNERS b/CODEOWNERS index e765bb242..019abfab0 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,19 +1,3 @@ -@sigstore/cosign-codeowners - # The CODEOWNERS are managed via a GitHub team, but the current list is (in alphabetical order): - -# asraa -# bobcallaway -# dekkagaijin -# dentrax -# developer-guy -# dlorenc -# font -# hectorj2f -# loosebazooka -# luhring +# # lukehinds -# mattmoor -# n3wscott -# priyawadhwa -# vaikas diff --git a/DEPRECATIONS.md b/DEPRECATIONS.md deleted file mode 100644 index ee6d1cf9a..000000000 --- a/DEPRECATIONS.md +++ /dev/null @@ -1,10 +0,0 @@ -# Deprecations - -This doc lists deprecated features in `cosign`. -You can read more about Sigstore's deprecation policy [here](https://docs.sigstore.dev/api-stability)! - -| **Feature Being Deprecated** | **API Stability Level** | **Earliest Date of Removal** | -|------------------------------|-------------------------|------------------------------| -| My feature | Experimental/Beta/GA | DD/MM/YY | -| | | | -| | | | diff --git a/FEATURES.md b/FEATURES.md deleted file mode 100644 index 232f5e3bd..000000000 --- a/FEATURES.md +++ /dev/null @@ -1,36 +0,0 @@ -# Feature Stability - -This doc covers feature stability in `cosign` as described in the [API Stability Policy](https://docs.sigstore.dev/api-stability) for Sigstore. - -## Experimental -* Keyless signing using the `Fulcio` CA -* Storing signatures in a transparency log -* The `pkg/cosign/oci` client library - -Some formats that cosign relies upon are not stable yet either: -* The SBOM specification for storing SBOMs in a container registry -* The In-Toto attestation format - - -## Beta -* All cosign subcommands, including flags and output - - -## General Availability - -### Key Management - -* fixed, text-based keys generated using `cosign generate-key-pair` -* cloud KMS-based keys generated using `cosign generate-key-pair -kms` -* keys generated on hardware tokens using the PIV interface using `cosign piv-tool` -* Kubernetes-secret based keys generated using `cosign generate-key-pair k8s://namespace/secretName` - - -### Artifact Types - -* OCI and Docker Images -* Other artifacts that can be stored in a container registry, including: - * Tekton Bundles - * Helm Charts - * WASM modules -* Text files and other binary blobs, using `cosign sign-blob` diff --git a/FUN.md b/FUN.md deleted file mode 100644 index 0537feb7a..000000000 --- a/FUN.md +++ /dev/null @@ -1,6 +0,0 @@ -# Fun Tips And Tricks! - -## Signing Git Commits - -Git commit signing has been broken out into its own project! Check out -https://github.com/sigstore/gitsign for more. diff --git a/IMPORT.md b/IMPORT.md deleted file mode 100644 index 91f54a613..000000000 --- a/IMPORT.md +++ /dev/null @@ -1,17 +0,0 @@ -# Import RSA and EC Keypairs -* Currently only supports RSA and ECDSA private keys - -### Import a keypair - -```shell -$ cosign import-key-pair --key opensslrsakey.pem -Enter password for private key: -Enter password for private key again: -Private key written to import-cosign.key -Public key written to import-cosign.pub -``` -### Sign a container with imported keypair - -```shell -$ cosign sign --key import-cosign.key dlorenc/demo -``` diff --git a/KEYLESS.md b/KEYLESS.md deleted file mode 100644 index 4121b9733..000000000 --- a/KEYLESS.md +++ /dev/null @@ -1,174 +0,0 @@ -# Keyless Signatures - -The full design document for this can be found [here](https://docs.google.com/document/d/189w4Fp1GEA1b2P633HyqTwtcWFNTu_Af4meolMa_1_8/edit?resourcekey=0-QoqNqcHXvSuPnMUdn8RGOQ#heading=h.2mtrw7byet02) -(join sigstore-dev@googlegroups.com for access). - -This document explains how the `keyless` signatures work in `cosign`. -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). - -## Usage - -Keyless signing: - -```shell -$ COSIGN_EXPERIMENTAL=1 cosign sign gcr.io/dlorenc-vmtest2/demo -Generating ephemeral keys... -Retrieving signed certificate... -Your browser will now be opened to: -https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&client_id=&redirect_uri=http%3A%2F%2F127.0.0.1%3A5556%2Fauth%2Fgoogle%2Fcallback&response_type=code -Pushing signature to: gcr.io/dlorenc-vmtest2/demo:sha256-97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36.sig -``` - -Keyless verifying: - -```shell -$ COSIGN_EXPERIMENTAL=1 cosign verify gcr.io/dlorenc-vmtest2/demo -The following checks were performed on all of these signatures: - - The cosign claims were validated - - The claims were present in the transparency log - - The signatures were integrated into the transparency log when the certificate was valid - - Any certificates were verified against the Fulcio roots. -Certificate subject: dlorenc@google.com -{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36"},"Type":"cosign container image signature"},"Optional":null} -``` - -That's it! No keys! -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` root 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` root CA can be found in the [fulcio repository](https://github.com/sigstore/fulcio). - -### Keys - -The root CA keys are hard-coded in `cosign` today. -They can only be changed by recompiling the binary. -This will be made more configurable in the future. - -### 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 and GitHub. - -#### On GCP - -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 -``` - -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 \ - --audiences=sigstore \ - --include-email \ - --impersonate-service-account my-sa@my-project.iam.gserviceaccount.com) \ - gcr.io/dlorenc-vmtest2/demo -``` - -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. - -## Upcoming work - -* Root CA hardening: We should use intermediate certs rather than the root, and support chained verification. -* Root CA configuration: We should allow users to change the roots and add their own. -* Other timestamps: We should allow for other timestamp attestations, including attached [RFC3161](https://www.ietf.org/rfc/rfc3161.txt) signatures. -* Probably a lot more: This is very experimental. -* More OIDC providers: Obvious. - -## 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. `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 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 Infrastructure - -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" \ - -fulcio-url "https://fulcio.example.com" \ - -rekor-url "https://rekor.example.com" \ - ghcr.io/jdoe/somerepo/testcosign - -``` - -### Custom root Cert - -You can override the public good instance root CA using the environment variable `SIGSTORE_ROOT_FILE`, e.g. - -``` -export SIGSTORE_ROOT_FILE="/home/jdoe/myrootCA.pem" -``` diff --git a/PKCS11.md b/PKCS11.md deleted file mode 100644 index 076c157e6..000000000 --- a/PKCS11.md +++ /dev/null @@ -1,89 +0,0 @@ -# PKCS11 Tokens - -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. - -## Quick Start - -### Setup - -To get started, make sure you already have your PKCS11 module installed, and insert your PKCS11-compatible token. - -Then, run the command `cosign pkcs11-tool list-tokens` to get the slot id of your token, as follows : - -```shell -$ cosign pkcs11-tool list-tokens --module-path /usr/local/lib/libp11.so -Listing tokens of PKCS11 module '/usr/local/lib/libp11.so' -Token in slot 1 - Label: TokenLabel - Manufacturer: Token Manufacturer - Model: Token Model - S/N: 68800ca5c75e074c -``` - -Afterwards, run the command `cosign pkcs11-tool list-keys-uris` to retrieve the PKCS11 URI of the key you wish to use, as follows : - -```shell -$ cosign pkcs11-tool list-keys-uris --module-path /usr/local/lib/libp11.so --slot-id 1 --pin 1234 -Listing URIs of keys in slot '1' of PKCS11 module '/usr/local/lib/libp11.so' -Object 0 - Label: key_label_1 - ID: 4a8d2f6ed9c4152b260d6c74a1ae72fcfdc64b65 - URI: pkcs11:token=TokenLabel;slot-id=1;id=%4a%8d%2f%6e%d9%c4%15%2b%26%0d%6c%74%a1%ae%72%fc%fd%c6%4b%65?module-path=/usr/local/lib/libp11.so&pin-value=1234 -Object 1 - Label: key_label_2 - ID: 57b39235cc6dec404c2310d7e37d5cbb5f1bba70 - URI: pkcs11:token=TokenLabel;slot-id=1;id=%57%b3%92%35%cc%6d%ec%40%4c%23%10%d7%e3%7d%5c%bb%5f%1b%ba%70?module-path=/usr/local/lib/libp11.so&pin-value=1234 -``` - -You can also construct the PKCS11 URI of your key manually by providing the following URI components : - -* **module-path** : the absolute path to the PKCS11 module **(optional)** - -* **token** and/or **slot-id** : either or both of the PKCS11 token label and the PKCS11 slot id **(mandatory)** - -* **object** and/or **id** : either or both of the PKCS11 key label and the PKCS11 key id **(mandatory)** - -* **pin-value** : the PIN of the PKCS11 token **(optional)** - -If `module-path` is not present in the URI, `cosign` expects the PKCS11 module path to be set using the environment variable `COSIGN_PKCS11_MODULE_PATH`. If neither are set, `cosign` will fail. If both are set, `module-path` has priority over `COSIGN_PKCS11_MODULE_PATH` environment variable. - -If `pin-value` is not present in the URI, `cosign` expects the PIN to be set using the environment variable `COSIGN_PKCS11_PIN`. If it is not, `cosign` checks whether the PKCS11 token requires user login (flag CKF_LOGIN_REQUIRED set), and if so, `cosign` will invite the user to enter the PIN only during signing. If both `pin-value` and `COSIGN_PKCS11_PIN` environment variable are set, `pin-value` has priority over `COSIGN_PKCS11_PIN`. - -### Signing - -You can then use the normal `cosign` commands to sign images and blobs with your PKCS11 key. - -```shell -$ cosign sign --key "" gcr.io/dlorenc-vmtest2/demo -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 "" gcr.io/dlorenc-vmtest2/demo -Verification for gcr.io/dlorenc-vmtest2/demo -- -The following checks were performed on each of these signatures: -- The cosign claims were validated -- The signatures were verified against the specified public key -- Any certificates were verified against the Fulcio roots. - -[{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}] -``` - -Or export the public key and verify against that: - -```shell -$ cosign public-key --key "" > pub.key - -$ cosign verify --key pub.key gcr.io/dlorenc-vmtest2/demo -Verification for gcr.io/dlorenc-vmtest2/demo -- -The following checks were performed on each of these signatures: -- The cosign claims were validated -- The signatures were verified against the specified public key -- Any certificates were verified against the Fulcio roots. - -[{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}] - -``` diff --git a/README.md b/README.md index 5adcd8ac9..0f4474565 100644 --- a/README.md +++ b/README.md @@ -1,754 +1,10 @@ -

- Cosign logo -

+# Policy Controller -# cosign +Kubernetes webhook for configuring admission policies. -Container Signing, Verification and Storage in an OCI registry. - -[![Go Report Card](https://goreportcard.com/badge/github.com/sigstore/cosign)](https://goreportcard.com/report/github.com/sigstore/cosign) -[![e2e-tests](https://github.com/sigstore/cosign/actions/workflows/e2e_tests.yml/badge.svg)](https://github.com/sigstore/cosign/actions/workflows/e2e_tests.yml) -[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5715/badge)](https://bestpractices.coreinfrastructure.org/projects/5715) - -Cosign aims to make signatures **invisible infrastructure**. - -Cosign supports: - -* Hardware and KMS signing -* Bring-your-own PKI -* Our free OIDC PKI ([Fulcio](https://github.com/sigstore/fulcio)) -* Built-in binary transparency and timestamping service ([Rekor](https://github.com/sigstore/rekor)) - -![intro](images/intro.gif) - -## Info - -`Cosign` is developed as part of the [`sigstore`](https://sigstore.dev) project. -We also use a [slack channel](https://sigstore.slack.com)! -Click [here](https://join.slack.com/t/sigstore/shared_invite/zt-mhs55zh0-XmY3bcfWn4XEyMqUUutbUQ) for the invite link. - -## Installation - -For Homebrew, Arch, Nix, GitHub Action, and Kubernetes installs see the [installation docs](https://docs.sigstore.dev/cosign/installation). - -For Linux and macOS binaries see the [GitHub release assets](https://github.com/sigstore/cosign/releases/latest). - -## Developer Installation - -If you have Go 1.17+, you can setup a development environment: - - $ git clone https://github.com/sigstore/cosign - $ cd cosign - $ go install ./cmd/cosign - $ $(go env GOPATH)/bin/cosign - -## Quick Start - -This shows how to: - -* generate a keypair -* sign a container image and store that signature in the registry -* find signatures for a container image, and verify them against a public key - -See the [Usage documentation](USAGE.md) for more commands! - -See the [FUN.md](FUN.md) documentation for some fun tips and tricks! - -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. - -### Generate a keypair - -```shell -$ cosign generate-key-pair -Enter password for private key: -Enter again: -Private key written to cosign.key -Public key written to cosign.pub -``` - -### Sign a container and store the signature in the registry - -```shell -$ cosign sign --key cosign.key dlorenc/demo -Enter password for private key: -Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig -``` - -The cosign command above prompts the user to enter the password for the private key. -The user can either manually enter the password, or if the environment variable `COSIGN_PASSWORD` is set then it is used automatically. - - -### Verify a container against a public key - -This command returns `0` if *at least one* `cosign` formatted signature for the image is found -matching the public key. -See the detailed usage below for information and caveats on other signature formats. - -Any valid payloads are printed to stdout, in json format. -Note that these signed payloads include the digest of the container image, which is how we can be -sure these "detached" signatures cover the correct image. - -```shell -$ cosign verify --key cosign.pub dlorenc/demo -The following checks were performed on these signatures: - - The cosign claims were validated - - The signatures were verified against the specified public key -{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null} -``` - -## `Cosign` is 1.0! - -This means the core feature set of `cosign` is considered ready for production use. -This core set includes: - -### Key Management - -* fixed, text-based keys generated using `cosign generate-key-pair` -* cloud KMS-based keys generated using `cosign generate-key-pair -kms` -* keys generated on hardware tokens using the PIV interface using `cosign piv-tool` -* Kubernetes-secret based keys generated using `cosign generate-key-pair k8s://namespace/secretName` - -### Artifact Types - -* OCI and Docker Images -* Other artifacts that can be stored in a container registry, including: - * Tekton Bundles - * Helm Charts - * WASM modules - * eBPF modules - * (probably anything else, feel free to add things to this list) -* Text files and other binary blobs, using `cosign sign-blob` - -### What ** is not ** production ready? - -While parts of `cosign` are stable, we are continuing to experiment and add new features. -The following feature set is not considered stable yet, but we are committed to stabilizing it over time! - -#### Anything under the `COSIGN_EXPERIMENTAL` environment variable - -* Integration with the `Rekor` transparency log -* Keyless signatures using the `Fulcio` CA - -#### Formats/Specifications - -While the `cosign` code for uploading, signing, retrieving, and verifying several artifact types is stable, -the format specifications for some of those types may not be considered stable yet. -Some of these are developed outside of the `cosign` project, so we are waiting for them to stabilize first. - -These include: - -* The SBOM specification for storing SBOMs in a container registry -* The In-Toto attestation format - -## Working with Other Artifacts - -OCI registries are useful for storing more than just container images! -`Cosign` also includes some utilities for publishing generic artifacts, including binaries, scripts, and configuration files using the OCI protocol. - -This section shows how to leverage these for an easy-to-use, backwards-compatible artifact distribution system that integrates well with the rest of Sigstore. - -### Blobs - -You can publish an artifact with `cosign upload blob`: - -```shell -$ echo "my first artifact" > artifact -$ cosign upload blob -f artifact gcr.io/dlorenc-vmtest2/artifact -Uploading file from [artifact] to [gcr.io/dlorenc-vmtest2/artifact:latest] with media type [text/plain; charset=utf-8] -File is available directly at [us.gcr.io/v2/dlorenc-vmtest2/readme/blobs/sha256:b57400c0ad852a7c2f6f7da4a1f94547692c61f3e921a49ba3a41805ae8e1e99] -us.gcr.io/dlorenc-vmtest2/readme@sha256:4aa3054270f7a70b4528f2064ee90961788e1e1518703592ae4463de3b889dec -``` - -Your users can download it from the "direct" url with standard tools like curl or wget: - -```shell -$ curl -L gcr.io/v2/dlorenc-vmtest2/artifact/blobs/sha256:97f16c28f6478f3c02d7fff4c7f3c2a30041b72eb6852ca85b919fd85534ed4b > artifact -``` - -The digest is baked right into the URL, so they can check that as well: - -```shell -$ curl -L gcr.io/v2/dlorenc-vmtest2/artifact/blobs/sha256:97f16c28f6478f3c02d7fff4c7f3c2a30041b72eb6852ca85b919fd85534ed4b | shasum -a 256 -97f16c28f6478f3c02d7fff4c7f3c2a30041b72eb6852ca85b919fd85534ed4b - -``` - -You can sign it with the normal `cosign sign` command and flags: - -```shell -$ cosign sign --key cosign.key gcr.io/dlorenc-vmtest2/artifact -Enter password for private key: -Pushing signature to: gcr.io/dlorenc-vmtest2/artifact:sha256-3f612a4520b2c245d620d0cca029f1173f6bea76819dde8543f5b799ea3c696c.sig -``` -#### sget - -We also include the `sget` command for safer, automatic verification of signatures and integration with our binary transparency log, Rekor. - -To install `sget`, if you have Go 1.16+, you can directly run: - - $ go install github.com/sigstore/cosign/cmd/sget@latest - -and the resulting binary will be placed at `$GOPATH/bin/sget` (or `$GOBIN/sget`, if set). - -Just like `curl`, `sget` can be used to fetch artifacts by digest using the OCI URL. -Digest verification is automatic: - -```shell -$ sget us.gcr.io/dlorenc-vmtest2/readme@sha256:4aa3054270f7a70b4528f2064ee90961788e1e1518703592ae4463de3b889dec > artifact -``` - -You can also use `sget` to fetch contents by tag. -Fetching contents without verifying them is dangerous, so we require the artifact be signed in this case: - -```shell -$ sget gcr.io/dlorenc-vmtest2/artifact -error: public key must be specified when fetching by tag, you must fetch by digest or supply a public key - -$ sget --key cosign.pub us.gcr.io/dlorenc-vmtest2/readme > foo - -Verification for us.gcr.io/dlorenc-vmtest2/readme -- -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 - - The signatures were verified against the specified public key - - Any certificates were verified against the Fulcio roots. -``` - -The signature, claims and transparency log proofs are all verified automatically by sget as part of the download. - -`curl | bash` isn't a great idea, but `sget | bash` is less-bad. - -#### Tekton Bundles - -[Tekton](https://tekton.dev) bundles can be uploaded and managed within an OCI registry. -The specification is [here](https://tekton.dev/docs/pipelines/tekton-bundle-contracts/). -This means they can also be signed and verified with `cosign`. - -Tekton Bundles can currently be uploaded with the [tkn cli](https://github.com/tektoncd/cli), but we may add this support to -`cosign` in the future. - -```shell -$ tkn bundle push us.gcr.io/dlorenc-vmtest2/pipeline:latest -f task-output-image.yaml -Creating Tekton Bundle: - - Added TaskRun: to image - -Pushed Tekton Bundle to us.gcr.io/dlorenc-vmtest2/pipeline@sha256:124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155 -$ cosign sign --key cosign.key us.gcr.io/dlorenc-vmtest2/pipeline:latest -Enter password for private key: -tlog entry created with index: 5086 -Pushing signature to: us.gcr.io/dlorenc-vmtest2/demo:sha256-124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155.sig -``` - -#### WASM - -Web Assembly Modules can also be stored in an OCI registry, using this [specification](https://github.com/solo-io/wasm/tree/master/spec). - -Cosign can upload these using the `cosign wasm upload` command: - -```shell -$ cosign upload wasm -f hello.wasm us.gcr.io/dlorenc-vmtest2/wasm -$ cosign sign --key cosign.key us.gcr.io/dlorenc-vmtest2/wasm -Enter password for private key: -tlog entry created with index: 5198 -Pushing signature to: us.gcr.io/dlorenc-vmtest2/wasm:sha256-9e7a511fb3130ee4641baf1adc0400bed674d4afc3f1b81bb581c3c8f613f812.sig -``` -#### eBPF - -[eBPF](https://ebpf.io) modules can also be stored in an OCI registry, using this [specification](https://github.com/solo-io/bumblebee/tree/main/spec). - -The image below was built using the `bee` tool. More information can be found [here](https://github.com/solo-io/bumblebee/) - -Cosign can then sign these images as they can any other OCI image. - -```shell -$ bee build ./examples/tcpconnect/tcpconnect.c localhost:5000/tcpconnect:test -$ bee push localhost:5000/tcpconnect:test -$ cosign sign --key cosign.key localhost:5000/tcpconnect:test -Enter password for private key: -Pushing signature to: localhost:5000/tcpconnect -$ cosign verify --key cosign.pub localhost:5000/tcpconnect:test -cosign verify --key pubkey.pem localhost:5001/tcpconnect:test - -Verification for localhost:5000/tcpconnect:test -- -The following checks were performed on each of these signatures: - - The cosign claims were validated - - The signatures were verified against the specified public key - -[{"critical":{"identity":{"docker-reference":"localhost:5000/tcpconnect"},"image":{"docker-manifest-digest":"sha256:7a91c50d922925f152fec96ed1d84b7bc6b2079c169d68826f6cf307f22d40e6"},"type":"cosign container image signature"},"optional":null}] - -``` - -#### In-Toto Attestations - -Cosign also has built-in support for [in-toto](https://in-toto.io) attestations. -The specification for these is defined [here](https://github.com/in-toto/attestation). - -You can create and sign one from a local predicate file using the following commands: - -```shell -$ cosign attest --predicate --key cosign.key -``` - -All of the standard key management systems are supported. -Payloads are signed using the DSSE signing spec, defined [here](https://github.com/secure-systems-lab/dsse). - -To verify: - -```shell -$ cosign verify-attestation --key cosign.pub -``` - -## Detailed Usage - -See the [Usage documentation](USAGE.md) for more commands! - -## Hardware-based Tokens - -See the [Hardware Tokens documentation](TOKENS.md) for information on how to use `cosign` with hardware. - -## Keyless - -🚨 🚨 🚨 See [here](KEYLESS.md) for info on the experimental Keyless signatures mode. 🚨 🚨 🚨 - -## Registry Support - -`cosign` uses [go-containerregistry](https://github.com/google/go-containerregistry) for registry -interactions, which has generally excellent compatibility, but some registries may have quirks. - -Today, `cosign` has been tested and works against the following registries: - -* AWS Elastic Container Registry -* GCP's Artifact Registry and Container Registry -* Docker Hub -* Azure Container Registry -* JFrog Artifactory Container Registry -* The CNCF distribution/distribution Registry -* GitLab Container Registry -* GitHub Container Registry -* The CNCF Harbor Registry -* Digital Ocean Container Registry -* Sonatype Nexus Container Registry -* Alibaba Cloud Container Registry -* Red Hat Quay Container Registry 3.6+ / Red Hat quay.io -* Elastic Container Registry -* IBM Cloud Container Registry -* Cloudsmith Container Registry - -We aim for wide registry support. To `sign` images in registries which do not yet fully support [OCI media types](https://github.com/sigstore/cosign/blob/main/SPEC.md#object-types), one may need to use `COSIGN_DOCKER_MEDIA_TYPES` to fall back to legacy equivalents. For example: -```shell -COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example.com/my/image -``` - -Please help test and file bugs if you see issues! -Instructions can be found in the [tracking issue](https://github.com/sigstore/cosign/issues/40). - -## Rekor Support -_Note: this is an experimental feature_ - -To publish signed artifacts to a Rekor transparency log and verify their existence in the log -set the `COSIGN_EXPERIMENTAL=1` environment variable. - -```shell -$ COSIGN_EXPERIMENTAL=1 cosign sign --key cosign.key dlorenc/demo -$ COSIGN_EXPERIMENTAL=1 cosign verify --key cosign.pub dlorenc/demo -``` - -`cosign` defaults to using the public instance of rekor at [rekor.sigstore.dev](https://rekor.sigstore.dev). -To configure the rekor server, use the -`rekor-url` flag - -## Caveats - -### Intentionally Missing Features - -`cosign` only generates ECDSA-P256 keys and uses SHA256 hashes. -Keys are stored in PEM-encoded PKCS8 format. -However, you can use `cosign` to store and retrieve signatures in any format, from any algorithm. - -### Unintentionally Missing Features - -`cosign` will integrate with transparency logs! -See https://github.com/sigstore/cosign/issues/34 for more info. - -`cosign` will integrate with even more transparency logs, and a PKI. -See https://github.com/sigStore/fulcio for more info. - -`cosign` will also support The Update Framework for delegations, key discovery and expiration. -See https://github.com/sigstore/cosign/issues/86 for more info! - -### Things That Should Probably Change - -#### Payload Formats - -`cosign` only supports Red Hat's [simple signing](https://www.redhat.com/en/blog/container-image-signing) -format for payloads. -That looks like: - -```json -{ - "critical": { - "identity": { - "docker-reference": "testing/manifest" - }, - "image": { - "Docker-manifest-digest": "sha256:20be...fe55" - }, - "type": "cosign container image signature" - }, - "optional": { - "creator": "Bob the Builder", - "timestamp": 1458239713 - } -} -``` -**Note:** This can be generated for an image reference using `cosign generate `. - -I'm happy to switch this format to something else if it makes sense. -See https://github.com/notaryproject/nv2/issues/40 for one option. - - -#### Registry Details - -`cosign` signatures are stored as separate objects in the OCI registry, with only a weak -reference back to the object they "sign". -This means this relationship is opaque to the registry, and signatures *will not* be deleted -or garbage-collected when the image is deleted. -Similarly, they **can** easily be copied from one environment to another, but this is not -automatic. - -Multiple signatures are stored in a list which is unfortunately a race condition today. -To add a signature, clients orchestrate a "read-append-write" operation, so the last write -will win in the case of contention. - -##### Specifying Registry -`cosign` will default to storing signatures in the same repo as the image it is signing. -To specify a different repo for signatures, you can set the `COSIGN_REPOSITORY` environment variable. - -This will replace the repo in the provided image like this: -``` -$ export COSIGN_REPOSITORY=gcr.io/my-new-repo -$ gcr.io/dlorenc-vmtest2/demo -> gcr.io/my-new-repo/demo:sha256-DIGEST.sig -``` -So the signature for `gcr.io/dlorenc-vmtest2/demo` will be stored in `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`. - - -## Signature Specification - -`cosign` is inspired by tools like [minisign](https://jedisct1.github.io/minisign/) and -[signify](https://www.openbsd.org/papers/bsdcan-signify.html). - -Generated private keys are stored in PEM format. -The keys encrypted under a password using scrypt as a KDF and nacl/secretbox for encryption. - -They have a PEM header of `ENCRYPTED COSIGN PRIVATE KEY`: - -``` ------BEGIN ENCRYPTED COSIGN PRIVATE KEY----- -... ------END ENCRYPTED COSIGN PRIVATE KEY----- -``` - -Public keys are stored on disk in PEM-encoded standard PKIX format with a header of `PUBLIC KEY`. -``` ------BEGIN PUBLIC KEY----- -MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELigCnlLNKgOglRTx1D7JhI7eRw99 -QolE9Jo4QUxnbMy5nUuBL+UZF9qqfm/Dg1BNeHRThHzWh2ki9vAEgWEDOw== ------END PUBLIC KEY----- -``` - -## Storage Specification - -`cosign` stores signatures in an OCI registry, and uses a naming convention (tag based -on the sha256 of what we're signing) for locating the signature index. - -

- -

- -`reg.example.com/ubuntu@sha256:703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715` has signatures located at `reg.example.com/ubuntu:sha256-703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715.sig` - -Roughly (ignoring ports in the hostname): `s/:/-/g` and `s/@/:/g` to find the signature index. - -See [Race conditions](#registry-details) for some caveats around this strategy. - -Alternative implementations could use transparency logs, local filesystem, a separate repository -registry, an explicit reference to a signature index, a new registry API, grafeas, etc. - -### Signing subjects - -`cosign` only works for artifacts stored as "manifests" in the registry today. -The proposed mechanism is flexible enough to support signing arbitrary things. - -### KMS Support - -`cosign` supports using a KMS provider to generate and sign keys. -Right now cosign supports Hashicorp Vault, AWS KMS, GCP KMS, Azure Key Vault and we are hoping to support more in the future! - -See the [KMS docs](KMS.md) for more details. - -### OCI Artifacts - -Push an artifact to a registry using [oras](https://github.com/deislabs/oras) (in this case, `cosign` itself!): - -```shell -$ oras push us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact ./cosign -Uploading f53604826795 cosign -Pushed us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact -Digest: sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef -``` - -Now sign it! Using `cosign` of course: - -```shell -$ cosign sign --key cosign.key us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact@sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef -Enter password for private key: -Pushing signature to: us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact:sha256-551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef.sig -``` - -Finally, verify `cosign` with `cosign` again: - -```shell -$ cosign verify --key cosign.pub us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact@sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef -The following checks were performed on each of these signatures: - - The cosign claims were validated - - The claims were present in the transparency log - - The signatures were integrated into the transparency log when the certificate was valid - - The signatures were verified against the specified public key - - Any certificates were verified against the Fulcio roots. - -{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef"},"Type":"cosign container image signature"},"Optional":null} -``` - -## FAQ - -### Why not use Notary v2 - -It's hard to answer this briefly. -This post contains some comparisons: - -[Notary V2 and Cosign](https://medium.com/@dlorenc/notary-v2-and-cosign-b816658f044d) - -If you find other comparison posts, please send a PR here and we'll link them all. - -### Why not use containers/image signing - -`containers/image` signing is close to `cosign`, and we reuse payload formats. -`cosign` differs in that it signs with ECDSA-P256 keys instead of PGP, and stores -signatures in the registry. - -### Why not use TUF? - -I believe this tool is complementary to TUF, and they can be used together. -I haven't tried yet, but think we can also reuse a registry for TUF storage. - -### Why not use Blockchain? - -Just kidding. Nobody actually asked this. Don't be that person. - -### Why not use $FOO? - -See the next section, [Requirements](#Requirements). -I designed this tool to meet a few specific requirements, and didn't find -anything else that met all of these. -If you're aware of another system that does meet these, please let me know! - -## Design Requirements - -* No external services for signature storage, querying, or retrieval -* We aim for as much registry support as possible -* Everything should work over the registry API -* PGP should not be required at all. -* Users must be able to find all signatures for an image -* Signers can sign an image after push -* Multiple entities can sign an image -* Signing an image does not mutate the image -* Pure-go implementation - -## Future Ideas - -### Registry API Changes - -The naming convention and read-modify-write update patterns we use to store things in -a registry are a bit, well, "hacky". -I think they're the best (only) real option available today, but if the registry API -changes we can improve these. - -### Other Types - -`cosign` can sign anything in a registry. -These examples show signing a single image, but you could also sign a multi-platform `Index`, -or any other type of artifact. -This includes Helm Charts, Tekton Pipelines, and anything else currently using OCI registries -for distribution. - -This also means new artifact types can be uploaded to a registry and signed. -One interesting type to store and sign would be TUF repositories. -I haven't tried yet, but I'm fairly certain TUF could be implemented on top of this. - -### Tag Signing - -`cosign` signatures protect the digests of objects stored in a registry. -The optional `annotations` support (via the `-a` flag to `cosign sign`) can be used to add extra -data to the payload that is signed and protected by the signature. -One use-case for this might be to sign a tag->digest mapping. - -If you would like to attest that a specific tag (or set of tags) should point at a digest, you can -run something like: - -```shell -$ TAG=sign-me -$ DGST=$(crane digest dlorenc/demo:$TAG) -$ cosign sign --key cosign.key -a tag=$TAG dlorenc/demo@$DGST -Enter password for private key: -Pushing signature to: dlorenc/demo:sha256-97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36.sig -``` - -Then you can verify that the tag->digest mapping is also covered in the signature, using the `-a` flag to `cosign verify`. -This example verifies that the digest `$TAG` points to (`sha256:97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36`) -has been signed, **and also** that the `$TAG`: - -```shell -$ cosign verify --key cosign.pub -a tag=$TAG dlorenc/demo:$TAG | jq . -{ - "Critical": { - "Identity": { - "docker-reference": "" - }, - "Image": { - "Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36" - }, - "Type": "cosign container image signature" - }, - "Optional": { - "tag": "sign-me" - } -} -``` - -Timestamps could also be added here, to implement TUF-style freeze-attack prevention. - -### Base Image/Layer Signing - -Again, `cosign` can sign anything in a registry. -You could use `cosign` to sign an image that is intended to be used as a base image, -and include that provenance metadata in resulting derived images. -This could be used to enforce that an image was built from an authorized base image. - -Rough Idea: -* OCI manifests have an ordered list of `layer` `Descriptors`, which can contain annotations. - See [here](https://github.com/opencontainers/image-spec/blob/master/manifest.md) for the - specification. -* A base image is an ordered list of layers to which other layers are appended, as well as an - initial configuration object that is mutated. - * A derived image is free to completely delete/destroy/recreate the config from its base image, - so signing the config would provided limited value. -* We can sign the full set of ordered base layers, and attach that signature as an annotation to - the **last** layer in the resulting child image. - -This example manifest manifest represents an image that has been built from a base image with two -layers. -One additional layer is added, forming the final image. - -```json -{ - "schemaVersion": 2, - "config": { - "mediaType": "application/vnd.oci.image.config.v1+json", - "size": 7023, - "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7" - }, - "layers": [ - { - "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", - "size": 32654, - "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0" - }, - { - "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", - "size": 16724, - "digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b", - "annotations": { - "dev.cosign.signature.baseimage": "Ejy6ipGJjUzMDoQFePWixqPBYF0iSnIvpMWps3mlcYNSEcRRZelL7GzimKXaMjxfhy5bshNGvDT5QoUJ0tqUAg==" - } - }, - { - "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", - "size": 73109, - "digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736" - } - ], -} -``` - -Note that this could be applied recursively, for multiple intermediate base images. - -### Counter-Signing - -Cosign signatures (and their protected payloads) are stored as artifacts in a registry. -These signature objects can also be signed, resulting in a new, "counter-signature" artifact. -This "counter-signature" protects the signature (or set of signatures) **and** the referenced artifact, which allows -it to act as an attestation to the **signature(s) themselves**. - -Before we sign the signature artifact, we first give it a memorable name so we can find it later. - -```shell -$ cosign sign --key cosign.key -a sig=original dlorenc/demo -Enter password for private key: -Pushing signature to: dlorenc/demo:sha256-97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36.sig -$ cosign verify --key cosign.pub dlorenc/demo | jq . -{ - "Critical": { - "Identity": { - "docker-reference": "" - }, - "Image": { - "Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36" - }, - "Type": "cosign container image signature" - }, - "Optional": { - "sig": "original" - } -} -``` - -Now give that signature a memorable name, then sign that: - -```shell -$ crane tag $(cosign triangulate dlorenc/demo) mysignature -2021/02/15 20:22:55 dlorenc/demo:mysignature: digest: sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e size: 556 -$ cosign sign --key cosign.key -a sig=counter dlorenc/demo:mysignature -Enter password for private key: -Pushing signature to: dlorenc/demo:sha256-71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e.sig -$ cosign verify --key cosign.pub dlorenc/demo:mysignature -{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e"},"Type":"cosign container image signature"},"Optional":{"sig":"counter"}} -``` - -Finally, check the original signature: - -```shell -$ crane manifest dlorenc/demo@sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e -{ - "schemaVersion": 2, - "config": { - "mediaType": "application/vnd.oci.image.config.v1+json", - "size": 233, - "digest": "sha256:3b25a088710d03f39be26629d22eb68cd277a01673b9cb461c4c24fbf8c81c89" - }, - "layers": [ - { - "mediaType": "application/vnd.oci.descriptor.v1+json", - "size": 217, - "digest": "sha256:0e79a356609f038089088ec46fd95f4649d04de989487220b1a0adbcc63fadae", - "annotations": { - "dev.sigstore.cosign/signature": "5uNZKEP9rm8zxAL0VVX7McMmyArzLqtxMTNPjPO2ns+5GJpBeXg+i9ILU+WjmGAKBCqiexTxzLC1/nkOzD4cDA==" - } - } - ] -} -``` +(TODO: vaikas) Update this README ## Security -Should you discover any security issues, please refer to sigstore's [security -process](https://github.com/sigstore/.github/blob/main/SECURITY.md) +Should you discover any security issues, please refer to sigstores [security +process](https://github.com/sigstore/community/blob/main/SECURITY.md) diff --git a/TOKENS.md b/TOKENS.md deleted file mode 100644 index 6ab13e255..000000000 --- a/TOKENS.md +++ /dev/null @@ -1,255 +0,0 @@ -# Hardware Tokens - -The `cosign` command line tool optionally supports hardware tokens for signing and key management. -This support is enabled through the [PIV protocol](https://csrc.nist.gov/projects/piv/piv-standards-and-supporting-documentation) -and the [go-piv](https://github.com/go-piv/piv-go) library, which is not included in the standard release. Use `make cosign-pivkey-pkcs11key`, or `go build -tags=pivkey,pkcs11key ./cmd/cosign`, to build `cosign` with support for hardware tokens. - ---- -**NOTE** - -`cosign`'s hardware token support requires `libpcsclite` on platforms other than Windows and OSX. -See [`go-piv`'s installation instructions for your platform.](https://github.com/go-piv/piv-go#installation) - ---- - -We recommend using an application provided by your hardware vendor to manage keys and permissions for advanced use-cases, but `cosign piv-tool` should work well for most users. - -## Quick Start - -### Setup - -To get started, insert a key to your computer and run the `cosign piv-tool generate-key` command. -We recommend using the `--random-management-key=true` flag. - -This command generates a cryptographically-random management key and configures the device to use it. -This management key is destroyed, requiring a hardware reset to modify the signing key (this can be done with the `cosign piv-tool reset` command). - -A signing key is generated on the hardware, and the resulting attestations are printed to stdout. -You do not need to save these, they can be retrieved later with the `cosign piv-tool attestation` command. - -```shell -$ cosign piv-tool generate-key --random-management-key -Resetting management key to random value. You must factory reset the device to change this value: y -Generating new signing key. This will destroy any previous keys.: y -Generated public key ------BEGIN PUBLIC KEY----- -MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEbZHvZgxjkqWlY865CPlmAqjLK6y -PhL+7MoxI3LLmO/gOhH8Q6elVcAZJgAUZY+GXlN0u1/TatI+sdw2DEQThw== ------END PUBLIC KEY----- - -Printing device attestation certificate ------BEGIN CERTIFICATE----- -MIIC+jCCAeKgAwIBAgIJAJDjrwcvIYiiMA0GCSqGSIb3DQEBCwUAMCsxKTAnBgNV -BAMMIFl1YmljbyBQSVYgUm9vdCBDQSBTZXJpYWwgMjYzNzUxMCAXDTE2MDMxNDAw -MDAwMFoYDzIwNTIwNDE3MDAwMDAwWjAhMR8wHQYDVQQDDBZZdWJpY28gUElWIEF0 -dGVzdGF0aW9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyS4ANsMp -RQA9cigP1oUG8yQ8tQkel2IergXvY9WSYy/muj30exFWXvO323i9RaQtoT7hOS5d -SsH1hNvSTD56fIaKpg+8jHsQLM6mF2Jo0Kb4rBduYNi+waFbGcwgrmRX1d9NcYb6 -UDJt0o0RW6aGPY6wqUvMlIj0EwNIN7Ct1wSjIdL1qFmyVwUkQkPDd/0jDv7giE0P -M36qISQ6U8t2jNg5aWDEjf7wwWTIiMjbv0FaaiL5Vqmc7WboofKZN5nQyWGAtAtz -jTXzSkBfNPDO1eAUgbCbmu5efD8WeAtiPQyz8zQDU5UyihmDUEF1Dgr9/QMtQ5bd -Z+FkBTtBYFp4aQIDAQABoykwJzARBgorBgEEAYLECgMDBAMFAgYwEgYDVR0TAQH/ -BAgwBgEB/wIBADANBgkqhkiG9w0BAQsFAAOCAQEAQutaY0Wf/o2MPyRmsMM1QQuX -JI1ncaiDczWpFGj8YFUqlwLsEgYMzzGMrgPHIyE+CCgbYfyJu2mGU7goEHFq2/Ky -i8mjJtk/nVMF/m+dD7zbLvXPU0f9BKdpm1LUjC/YscvkFuI+sFrZvk8e1DAM49D5 -Dm3MsEw9KjGhhTSv8iMoz9QMN7O1ozfsLTkj5eJQFEzkeUtgPxoJVnJqd4JkqnhF -ZoN7tG+9N6wouG5pCzOJDgraGwow11UdcheQze2SVktYcRdWVgr86YBiYdfAzkLz -FN4tXEiGuQyX6gWKBdd91niHF27RIWNGuz6X9KzMwgJ374n2ld8BiLg9PU30xA== ------END CERTIFICATE----- - -Printing key attestation certificate ------BEGIN CERTIFICATE----- -MIICVTCCAT2gAwIBAgIQARbGLrd6RGhDODMN+neZczANBgkqhkiG9w0BAQsFADAh -MR8wHQYDVQQDDBZZdWJpY28gUElWIEF0dGVzdGF0aW9uMCAXDTE2MDMxNDAwMDAw -MFoYDzIwNTIwNDE3MDAwMDAwWjAlMSMwIQYDVQQDDBpZdWJpS2V5IFBJViBBdHRl -c3RhdGlvbiA5YzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBG2R72YMY5KlpWP -OuQj5ZgKoyyusj4S/uzKMSNyy5jv4DoR/EOnpVXAGSYAFGWPhl5TdLtf02rSPrHc -NgxEE4ejTjBMMBEGCisGAQQBgsQKAwMEAwUCBjAUBgorBgEEAYLECgMHBAYCBADH -kP4wEAYKKwYBBAGCxAoDCAQCAwIwDwYKKwYBBAGCxAoDCQQBAzANBgkqhkiG9w0B -AQsFAAOCAQEAesDBFM7J67HCaJ6YzF2Ztz9UwQWVVid9AXG0b3rTdDBUAm85I+9a -zr8kS/adx2DKXQwQ2XTkSh4uMd4vVXMPr/MCiVzKzVnCgel1Fv97OaozpEicnTTn -0/cvf6NSdFeRDL06NBphp3gdWEkvuTb0LmCKnCldKbtGllK6yfZ/kVZexdnUrFIi -Hy45LclHKHKe3nveDD1WuGCpSABrxkx/BL/BNHB1y/gwiPHBFX+RShAtHwlW8uDK -g/8KdqKm021Eq/NJ+3WxINbRLFgYx8b+jTc7TE6ASNSNnbeG9UYlJ8kzfVII6C/4 -H0RutMyJMyduyT5c8F3OmDY5FDdX1F1VRQ== ------END CERTIFICATE----- - -Verifying certificates... -Verified ok - -Device info: - Issuer: CN=Yubico PIV Root CA Serial 263751 - Form factor: unknown: 0 - PIN Policy: Always - Serial number: 10550341 - Version: 4.4.5 -``` - -### Signing - -You can then use the normal `cosign` commands to sign images and blobs with your security key and PIN. -**NOTE**: The default PIN is `123456`. - -```shell -$ cosign sign --sk gcr.io/dlorenc-vmtest2/demo -Enter PIN for security key: -Please tap security key... -Pushing signature to: gcr.io/dlorenc-vmtest2/demo:sha256-410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd.sig -``` - -To verify, you can either use the hardware key directly: - -```shell -$ cosign verify --sk gcr.io/dlorenc-vmtest2/demo - -Verification for gcr.io/dlorenc-vmtest2/demo -- -The following checks were performed on each of these signatures: - - The cosign claims were validated - - The signatures were verified against the specified public key - - Any certificates were verified against the Fulcio roots. - -[{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}] -``` - -Or export the public key and verify against that: - -```shell -$ cosign public-key --sk > pub.key - -$ cosign verify --key pub.key gcr.io/dlorenc-vmtest2/demo - -Verification for gcr.io/dlorenc-vmtest2/demo -- -The following checks were performed on each of these signatures: - - The cosign claims were validated - - The signatures were verified against the specified public key - - Any certificates were verified against the Fulcio roots. - -[{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}] -``` - -## CLI Usage - -### Setup - -The `cosign piv-tool reset` command will restore your device to factory defaults. -This will **DESTROY** any keys on the device, you cannot recover them. - -The default management key, PIN and PUK will be configured after this command. - -The `cosign piv-tool generate-key` command is used to provision a key compatible with `cosign` and the rest of `sigstore`. -We recommend using the `--random-management-key=true` flag. - -### Access Control - -The management-key, PIN and PUK can all be configured with the `set-management-key`, `set-pin` and `set-puk` commands. -Leaving the `old-` flag empty will result in the default value being used. - -The PIN is used for signing, so you should set that to a value you can remember. -The PUK is used to reset the PIN in case you forget, without needing to regenerate the signing key. - -We recommend configuring these after the initial setup and key generation. - -## Tested Devices - -This set of commands has been tested against the following hardware: - -* YubiKey 5C -* YuibiKey 5C Nano FIPS -* YubiKey 4 Series - -**Note**: We aim to expand this list. -If you have hardware and can test it out, please send a PR with your results! - -Tests can be run against a device with the following command. -**WARNING**: These tests will destroy any keys on your device. - -```shell -$ go test ./test -tags=resetyubikey,e2e -count=1 -``` - -**WARNING**: These tests will destroy any keys on your device. - -## Attestations - -There are two attestations available from the hardware key. -The first is the device attestation. -This can be used to verify the hardware is authentic and came from the manufacturer. -To verify this, retrieve the manufacturers CA. -See [here](https://developers.yubico.com/yubico-piv-tool/Attestation.html) for instructions from Yubico. - -This certificate can be validated with `openssl` or other tooling: - -```shell -# Obtained from https://developers.yubico.com/PIV/Introduction/piv-attestation-ca.pem -$ echo '-----BEGIN CERTIFICATE----- -MIIDFzCCAf+gAwIBAgIDBAZHMA0GCSqGSIb3DQEBCwUAMCsxKTAnBgNVBAMMIFl1 -YmljbyBQSVYgUm9vdCBDQSBTZXJpYWwgMjYzNzUxMCAXDTE2MDMxNDAwMDAwMFoY -DzIwNTIwNDE3MDAwMDAwWjArMSkwJwYDVQQDDCBZdWJpY28gUElWIFJvb3QgQ0Eg -U2VyaWFsIDI2Mzc1MTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMN2 -cMTNR6YCdcTFRxuPy31PabRn5m6pJ+nSE0HRWpoaM8fc8wHC+Tmb98jmNvhWNE2E -ilU85uYKfEFP9d6Q2GmytqBnxZsAa3KqZiCCx2LwQ4iYEOb1llgotVr/whEpdVOq -joU0P5e1j1y7OfwOvky/+AXIN/9Xp0VFlYRk2tQ9GcdYKDmqU+db9iKwpAzid4oH -BVLIhmD3pvkWaRA2H3DA9t7H/HNq5v3OiO1jyLZeKqZoMbPObrxqDg+9fOdShzgf -wCqgT3XVmTeiwvBSTctyi9mHQfYd2DwkaqxRnLbNVyK9zl+DzjSGp9IhVPiVtGet -X02dxhQnGS7K6BO0Qe8CAwEAAaNCMEAwHQYDVR0OBBYEFMpfyvLEojGc6SJf8ez0 -1d8Cv4O/MA8GA1UdEwQIMAYBAf8CAQEwDgYDVR0PAQH/BAQDAgEGMA0GCSqGSIb3 -DQEBCwUAA4IBAQBc7Ih8Bc1fkC+FyN1fhjWioBCMr3vjneh7MLbA6kSoyWF70N3s -XhbXvT4eRh0hvxqvMZNjPU/VlRn6gLVtoEikDLrYFXN6Hh6Wmyy1GTnspnOvMvz2 -lLKuym9KYdYLDgnj3BeAvzIhVzzYSeU77/Cupofj093OuAswW0jYvXsGTyix6B3d -bW5yWvyS9zNXaqGaUmP3U9/b6DlHdDogMLu3VLpBB9bm5bjaKWWJYgWltCVgUbFq -Fqyi4+JE014cSgR57Jcu3dZiehB6UtAPgad9L5cNvua/IWRmm+ANy3O2LH++Pyl8 -SREzU8onbBsjMg9QDiSf5oJLKvd/Ren+zGY7 ------END CERTIFICATE-----' > yubico.crt - -# Obtained from "cosign piv-tool attestation" (the first certificate) -$ echo '-----BEGIN CERTIFICATE----- -MIIC+jCCAeKgAwIBAgIJAJDjrwcvIYiiMA0GCSqGSIb3DQEBCwUAMCsxKTAnBgNV -BAMMIFl1YmljbyBQSVYgUm9vdCBDQSBTZXJpYWwgMjYzNzUxMCAXDTE2MDMxNDAw -MDAwMFoYDzIwNTIwNDE3MDAwMDAwWjAhMR8wHQYDVQQDDBZZdWJpY28gUElWIEF0 -dGVzdGF0aW9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyS4ANsMp -RQA9cigP1oUG8yQ8tQkel2IergXvY9WSYy/muj30exFWXvO323i9RaQtoT7hOS5d -SsH1hNvSTD56fIaKpg+8jHsQLM6mF2Jo0Kb4rBduYNi+waFbGcwgrmRX1d9NcYb6 -UDJt0o0RW6aGPY6wqUvMlIj0EwNIN7Ct1wSjIdL1qFmyVwUkQkPDd/0jDv7giE0P -M36qISQ6U8t2jNg5aWDEjf7wwWTIiMjbv0FaaiL5Vqmc7WboofKZN5nQyWGAtAtz -jTXzSkBfNPDO1eAUgbCbmu5efD8WeAtiPQyz8zQDU5UyihmDUEF1Dgr9/QMtQ5bd -Z+FkBTtBYFp4aQIDAQABoykwJzARBgorBgEEAYLECgMDBAMFAgYwEgYDVR0TAQH/ -BAgwBgEB/wIBADANBgkqhkiG9w0BAQsFAAOCAQEAQutaY0Wf/o2MPyRmsMM1QQuX -JI1ncaiDczWpFGj8YFUqlwLsEgYMzzGMrgPHIyE+CCgbYfyJu2mGU7goEHFq2/Ky -i8mjJtk/nVMF/m+dD7zbLvXPU0f9BKdpm1LUjC/YscvkFuI+sFrZvk8e1DAM49D5 -Dm3MsEw9KjGhhTSv8iMoz9QMN7O1ozfsLTkj5eJQFEzkeUtgPxoJVnJqd4JkqnhF -ZoN7tG+9N6wouG5pCzOJDgraGwow11UdcheQze2SVktYcRdWVgr86YBiYdfAzkLz -FN4tXEiGuQyX6gWKBdd91niHF27RIWNGuz6X9KzMwgJ374n2ld8BiLg9PU30xA== ------END CERTIFICATE-----' > device.crt - -$ openssl verify -CAfile yubico.crt device.crt -device.crt: OK -``` - -The key attestation can be used to verify that the signing key was generated on the device, not loaded from an external source. - -This can be verified against the device attestation cert, which forms a chain back to the manufacturer. - -```shell -# Use the same crt files from the previous step, create the CA chain -$ cat yubico.crt device.crt > chain.pem - -# This cert was obtained from "cosign piv-tool attestation", the second cert -$ echo '-----BEGIN CERTIFICATE----- -MIICVTCCAT2gAwIBAgIQARF+TvIOm46Oc+FF3+YHITANBgkqhkiG9w0BAQsFADAh -MR8wHQYDVQQDDBZZdWJpY28gUElWIEF0dGVzdGF0aW9uMCAXDTE2MDMxNDAwMDAw -MFoYDzIwNTIwNDE3MDAwMDAwWjAlMSMwIQYDVQQDDBpZdWJpS2V5IFBJViBBdHRl -c3RhdGlvbiA5YzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBG2R72YMY5KlpWP -OuQj5ZgKoyyusj4S/uzKMSNyy5jv4DoR/EOnpVXAGSYAFGWPhl5TdLtf02rSPrHc -NgxEE4ejTjBMMBEGCisGAQQBgsQKAwMEAwUCBjAUBgorBgEEAYLECgMHBAYCBADH -kP4wEAYKKwYBBAGCxAoDCAQCAwIwDwYKKwYBBAGCxAoDCQQBAzANBgkqhkiG9w0B -AQsFAAOCAQEAeT5EXMm1PfVImtFinOPUsVY4tq2mPaZQ67//OiPisuSaF90YJIRJ -PyndeKHDpscFwN1h8XhACb6e6XAyswB//qMdt+2VEeJCFatcuUHki4Vb8plRkZNU -IDTbnZ3TnqY9eH4POmbHS9MmsDJPBFqCAvbX4hgHOiYmpim2tf4U562LMzpYU44c -rb9ZMlAhjlOHgft02Gduv2DK1THfUacMYR1L0p9WgCaRKAlAWsvyl3Xmfjf3NRJT -gzHKg/sREq1fns6kff5rj0kqZhuuhSYfOrhS3pRbMOEcKksymBwYbQpEgJYJndwO -uCPMJZqsNyWMmfksjulR9XAQvBCImkXncw== ------END CERTIFICATE-----' > key.crt - -$ openssl verify -CAfile chain.pem key.crt -key.crt: OK -``` diff --git a/USAGE.md b/USAGE.md deleted file mode 100644 index 26e5c8589..000000000 --- a/USAGE.md +++ /dev/null @@ -1,258 +0,0 @@ -# Detailed Usage - -## Sign a container multiple times - -Multiple signatures can be "attached" to a single container image: - -```shell -$ cosign sign --key cosign.key dlorenc/demo -Enter password for private key: -Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig - -$ cosign sign --key other.key dlorenc/demo -Enter password for private key: -Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig -``` - -We only actually sign the digest, but you can pass by tag or digest. - -The `-a` flag can be used to add annotations to the generated, signed payload. -This flag can be repeated: - -```shell -$ cosign sign --key other.key -a foo=bar dlorenc/demo -Enter password for private key: -Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig -``` - -These values are included in the signed payload under the `Optional` section. -(More on this later): - -```json -"Optional":{"baz":"bat","foo":"bar"} -``` - -they can be verified with the `-a` flag to `cosign verify`. - -## Sign and upload a generated payload (in another format, from another tool) - -The payload must be specified as a path to a file: - -```shell -$ cosign sign --key cosign.key --payload README.md dlorenc/demo -Using payload from: README.md -Enter password for private key: -Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig -``` - -## Signature Location and Management - -Signatures are uploaded to an OCI artifact stored with a predictable name. -This name can be located with the `cosign triangulate` command: - -```shell -cosign triangulate dlorenc/demo -index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig -``` - -They can be viewed with `crane`: - -```shell -crane manifest $(cosign triangulate gcr.io/dlorenc-vmtest2/demo) | jq . -{ - "schemaVersion": 2, - "mediaType": "application/vnd.docker.distribution.manifest.v2+json", - "config": { - "mediaType": "application/vnd.docker.container.image.v1+json", - "size": 342, - "digest": "sha256:f5de0db6e714055d48b4bb3a374e9630c4923fa704d9311da6a2740cf625aaba" - }, - "layers": [ - { - "mediaType": "application/vnd.dev.cosign.simplesigning.v1+json", - "size": 210, - "digest": "sha256:1119abab63e605dcc281019bad0424744178b6f61ba57378701fe7391994c999", - "annotations": { - "dev.cosignproject.cosign/signature": "MEUCIG0ZmgqE3qTrHWp+HF9CrxsNH57Cck3cQI+zNNrUwSHfAiEAm+2eY/Z6ixQwjLbTraDN5ZB/P1Z5k/KwIoblry65r+s=" - } - }, - { - "mediaType": "application/vnd.dev.cosign.simplesigning.v1+json", - "size": 219, - "digest": "sha256:583246418c2afd5bfe29694793d07da37ffd552aadf8879b1d98047178b80398", - "annotations": { - "dev.cosignproject.cosign/signature": "MEUCIF/+szLKKA2q2+c86AXeWR7UeD5yYpW7p0waHordxNjhAiEAm5e+Hm7Jhv9JpSwHpTc6aGLSkL6/Acm/z+b8mhfGXqY=" - } - } - ] -} -``` - -Some registries support deletion too (DockerHub does not): - -```shell -$ cosign clean gcr.io/dlorenc-vmtest2/demo -``` - -## Sign but skip upload (to store somewhere else) - -The base64 encoded signature is printed to stdout. -This can be stored somewhere else. - -```shell -$ cosign sign --key key.pem --upload=false dlorenc/demo -Qr883oPOj0dj82PZ0d9mQ2lrdM0lbyLSXUkjt6ejrxtHxwe7bU6Gr27Sysgk1jagf1htO/gvkkg71oJiwWryCQ== -``` - -## Generate the signature payload (to sign with another tool) - -The json payload is printed to stdout: - -```shell -$ cosign generate dlorenc/demo -{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null} -``` - -This can be piped directly into openssl: - -```shell -$ cosign generate dlorenc/demo | openssl... -``` - -## Upload a generated signature - -The signature is passed via the `--signature` flag. -It can be a file: - -```shell -$ cosign attach signature --signature file.sig dlorenc/demo -Pushing signature to: dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig -``` - -the base64-encoded signature: - -```shell -$ cosign attach signature --signature Qr883oPOj0dj82PZ0d9mQ2lrdM0lbyLSXUkjt6ejrxtHxwe7bU6Gr27Sysgk1jagf1htO/gvkkg71oJiwWryCQ== dlorenc/demo -Pushing signature to: dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def.sig -``` - -or, `-` for stdin for chaining from other commands: - -```shell -$ cosign generate dlorenc/demo | openssl... | cosign attach signature --signature -- dlorenc/demo -Pushing signature to: dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def.sig -``` - -## Verifying claims - -**Important Note**: - -Signature payloads created by `cosign` included the digest of the container image they are attached to. -By default, `cosign` validates that this digest matches the container during `cosign verify`. - -If you are using other payload formats with `cosign`, you can use the `--check-claims=false` flag: - -```shell -$ cosign verify --check-claims=false --key cosign.pub dlorenc/demo -Warning: the following claims have not been verified: -{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null} -``` - -This will still verify the signature and payload against the supplied public key, but will not -verify any claims in the payload. - -Annotations made in the original signature (`cosign sign -a foo=bar`) are present under the `Optional` section of the payload: - -```shell -$ cosign verify --key cosign.pub dlorenc/demo | jq . -{ - "Critical": { - "Identity": { - "docker-reference": "" - }, - "Image": { - "Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36" - }, - "Type": "cosign container image signature" - }, - "Optional": { - "sig": "original" - } -} -``` - -These can be checked with matching `-a foo=bar` flags on `cosign verify`. -When using this flag, **every** specified key-value pair **must exist and match** in the verified payload. -The payload may contain other key-value pairs. - -```shell -# This works -$ cosign verify -a --key cosign.pub dlorenc/demo -{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36"},"Type":"cosign container image signature"},"Optional":{"sig":"original"}} - -# This works too -$ cosign verify -a sig=original --key cosign.pub dlorenc/demo -{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36"},"Type":"cosign container image signature"},"Optional":{"sig":"original"}} - -# This doesn't work -$ cosign verify -a sig=original -a=foo=bar --key cosign.pub dlorenc/demo -error: no matching claims: -invalid or missing annotation in claim: map[sig:original] -``` - -## Download the signatures to verify with another tool - -Each signature is printed to stdout in a json format: - -``` -$ cosign download signature us-central1-docker.pkg.dev/dlorenc-vmtest2/test/taskrun -{"Base64Signature":"Ejy6ipGJjUzMDoQFePWixqPBYF0iSnIvpMWps3mlcYNSEcRRZelL7GzimKXaMjxfhy5bshNGvDT5QoUJ0tqUAg==","Payload":"eyJDcml0aWNhbCI6eyJJZGVudGl0eSI6eyJkb2NrZXItcmVmZXJlbmNlIjoiIn0sIkltYWdlIjp7IkRvY2tlci1tYW5pZmVzdC1kaWdlc3QiOiI4N2VmNjBmNTU4YmFkNzliZWVhNjQyNWEzYjI4OTg5ZjAxZGQ0MTcxNjQxNTBhYjNiYWFiOThkY2JmMDRkZWY4In0sIlR5cGUiOiIifSwiT3B0aW9uYWwiOm51bGx9"} -``` - -## Retrieve the Public Key From a Private Key or KMS - - -KMS: -```shell -# Retrieve from Google Cloud KMS -$ cosign public-key --key gcpkms://projects/someproject/locations/us-central1/keyRings/foo/cryptoKeys/bug/versions/1 ------BEGIN PUBLIC KEY----- -MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgrKKtyws86/APoULh/zXk4LONqII -AcxvLtLEgRjRI4TKnMAXtIGp8K4X4CTWPEXMqSYZZUa2I1YvHyLLY2bEzA== ------END PUBLIC KEY----- - -# Retrieve from HashiCorp Vault -$ cosign public-key --key hashivault://transit ------BEGIN PUBLIC KEY----- -MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgrKKtyws86/APoULh/zXk4LONqII -AcxvLtLEgRjRI4TKnMAXtIGp8K4X4CTWPEXMqSYZZUa2I1YvHyLLY2bEzA== ------END PUBLIC KEY----- -``` - -Private Key: -```shell -$ ./cosign public-key --key cosign.key -Enter password for private key: ------BEGIN PUBLIC KEY----- -MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEjCxhhvb1KmIfe1J2ceT25kHepstb -IDYuTA0U1ri4F0CXXazLiftzGlyfse1No4orr8w1ZIchQ8TJlyCSaSuR0Q== ------END PUBLIC KEY----- -``` - -# Experimental Features - -## Verify a signature was added to the transparency log -There are two options for verifying a cosign signature was added to a transparency log: -1. Check the log to make sure the entry exists in the log -2. Use the `bundle` annotation on a cosign signature to verify an element was added to the log without hitting the log - -The cosign `bundle` annotation contains a Signed Entry Timestamp (SET), which is conceptually similar to an SCT in a Web PKI system. -The SET is a signed inclusion promise provided by the transparency log, which acts as a guarantee by the log that an element has been included in it. -The SET can be verified with the logs public key and used to prove that an element is in the log without actually checking the log itself. - -For more details on how the `bundle` annotation is formatted, see the cosign [spec](specs/SIGNATURE_SPEC.md). - -To verify the `bundle` annotation, follow these steps: -1. Marshal the `bundle` Payload into JSON -1. Canonicalize the payload by following RFC 8785 rules -1. Verify the canonicalized payload and signedEntryTimestamp against the transparency logs public key diff --git a/artifacthub-repo.yml b/artifacthub-repo.yml deleted file mode 100644 index 2199462d3..000000000 --- a/artifacthub-repo.yml +++ /dev/null @@ -1,21 +0,0 @@ -# -# Copyright 2022 The Sigstore Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -repositoryID: 0344601c-282a-4857-a852-d9207291ccfe -owners: - - name: cpanato - email: ctadeu@gmail.com - - name: dlorenc - email: lorenc.d@gmail.com