Skip to content

Commit

Permalink
Clean up READMEs (#3587)
Browse files Browse the repository at this point in the history
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 <hblauzvern@google.com>
  • Loading branch information
haydentherapper committed Mar 11, 2024
1 parent 16a3dda commit 8ba9a5e
Show file tree
Hide file tree
Showing 10 changed files with 12 additions and 87 deletions.
1 change: 0 additions & 1 deletion EXAMPLES.md

This file was deleted.

36 changes: 0 additions & 36 deletions FEATURES.md

This file was deleted.

6 changes: 0 additions & 6 deletions FUN.md

This file was deleted.

1 change: 0 additions & 1 deletion IMPORT.md

This file was deleted.

1 change: 0 additions & 1 deletion KEYLESS.md

This file was deleted.

1 change: 0 additions & 1 deletion KMS.md

This file was deleted.

1 change: 0 additions & 1 deletion PKCS11.md

This file was deleted.

50 changes: 12 additions & 38 deletions README.md
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`:
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
1 change: 0 additions & 1 deletion TOKENS.md

This file was deleted.

1 change: 0 additions & 1 deletion USAGE.md

This file was deleted.

0 comments on commit 8ba9a5e

Please sign in to comment.