From 8ba9a5ece353e37b0a86d89595f8c74e7b62b869 Mon Sep 17 00:00:00 2001 From: Hayden B Date: Sun, 10 Mar 2024 18:40:45 -0700 Subject: [PATCH] Clean up READMEs (#3587) Remove deprecated markdown files with only links to docs.sigstore.dev, clean up outdated data in README, remove FEATURES which is outdated Signed-off-by: Hayden B --- EXAMPLES.md | 1 - FEATURES.md | 36 ------------------------------------ FUN.md | 6 ------ IMPORT.md | 1 - KEYLESS.md | 1 - KMS.md | 1 - PKCS11.md | 1 - README.md | 50 ++++++++++++-------------------------------------- TOKENS.md | 1 - USAGE.md | 1 - 10 files changed, 12 insertions(+), 87 deletions(-) delete mode 100644 EXAMPLES.md delete mode 100644 FEATURES.md delete mode 100644 FUN.md delete mode 100644 IMPORT.md delete mode 100644 KEYLESS.md delete mode 100644 KMS.md delete mode 100644 PKCS11.md delete mode 100644 TOKENS.md delete mode 100644 USAGE.md diff --git a/EXAMPLES.md b/EXAMPLES.md deleted file mode 100644 index 73fbfb24e2d..00000000000 --- a/EXAMPLES.md +++ /dev/null @@ -1 +0,0 @@ -> Note of deprecation: This document has been migrated and merged into into [`sigstore/docs`](https://github.com/sigstore/docs/blob/main/content/en/signing/overview.md) as part of [documentation migration](https://github.com/sigstore/cosign/issues/822) and PR: https://github.com/sigstore/docs/pull/123. To view the live docs page, go to: https://docs.sigstore.dev/signing/overview/ diff --git a/FEATURES.md b/FEATURES.md deleted file mode 100644 index 232f5e3bd16..00000000000 --- 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 0537feb7a93..00000000000 --- 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 9a7d65c3804..00000000000 --- a/IMPORT.md +++ /dev/null @@ -1 +0,0 @@ -> Note of deprecation: This document has been migrated into [`sigstore/docs`](https://github.com/sigstore/docs/blob/main/content/en/key_management/import-keypair.md) as part of [documentation migration](https://github.com/sigstore/cosign/issues/822) and PR: https://github.com/sigstore/docs/pull/54. To view the live docs page, go to: https://docs.sigstore.dev/key_management/import-keypair/ diff --git a/KEYLESS.md b/KEYLESS.md deleted file mode 100644 index ac03452e773..00000000000 --- a/KEYLESS.md +++ /dev/null @@ -1 +0,0 @@ -> Note of deprecation: This document has been migrated into [`sigstore/docs`](https://github.com/sigstore/docs/blob/main/content/en/signing/overview.md) as part of [documentation migration](https://github.com/sigstore/cosign/issues/822) and PR: https://github.com/sigstore/docs/pull/56. To view the live docs page, go to: https://docs.sigstore.dev/signing/overview/ diff --git a/KMS.md b/KMS.md deleted file mode 100644 index 2aae238ae6d..00000000000 --- a/KMS.md +++ /dev/null @@ -1 +0,0 @@ -> Note of deprecation: This document has been migrated and merged into [`sigstore/docs`](https://github.com/sigstore/docs/blob/main/content/en/key_management/overview.md) as part of [documentation migration](https://github.com/sigstore/cosign/issues/822) and PR: https://github.com/sigstore/docs/pull/125. To view the live docs page, go to: https://docs.sigstore.dev/key_management/overview/ diff --git a/PKCS11.md b/PKCS11.md deleted file mode 100644 index 091ec3e3ab4..00000000000 --- a/PKCS11.md +++ /dev/null @@ -1 +0,0 @@ -> Note of deprecation: This document has been migrated into [`sigstore/docs`](https://github.com/sigstore/docs/blob/main/content/en/signing/pkcs11.md) as part of [documentation migration](https://github.com/sigstore/cosign/issues/822) and PR: https://github.com/sigstore/docs/pull/129. To view the live docs page, go to: https://docs.sigstore.dev/signing/pkcs11/ diff --git a/README.md b/README.md index fdd5ae4b46e..95f268d96c8 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ ENTRYPOINT [ "cosign" ] ## Quick Start This shows how to: -* sign a container image with the default "keyless signing" method (see [KEYLESS.md](./KEYLESS.md)) +* sign a container image with the default identity-based "keyless signing" method (see [the documentation for more information](https://docs.sigstore.dev/signing/overview/)) * verify the container image ### Sign a container and store the signature in the registry @@ -102,7 +102,7 @@ Cosign will then store the signature and certificate in the Rekor transparency l ### Verify a container -To verify the image, you'll need to pass in the expected certificate issuer and certificate subject via the `--certificate-identity` and `--certificate-oidc-issuer` flags: +To verify the image, you'll need to pass in the expected certificate subject and certificate issuer via the `--certificate-identity` and `--certificate-oidc-issuer` flags: ``` cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER @@ -179,6 +179,8 @@ OCI registries are useful for storing more than just container images! 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. +See [the documentation](https://docs.sigstore.dev/signing/other_types/) for more information. + ### Blobs You can publish an artifact with `cosign upload blob`: @@ -300,15 +302,11 @@ $ cosign verify-attestation --key cosign.pub $IMAGE_URI ## Detailed Usage -See the [Usage documentation](USAGE.md) for more commands! +See the [Usage documentation](https://docs.sigstore.dev/signing/overview/) for more information. ## 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. 🚨 🚨 🚨 +See the [Hardware Tokens documentation](https://docs.sigstore.dev/key_management/hardware-based-tokens/) for information on how to use `cosign` with hardware. ## Registry Support @@ -335,7 +333,7 @@ Today, `cosign` has been tested and works against the following registries: * Cloudsmith Container Registry * The CNCF zot 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: +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/specs/SIGNATURE_SPEC.md), 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@$DIGEST @@ -344,26 +342,14 @@ COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example 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). - ## Caveats ### Intentionally Missing Features -`cosign` only generates ECDSA-P256 keys and uses SHA256 hashes. +`cosign` only generates ECDSA-P256 keys and uses SHA256 hashes, for both ephemeral keyless signing and managed key signing. 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 @@ -493,7 +479,7 @@ The proposed mechanism is flexible enough to support signing arbitrary things. `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. +See the [KMS docs](https://docs.sigstore.dev/key_management/overview/) for more details. ### OCI Artifacts @@ -550,17 +536,6 @@ signatures in the registry. 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 @@ -764,10 +739,9 @@ $ crane manifest dlorenc/demo@sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa2 ## Release Cadence -We are intending to move to a monthly cadence for minor releases. -Minor releases will be published around the beginning of the month. -We may cut a patch release instead, if the changes are small enough not to warrant a minor release. -We will also cut patch releases periodically as needed to address bugs. +We cut releases as needed. Patch releases are cut to fix small bugs. Minor releases are +cut periodically when there are multiple bugs fixed or features added. Major releases +will be released when there are breaking features. ## Security diff --git a/TOKENS.md b/TOKENS.md deleted file mode 100644 index e43fb507e38..00000000000 --- a/TOKENS.md +++ /dev/null @@ -1 +0,0 @@ -> Note of deprecation: This document has been migrated into [`sigstore/docs`](https://github.com/sigstore/docs/blob/main/content/en/key_management/hardware-based-tokens.md) as part of [documentation migration](https://github.com/sigstore/cosign/issues/822) and PR: https://github.com/sigstore/docs/pull/128. To view the live docs page, go to: https://docs.sigstore.dev/key_management/hardware-based-tokens/ diff --git a/USAGE.md b/USAGE.md deleted file mode 100644 index 760fff1610d..00000000000 --- a/USAGE.md +++ /dev/null @@ -1 +0,0 @@ -> Note of deprecation: This document has been migrated and merged into [`sigstore/docs`](https://github.com/sigstore/docs/blob/main/content/en/signing/overview.md) as part of [documentation migration](https://github.com/sigstore/cosign/issues/822) and PR: https://github.com/sigstore/docs/pull/123. To view the live docs page, go to: https://docs.sigstore.dev/signing/overview/