From d25b64616ef89deff61e4c23796ad5082e59be34 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Sat, 24 Aug 2024 15:22:10 -0700 Subject: [PATCH 1/3] Reorganizing documentation ahead of including language client information. Quickstart surfaced to top level. Signing, verifying, key management, and system configuration nested under cosign category. Signed-off-by: hayleycd --- content/en/about/faq.md | 19 ++++++------- content/en/about/overview.md | 12 ++++---- content/en/about/threat-model.md | 2 +- content/en/cosign/_index.html | 9 ++++++ .../{ => cosign}/key_management/_index.html | 0 .../key_management/hardware-based-tokens.md | 2 +- .../key_management/import-keypair.md | 2 +- .../{ => cosign}/key_management/overview.md | 2 +- .../signing_with_self-managed_keys.md | 4 +-- content/en/{ => cosign}/signing/_index.html | 0 .../en/{ => cosign}/signing/git_support.md | 6 ++-- content/en/{ => cosign}/signing/gitsign.md | 6 ++-- .../en/{ => cosign}/signing/other_types.md | 0 content/en/{ => cosign}/signing/overview.md | 2 +- content/en/{ => cosign}/signing/pkcs11.md | 0 .../signing/signing_with_blobs.md | 4 +-- .../signing/signing_with_containers.md | 6 ++-- .../en/{ => cosign}/system_config/_index.html | 0 .../system_config/custom_components.md | 0 .../system_config/installation.md | 0 .../{ => cosign}/system_config/integration.md | 0 .../system_config/public_deployment.md | 0 .../system_config/registry_support.md | 0 .../system_config/specifications.md | 0 content/en/{ => cosign}/verifying/_index.html | 0 .../en/{ => cosign}/verifying/attestation.md | 0 .../en/{ => cosign}/verifying/inspecting.md | 0 .../en/{ => cosign}/verifying/timestamps.md | 0 content/en/{ => cosign}/verifying/verify.md | 4 +-- content/en/quickstart/_index.html | 11 ++++++++ .../quickstart-cosign.md} | 28 +++++++++++-------- layouts/_default/list.html | 2 -- 32 files changed, 72 insertions(+), 49 deletions(-) create mode 100644 content/en/cosign/_index.html rename content/en/{ => cosign}/key_management/_index.html (100%) rename content/en/{ => cosign}/key_management/hardware-based-tokens.md (99%) rename content/en/{ => cosign}/key_management/import-keypair.md (77%) rename content/en/{ => cosign}/key_management/overview.md (99%) rename content/en/{ => cosign}/key_management/signing_with_self-managed_keys.md (95%) rename content/en/{ => cosign}/signing/_index.html (100%) rename content/en/{ => cosign}/signing/git_support.md (94%) rename content/en/{ => cosign}/signing/gitsign.md (99%) rename content/en/{ => cosign}/signing/other_types.md (100%) rename content/en/{ => cosign}/signing/overview.md (98%) rename content/en/{ => cosign}/signing/pkcs11.md (100%) rename content/en/{ => cosign}/signing/signing_with_blobs.md (96%) rename content/en/{ => cosign}/signing/signing_with_containers.md (98%) rename content/en/{ => cosign}/system_config/_index.html (100%) rename content/en/{ => cosign}/system_config/custom_components.md (100%) rename content/en/{ => cosign}/system_config/installation.md (100%) rename content/en/{ => cosign}/system_config/integration.md (100%) rename content/en/{ => cosign}/system_config/public_deployment.md (100%) rename content/en/{ => cosign}/system_config/registry_support.md (100%) rename content/en/{ => cosign}/system_config/specifications.md (100%) rename content/en/{ => cosign}/verifying/_index.html (100%) rename content/en/{ => cosign}/verifying/attestation.md (100%) rename content/en/{ => cosign}/verifying/inspecting.md (100%) rename content/en/{ => cosign}/verifying/timestamps.md (100%) rename content/en/{ => cosign}/verifying/verify.md (97%) create mode 100644 content/en/quickstart/_index.html rename content/en/{signing/quickstart.md => quickstart/quickstart-cosign.md} (80%) diff --git a/content/en/about/faq.md b/content/en/about/faq.md index 5fa320b5..47dd76c4 100644 --- a/content/en/about/faq.md +++ b/content/en/about/faq.md @@ -6,12 +6,12 @@ title: Frequently asked questions weight: 35 --- -This FAQ is intended to go as in depth as possible for anyone using sigstore. +This FAQ is intended to go as in depth as possible for anyone using sigstore. ## General ### What security checks do you use internally? - + We’ve adopted a security disclosures and response policy to make sure we can responsibly handle critical issues. We have an initial Security Response Committee, who for each vulnerability reported will coordinate to create the fix and release, and communicate the process. You can read the [full policy on GitHub](https://github.com/sigstore/.github/blob/main/SECURITY.md). ### How does Sigstore integrate in-toto? @@ -91,7 +91,7 @@ The commit itself contains a signed digest of the user commit content (that is, the author, committer, message, etc.) along with the code signing certificate. This data is stored within the commit itself as part of your repository. Review guidance on -[inspecting the Git commit signature]({{< relref "verifying/inspecting">}}) for +[inspecting the Git commit signature]({{< relref "cosign/verifying/inspecting">}}) for more details. #### 2. Within the Rekor transparency log @@ -121,17 +121,16 @@ For Git, each commit in a rebase is considered a distinct signing operation so by default an ephemeral key is generated for each commit. There are a few options to help automating the authentication process: -- Setting the [`connectorID`](/signing/gitsign/#configuration) value can be set to +* Setting the [`connectorID`](cosign/signing/gitsign/#configuration) value can be set to automatically select the desired provider for Dex-backed OIDC providers (including the public Sigstore instance at `oauth.sigstore.dev`). While this still requires a browser window to open, this does not require an extra click to select the provider. -- Starting in v0.2.0, Gitsign has experimental support for key caching to allow +* Starting in v0.2.0, Gitsign has experimental support for key caching to allow users to reuse ephemeral keys for the lifetime of the Fulcio certificate. If you are interested in learning more, check out the [`gitsign-credential-cache` README](https://github.com/sigstore/gitsign/tree/main/cmd/gitsign-credential-cache). - ## Rekor ### Is the transparency log monitored? @@ -148,10 +147,10 @@ There's no need for a distributed source of transparency as there can be multipl ### Why use a Merkle Tree/Transparency log? -- Rekor's back end is [Trillian](https://github.com/google/trillian) -- Trillian is an open source community under active development -- Trilian is deployed by Google, CloudFlare (nimbus), Let's Encrypt for certificate transparency, so it already is considered production grade +* Rekor's back end is [Trillian](https://github.com/google/trillian) +* Trillian is an open source community under active development +* Trilian is deployed by Google, CloudFlare (nimbus), Let's Encrypt for certificate transparency, so it already is considered production grade ### Can I get Rekor to work with my X format, framework standard? -- Yes. Using pluggable types you can create your own manifest layout and send it to Rekor. Head over to [pluggable types]({{< relref "logging/pluggable-types">}}) +* Yes. Using pluggable types you can create your own manifest layout and send it to Rekor. Head over to [pluggable types]({{< relref "logging/pluggable-types">}}) diff --git a/content/en/about/overview.md b/content/en/about/overview.md index 541575e8..1c5bee0f 100644 --- a/content/en/about/overview.md +++ b/content/en/about/overview.md @@ -58,13 +58,13 @@ For more information on the modules that make up Sigstore, review [Tooling]({{< ## How to use Sigstore -To use Sigstore, you must first install the client. Review the [Installation]({{< relref "system_config/installation">}}) instructions. You can then pick the subject matter you wish to learn about from the menu items on the left. For a quick introduction, you can try using one of the links below: +To use Sigstore, you must first install the client. Review the [Installation]({{< relref "cosign/system_config/installation">}}) instructions. You can then pick the subject matter you wish to learn about from the menu items on the left. For a quick introduction, you can try using one of the links below: -- To get a quick view of how to use the program see [Quick Start]({{< relref "signing/quickstart">}}) -- To learn how to work with blobs, see [sign a blob]({{< relref "signing/signing_with_blobs">}}) -- To learn how to work with containers, see [sign a container]({{< relref "signing/signing_with_containers">}}) -- To use Gitsign, see [Sign Git commits with Gitsign]({{< relref "signing/gitsign">}}) -- To learn about verification, see [verify entries with Cosign]({{< relref "verifying/verify">}}) +- To get a quick view of how to use the program see [Quick Start]({{< relref "quickstart/quickstart-cosign">}}) +- To learn how to work with blobs, see [sign a blob]({{< relref "cosign/signing/signing_with_blobs">}}) +- To learn how to work with containers, see [sign a container]({{< relref "cosign/signing/signing_with_containers">}}) +- To use Gitsign, see [Sign Git commits with Gitsign]({{< relref "cosign/signing/gitsign">}}) +- To learn about verification, see [verify entries with Cosign]({{< relref "cosign/verifying/verify">}}) ## Contributing diff --git a/content/en/about/threat-model.md b/content/en/about/threat-model.md index a7a23d48..ab7aaa76 100644 --- a/content/en/about/threat-model.md +++ b/content/en/about/threat-model.md @@ -9,7 +9,7 @@ weight: 3 ## Introduction **What types of security analysis have you done on Sigstore?** -This page contains the results of a threat modeling exercise on Sigstore. First, we enumerate the components of Sigstore along with third parties and infrastructure that it uses during the [“keyless” signing]({{< relref "signing/overview">}}) and verification flows. Second, we postulate an attacker that can compromise various subsets of these parties. Finally, we analyze the impact of such an attacker on these security properties. The results of a similar exercise are included in the peer-reviewed paper [Sigstore: Software Signing for Everybody](https://dl.acm.org/doi/pdf/10.1145/3548606.3560596). +This page contains the results of a threat modeling exercise on Sigstore. First, we enumerate the components of Sigstore along with third parties and infrastructure that it uses during the [“keyless” signing]({{< relref "cosign/signing/overview">}}) and verification flows. Second, we postulate an attacker that can compromise various subsets of these parties. Finally, we analyze the impact of such an attacker on these security properties. The results of a similar exercise are included in the peer-reviewed paper [Sigstore: Software Signing for Everybody](https://dl.acm.org/doi/pdf/10.1145/3548606.3560596). This will be most useful to those building secure systems on top of Sigstore, rather than end users. The security guarantees of such systems depends on the details of integration; an example analysis can be found in [TAP-18](https://github.com/theupdateframework/taps/blob/master/tap18.md), which proposes using Sigstore identities with a [TUF](https://theupdateframework.com/) repository used to securely distribute software artifacts. diff --git a/content/en/cosign/_index.html b/content/en/cosign/_index.html new file mode 100644 index 00000000..6ced309a --- /dev/null +++ b/content/en/cosign/_index.html @@ -0,0 +1,9 @@ +--- +title: "Cosign" +lead: "" +date: 2020-10-06T08:49:15+00:00 +lastmod: 2020-10-06T08:49:15+00:00 +draft: false +images: [] +weight: 15 +--- diff --git a/content/en/key_management/_index.html b/content/en/cosign/key_management/_index.html similarity index 100% rename from content/en/key_management/_index.html rename to content/en/cosign/key_management/_index.html diff --git a/content/en/key_management/hardware-based-tokens.md b/content/en/cosign/key_management/hardware-based-tokens.md similarity index 99% rename from content/en/key_management/hardware-based-tokens.md rename to content/en/cosign/key_management/hardware-based-tokens.md index 6b387286..f5d2dfec 100644 --- a/content/en/key_management/hardware-based-tokens.md +++ b/content/en/cosign/key_management/hardware-based-tokens.md @@ -10,7 +10,7 @@ This support is enabled through the [PIV protocol](https://csrc.nist.gov/project 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** +## Background information 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) diff --git a/content/en/key_management/import-keypair.md b/content/en/cosign/key_management/import-keypair.md similarity index 77% rename from content/en/key_management/import-keypair.md rename to content/en/cosign/key_management/import-keypair.md index 35dfa378..850b1bb4 100644 --- a/content/en/key_management/import-keypair.md +++ b/content/en/cosign/key_management/import-keypair.md @@ -9,7 +9,7 @@ weight: 510 ### Import a Key Pair -To use a local key not generated by cosign for signing, the key must be imported. To use a key stored in a [KMS]({{< relref "key_management/overview">}}), importing is not necessary and the key can be [specified by resource name](/key_management/overview/#signing-and-verification). +To use a local key not generated by cosign for signing, the key must be imported. To use a key stored in a [KMS]({{< relref "cosign/key_management/overview">}}), importing is not necessary and the key can be [specified by resource name]({{< relref "overview.md#signing-and-verification">}}). The importing of a key pair with `cosign` is as follows. diff --git a/content/en/key_management/overview.md b/content/en/cosign/key_management/overview.md similarity index 99% rename from content/en/key_management/overview.md rename to content/en/cosign/key_management/overview.md index 113ce1e4..91ec71da 100644 --- a/content/en/key_management/overview.md +++ b/content/en/cosign/key_management/overview.md @@ -115,7 +115,7 @@ $ cosign verify --key awskms:///${AWS_CMK_ID} $IMAGE_DIGEST | jq . GCP KMS keys can be used in `cosign` for signing and verification. -The URI format for GCP KMS is: +The URI format for GCP KMS is: ```shell gcpkms://projects/$PROJECT/locations/$LOCATION/keyRings/$KEYRING/cryptoKeys/$KEY/versions/$KEY_VERSION diff --git a/content/en/key_management/signing_with_self-managed_keys.md b/content/en/cosign/key_management/signing_with_self-managed_keys.md similarity index 95% rename from content/en/key_management/signing_with_self-managed_keys.md rename to content/en/cosign/key_management/signing_with_self-managed_keys.md index 178b908a..5238a5cb 100644 --- a/content/en/key_management/signing_with_self-managed_keys.md +++ b/content/en/cosign/key_management/signing_with_self-managed_keys.md @@ -15,7 +15,7 @@ Private key written to cosign.key Public key written to cosign.pub ``` -Alternatively, you can use the `COSIGN_PASSWORD` environment variable to provide one. +Alternatively, you can use the `COSIGN_PASSWORD` environment variable to provide one. *Note:* Cosign supports RSA, ECDSA, and ED25519 keys. For RSA, Cosign only supports RSA PKCS#1.5 padded keys. @@ -27,7 +27,7 @@ To generate keys using a KMS provider, you can use the `cosign generate-key-pair cosign generate-key-pair --kms :// ``` -Read more about this in the [key management overview]({{< relref "key_management/overview">}}). +Read more about this in the [key management overview]({{< relref "cosign/key_management/overview">}}). The public key can be retrieved with: diff --git a/content/en/signing/_index.html b/content/en/cosign/signing/_index.html similarity index 100% rename from content/en/signing/_index.html rename to content/en/cosign/signing/_index.html diff --git a/content/en/signing/git_support.md b/content/en/cosign/signing/git_support.md similarity index 94% rename from content/en/signing/git_support.md rename to content/en/cosign/signing/git_support.md index af2c806f..a56b7a89 100644 --- a/content/en/signing/git_support.md +++ b/content/en/cosign/signing/git_support.md @@ -23,7 +23,7 @@ To generate keys using a Git provider, you can use the `cosign generate-key-pair argument `github://` or `gitlab://`. For example: ```shell -$ cosign generate-key-pair :/// +cosign generate-key-pair :/// ``` One little note here, if you prefer to use GitLab as a provider, you can specify the `ID` of the project instead of @@ -78,6 +78,6 @@ feature is only available to GitLab. GitHub does not support it to fetch the sec You can also export the public key and verify it against that file: ```shell -$ cosign public-key --key gitlab:/// > gitlab.pub -$ cosign verify --key gitlab.pub gcr.io/user-vmtest2/demo +cosign public-key --key gitlab:/// > gitlab.pub +cosign verify --key gitlab.pub gcr.io/user-vmtest2/demo ``` diff --git a/content/en/signing/gitsign.md b/content/en/cosign/signing/gitsign.md similarity index 99% rename from content/en/signing/gitsign.md rename to content/en/cosign/signing/gitsign.md index 5321e456..4b54fc75 100644 --- a/content/en/signing/gitsign.md +++ b/content/en/cosign/signing/gitsign.md @@ -40,7 +40,7 @@ https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&... [main 040b9af] Signed commit ``` -This will redirect you through the [Sigstore Keyless]({{< relref "signing/overview">}}) +This will redirect you through the [Sigstore Keyless]({{< relref "cosign/signing/overview">}}) flow to authenticate and sign the commit. Commits can then be verified using `git verify-commit`: @@ -53,6 +53,7 @@ gitsign: Good signature from [billy@chainguard.dev] Validated Git signature: true Validated Rekor entry: true ``` + ## Installing Gitsign You can install Gitsign on your system with the Go installer, via Homebrew, or @@ -146,6 +147,7 @@ git config --global tag.gpgsign true # Sign all tags git config --global gpg.x509.program gitsign # Use Gitsign for signing git config --global gpg.format x509 # Gitsign expects x509 args ``` + ## Configuration ### File config @@ -193,7 +195,7 @@ are set, `GITSIGN_` prefix takes priority. ## Signing a Commit -After installing Gitsign and configuring Git to use it as a signer application +After installing Gitsign and configuring Git to use it as a signer application for your project (or globally), you can sign commits as usual with `git commit -S` (or `git config --global commit.gpgsign true` to enable signing for all commits). diff --git a/content/en/signing/other_types.md b/content/en/cosign/signing/other_types.md similarity index 100% rename from content/en/signing/other_types.md rename to content/en/cosign/signing/other_types.md diff --git a/content/en/signing/overview.md b/content/en/cosign/signing/overview.md similarity index 98% rename from content/en/signing/overview.md rename to content/en/cosign/signing/overview.md index 078a45ef..a7b466dd 100644 --- a/content/en/signing/overview.md +++ b/content/en/cosign/signing/overview.md @@ -100,4 +100,4 @@ If you're running your own sigstore services flags are available to set your own ### Custom roots of trust -For information on custom roots of trust, see [Configuring Cosign with Custom Components]({{< relref "system_config/custom_components">}}). +For information on custom roots of trust, see [Configuring Cosign with Custom Components]({{< relref "cosign/system_config/custom_components">}}). diff --git a/content/en/signing/pkcs11.md b/content/en/cosign/signing/pkcs11.md similarity index 100% rename from content/en/signing/pkcs11.md rename to content/en/cosign/signing/pkcs11.md diff --git a/content/en/signing/signing_with_blobs.md b/content/en/cosign/signing/signing_with_blobs.md similarity index 96% rename from content/en/signing/signing_with_blobs.md rename to content/en/cosign/signing/signing_with_blobs.md index 4a371640..425ebb3e 100644 --- a/content/en/signing/signing_with_blobs.md +++ b/content/en/cosign/signing/signing_with_blobs.md @@ -5,7 +5,7 @@ title: Signing Blobs weight: 130 --- -You can use Cosign for signing and verifying standard files and blobs (or binary large objects), in addition to containers. This topic discusses signing blobs/files. For information on verifying, see [Verifying Signatures]({{< relref "verifying/verify">}}). +You can use Cosign for signing and verifying standard files and blobs (or binary large objects), in addition to containers. This topic discusses signing blobs/files. For information on verifying, see [Verifying Signatures]({{< relref "cosign/verifying/verify">}}). ## Keyless signing of blobs and files @@ -62,7 +62,7 @@ Enter password for private key: MEQCIAU4wPBpl/U5Vtdx/eJFgR0nICiiNCgyWPWarupH0onwAiAv5ycIKgztxHNVG7bzUjqHuvK2gsc4MWxwDgtDh0JINw== ``` -This supports all the same flags and features as `cosign sign`, including KMS support, hardware tokens, and keyless signatures. See [Signing with Self-Managed Keys]({{< relref "key_management/signing_with_self-managed_keys">}}) for more information. +This supports all the same flags and features as `cosign sign`, including KMS support, hardware tokens, and keyless signatures. See [Signing with Self-Managed Keys]({{< relref "cosign/key_management/signing_with_self-managed_keys">}}) for more information. ## Blobs in OCI Registries diff --git a/content/en/signing/signing_with_containers.md b/content/en/cosign/signing/signing_with_containers.md similarity index 98% rename from content/en/signing/signing_with_containers.md rename to content/en/cosign/signing/signing_with_containers.md index 87f71908..38d546e0 100644 --- a/content/en/signing/signing_with_containers.md +++ b/content/en/cosign/signing/signing_with_containers.md @@ -5,7 +5,7 @@ title: Signing Containers weight: 125 --- -You can use Cosign to sign containers with ephemeral keys by authenticating with an OIDC (OpenID Connect) protocol supported by Sigstore. Currently, you can authenticate with Google, GitHub, or Microsoft. For more information, read the [Key management overview]({{< relref "key_management/overview">}}). +You can use Cosign to sign containers with ephemeral keys by authenticating with an OIDC (OpenID Connect) protocol supported by Sigstore. Currently, you can authenticate with Google, GitHub, or Microsoft. For more information, read the [Key management overview]({{< relref "cosign/key_management/overview">}}). The format for keyless signing of a container is as follows. @@ -39,7 +39,7 @@ This usage is a common use case that uses traditional key signing from a key pai $ cosign sign --key cosign.key $IMAGE ``` -If you need to generate local keys, you can do so by running `cosign generate-key-pair`. See [Signing with Self-Managed Keys]({{< relref "key_management/signing_with_self-managed_keys">}}) for more information. +If you need to generate local keys, you can do so by running `cosign generate-key-pair`. See [Signing with Self-Managed Keys]({{< relref "cosign/key_management/signing_with_self-managed_keys">}}) for more information. ## Sign a container multiple times @@ -86,7 +86,7 @@ When referring to a key managed by a KMS provider, `cosign` takes a [go-cloud](h $ cosign sign --key :// $IMAGE ``` -Read more about this in our [key management overview]({{< relref "key_management/overview">}}). +Read more about this in our [key management overview]({{< relref "cosign/key_management/overview">}}). ### Key stored in an environment variable diff --git a/content/en/system_config/_index.html b/content/en/cosign/system_config/_index.html similarity index 100% rename from content/en/system_config/_index.html rename to content/en/cosign/system_config/_index.html diff --git a/content/en/system_config/custom_components.md b/content/en/cosign/system_config/custom_components.md similarity index 100% rename from content/en/system_config/custom_components.md rename to content/en/cosign/system_config/custom_components.md diff --git a/content/en/system_config/installation.md b/content/en/cosign/system_config/installation.md similarity index 100% rename from content/en/system_config/installation.md rename to content/en/cosign/system_config/installation.md diff --git a/content/en/system_config/integration.md b/content/en/cosign/system_config/integration.md similarity index 100% rename from content/en/system_config/integration.md rename to content/en/cosign/system_config/integration.md diff --git a/content/en/system_config/public_deployment.md b/content/en/cosign/system_config/public_deployment.md similarity index 100% rename from content/en/system_config/public_deployment.md rename to content/en/cosign/system_config/public_deployment.md diff --git a/content/en/system_config/registry_support.md b/content/en/cosign/system_config/registry_support.md similarity index 100% rename from content/en/system_config/registry_support.md rename to content/en/cosign/system_config/registry_support.md diff --git a/content/en/system_config/specifications.md b/content/en/cosign/system_config/specifications.md similarity index 100% rename from content/en/system_config/specifications.md rename to content/en/cosign/system_config/specifications.md diff --git a/content/en/verifying/_index.html b/content/en/cosign/verifying/_index.html similarity index 100% rename from content/en/verifying/_index.html rename to content/en/cosign/verifying/_index.html diff --git a/content/en/verifying/attestation.md b/content/en/cosign/verifying/attestation.md similarity index 100% rename from content/en/verifying/attestation.md rename to content/en/cosign/verifying/attestation.md diff --git a/content/en/verifying/inspecting.md b/content/en/cosign/verifying/inspecting.md similarity index 100% rename from content/en/verifying/inspecting.md rename to content/en/cosign/verifying/inspecting.md diff --git a/content/en/verifying/timestamps.md b/content/en/cosign/verifying/timestamps.md similarity index 100% rename from content/en/verifying/timestamps.md rename to content/en/cosign/verifying/timestamps.md diff --git a/content/en/verifying/verify.md b/content/en/cosign/verifying/verify.md similarity index 97% rename from content/en/verifying/verify.md rename to content/en/cosign/verifying/verify.md index c41946d7..57b07ce9 100644 --- a/content/en/verifying/verify.md +++ b/content/en/cosign/verifying/verify.md @@ -5,7 +5,7 @@ title: Verifying Signatures weight: 300 --- -> **Note**: To verify a signed artifact or blob, first [install Cosign]({{< relref "system_config/installation">}}), then follow the instructions below. +> **Note**: To verify a signed artifact or blob, first [install Cosign]({{< relref "cosign/system_config/installation">}}), then follow the instructions below. The general verification format with the `cosign verify` command is as follows. @@ -238,7 +238,7 @@ AcxvLtLEgRjRI4TKnMAXtIGp8K4X4CTWPEXMqSYZZUa2I1YvHyLLY2bEzA== ``` ## Custom Components -For configuring Cosign to work with custom components, checkout the [Configuring Cosign with Custom Components]({{< relref "system_config/custom_components">}}) docs to find out how to achieve this. +For configuring Cosign to work with custom components, checkout the [Configuring Cosign with Custom Components]({{< relref "cosign/system_config/custom_components">}}) docs to find out how to achieve this. ### Custom Root Cert diff --git a/content/en/quickstart/_index.html b/content/en/quickstart/_index.html new file mode 100644 index 00000000..d9be6b65 --- /dev/null +++ b/content/en/quickstart/_index.html @@ -0,0 +1,11 @@ +--- +type: docs +title: "Quickstart" +description: "" +lead: "" +date: 2020-10-06T08:49:15+00:00 +lastmod: 2020-10-06T08:49:15+00:00 +draft: false +images: [] +weight: 10 +--- diff --git a/content/en/signing/quickstart.md b/content/en/quickstart/quickstart-cosign.md similarity index 80% rename from content/en/signing/quickstart.md rename to content/en/quickstart/quickstart-cosign.md index f6a93e0d..6c504be2 100644 --- a/content/en/signing/quickstart.md +++ b/content/en/quickstart/quickstart-cosign.md @@ -1,22 +1,26 @@ --- type: docs -category: Signing -description: '' -menuTitle: Quick Start -title: Cosign -weight: 100 +category: Quickstart +description: Sign and Verify with Cosign +title: Sigstore Quickstart with Cosign +weight: 5 --- ![Cosign Overview](/sigstore_cosign-horizontal-color.svg) -## Getting Started (Quick Start) - -Cosign is a command line utility that can sign and verify software artifact, such as container images and blobs. Join us on our [Slack channel](https://sigstore.slack.com/). (Need an [invite](https://links.sigstore.dev/slack-invite)?) +## Quickstart signing and verifying with Cosign + +Cosign is a command line utility that is used to sign software artifacts and verify signatures using Sigstore. + +Language specific clients (like [sigstore-python](https://github.com/sigstore/sigstore-python)) are other options for signing and verifying, but Cosign is a great, language agnostic place to start. + +This quickstart will walk you through how to sign and verify a blob and a container. Although keyless signing is recommended, this quickstart will also show you how to sign using a generated key. + ### Installation -To sign software artifacts and verify signatures using Sigstore, you need to install Cosign. Instructions to install Cosign can be found on the [Cosign Installation page]({{< relref "system_config/installation">}}). This will allow you to sign and verify both blobs and containers. +To sign software artifacts and verify signatures using Sigstore, you need to install Cosign. Instructions to install Cosign can be found on the [Cosign Installation page]({{< relref "cosign/system_config/installation">}}). This will allow you to sign and verify both blobs and containers. ### Signing a blob @@ -113,16 +117,16 @@ Pushing signature to: index.docker.io/user/demo:sha256-87ef60f558bad79be4def8.si ``` ## SCM Integration -Cosign integrates natively with source code management (SCM) systems like GitHub and GitLab. You can use the official [GitHub Actions Cosign installer](https://github.com/marketplace/actions/cosign-installer) or use Cosign to generate and work safely with [SCM secrets]({{< relref "signing/git_support">}}) with native API integration. +Cosign integrates natively with source code management (SCM) systems like GitHub and GitLab. You can use the official [GitHub Actions Cosign installer](https://github.com/marketplace/actions/cosign-installer) or use Cosign to generate and work safely with [SCM secrets]({{< relref "cosign/signing/git_support">}}) with native API integration. ## Attestations In addition to signatures, Cosign can be used with [In-Toto Attestations](https://github.com/in-toto/attestation). -Attestations provide an additional semantic-layer on top of plain cryptographic signatures that can be used in policy systems. Learn more in the [Attestations]({{< relref "verifying/attestation">}}) documentation. +Attestations provide an additional semantic-layer on top of plain cryptographic signatures that can be used in policy systems. Learn more in the [Attestations]({{< relref "cosign/verifying/attestation">}}) documentation. ## Other Formats Cosign is useful not only for blobs, containers, and container-related artifacts; it can also be used for other file types. -To learn how to sign SBOMs, WASM modules, Tekton bundles and more, review [Signing Other Types]({{< relref "signing/other_types" >}}). For more information about blobs, review [Signing Blobs]({{< relref "signing/signing_with_blobs" >}}). For containers, see [Signing Containers]({{< relref "signing/signing_with_containers" >}}). +To learn how to sign SBOMs, WASM modules, Tekton bundles and more, review [Signing Other Types]({{< relref "cosign/signing/other_types" >}}). For more information about blobs, review [Signing Blobs]({{< relref "cosign/signing/signing_with_blobs" >}}). For containers, see [Signing Containers]({{< relref "cosign/signing/signing_with_containers" >}}). diff --git a/layouts/_default/list.html b/layouts/_default/list.html index 2778b20b..a0a32629 100644 --- a/layouts/_default/list.html +++ b/layouts/_default/list.html @@ -11,12 +11,10 @@

{{ .Title }}

{{- .Scratch.Set "fillImage" "1270x620 Center" -}} - {{ partial "content/card-image.html" . }}

{{ .Params.title }}

{{ .Params.excerpt | safeHTML }}

- {{ partial "main/blog-meta.html" . -}}
From f01dd724d29e0f407287af2270226322b7f50422 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Mon, 9 Sep 2024 22:29:52 -0700 Subject: [PATCH 2/3] Addressing comments about formatting and signing with a generated key. Signed-off-by: hayleycd --- .../key_management/hardware-based-tokens.md | 3 --- content/en/quickstart/quickstart-cosign.md | 19 +------------------ 2 files changed, 1 insertion(+), 21 deletions(-) diff --git a/content/en/cosign/key_management/hardware-based-tokens.md b/content/en/cosign/key_management/hardware-based-tokens.md index f5d2dfec..3fdd5046 100644 --- a/content/en/cosign/key_management/hardware-based-tokens.md +++ b/content/en/cosign/key_management/hardware-based-tokens.md @@ -9,14 +9,11 @@ The `cosign` command line tool optionally supports hardware tokens for signing a 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. ---- ## Background information 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. The following exmamples use this image: diff --git a/content/en/quickstart/quickstart-cosign.md b/content/en/quickstart/quickstart-cosign.md index 6c504be2..848c76ba 100644 --- a/content/en/quickstart/quickstart-cosign.md +++ b/content/en/quickstart/quickstart-cosign.md @@ -16,7 +16,7 @@ Cosign is a command line utility that is used to sign software artifacts and ver Language specific clients (like [sigstore-python](https://github.com/sigstore/sigstore-python)) are other options for signing and verifying, but Cosign is a great, language agnostic place to start. -This quickstart will walk you through how to sign and verify a blob and a container. Although keyless signing is recommended, this quickstart will also show you how to sign using a generated key. +This quickstart will walk you through how to sign and verify a blob and a container. ### Installation @@ -98,23 +98,6 @@ $ cosign verify --certificate-identity=name@example.com cosign verify $IMAGE_URI_DIGEST --certificate-identity-regexp=.* --certificate-oidc-issuer-regexp=.* ``` -## Signing with a generated key - -It is recommended that you use keyless signing, as a main feature of Sigstore is to make signatures invisible infrastructure that do not require key management. However, Sigstore allows you to use an existing key or generate a key if you prefer. - -To generate keys using Cosign, use the `cosign generate-key-pair` command. - -``` -$ cosign generate-key-pair -``` - -The following example shows the process of signing with an existing key. You must enter the password of the private key to sign. - -``` -$ cosign sign --key cosign.key user/demo -Enter password for private key: -Pushing signature to: index.docker.io/user/demo:sha256-87ef60f558bad79be4def8.sig -``` ## SCM Integration Cosign integrates natively with source code management (SCM) systems like GitHub and GitLab. You can use the official [GitHub Actions Cosign installer](https://github.com/marketplace/actions/cosign-installer) or use Cosign to generate and work safely with [SCM secrets]({{< relref "cosign/signing/git_support">}}) with native API integration. From fd31d8f0014530e4b3f0b76310a0932d94aace57 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Thu, 12 Sep 2024 09:01:20 -0700 Subject: [PATCH 3/3] Addressing language client comment. Signed-off-by: hayleycd --- content/en/quickstart/quickstart-cosign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/quickstart/quickstart-cosign.md b/content/en/quickstart/quickstart-cosign.md index 848c76ba..82963507 100644 --- a/content/en/quickstart/quickstart-cosign.md +++ b/content/en/quickstart/quickstart-cosign.md @@ -14,7 +14,7 @@ Join us on our [Slack channel](https://sigstore.slack.com/). (Need an [invite](h Cosign is a command line utility that is used to sign software artifacts and verify signatures using Sigstore. -Language specific clients (like [sigstore-python](https://github.com/sigstore/sigstore-python)) are other options for signing and verifying, but Cosign is a great, language agnostic place to start. +Sigstore has a number of language specific clients (like [sigstore-python](https://github.com/sigstore/sigstore-python)). These clients are SDKs that you can use to build custom tooling. Although a number of the clients include a basic CLI, Cosign is the recommended tool for signing and verifying. This quickstart will walk you through how to sign and verify a blob and a container.