diff --git a/content/en/about/faq.md b/content/en/about/faq.md index 977bb73b..c6666229 100644 --- a/content/en/about/faq.md +++ b/content/en/about/faq.md @@ -71,7 +71,7 @@ reasons: [GitHub’s trust root](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#smime-commit-signature-verification). 2. Gitsign’s ephemeral keys are only valid for a short time, so using standard x509 verification would consider the certificate invalid after expiration. - Verification needs to include validation via the [transparency log](/logging/overview/) to + Verification needs to include validation via the [transparency log]({{< relref "logging/overview">}}) to verify that the certificate was valid at the time it was used. We hope to work closely with GitHub to get these types of signatures recognized @@ -91,14 +91,14 @@ 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](/verifying/inspecting/) for +[inspecting the Git commit signature]({{< relref "verifying/inspecting">}}) for more details. #### 2. Within the Rekor transparency log To be able to verify signatures for ephemeral certs past their `Not After` time, Gitsign records commits and the code signing certificates to -[Rekor](/logging/overview/). This data is a +[Rekor]({{< relref "logging/overview">}}). This data is a [HashedRekord](https://github.com/sigstore/rekor/blob/e375eb461cae524270889b57a249ff086bea6c05/types.md#hashed-rekord) containing a SHA256 hash of the commit SHA, as well as the code signing certificate. Review guidance on @@ -110,7 +110,7 @@ By default, data is written to the particular, users and organizations may be sensitive to the data contained within code signing certificates returned by Fulcio, which may include user emails or repository identifiers. Review -[OIDC Usage in Fulcio](/certificate_authority/oidc-in-fulcio/) for more details regarding what +[OIDC Usage in Fulcio]({{< relref "certificate_authority/oidc-in-fulcio">}}) for more details regarding what data is contained in the code signing certs. Alternately, you can learn how to [Deploy a Rekor Server Manually](/logging/installation/#deploy-a-rekor-server-manually), which would set up your own Rekor instance. @@ -158,4 +158,4 @@ Public blockchains often end up using a centralized entry point for canonicaliza ### 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](/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 9131126d..b89b1f83 100644 --- a/content/en/about/overview.md +++ b/content/en/about/overview.md @@ -54,23 +54,23 @@ After the client signs the artifact, the artifact's digest, signature and certif For verifying an artifact, a Sigstore client will verify the signature on the artifact using the public key from the certificate, verify the identity in the certificate matches an expected identity, verify the certificate's signature using Sigstore's root of trust, and verify proof of inclusion in Rekor. Together, verification of this information tells the user that the artifact comes from its expected source and has not been tampered with after its creation. -For more information on the modules that make up Sigstore, review [Toolling](/about/tooling/). +For more information on the modules that make up Sigstore, review [Toolling]({{< relref "about/tooling">}}). ## How to use Sigstore -To use Sigstore, you must first install the client. Review the [Installation](/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 "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](/signing/quickstart/) -- To learn how to work with blobs, see [sign a blob](/signing/signing_with_blobs/) -- To learn how to work with containers, see [sign a container](/signing/signing_with_containers/) -- To use Gitsign, see [Sign Git commits with Gitsign](/signing/gitsign/) -- To learn about verification, see [verify entries with Cosign](/verifying/verify/) +- 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">}}) ## Contributing Up to date documentation, best practices, and detailed scenarios for Sigstore live here. These pages are maintained by the community and intended to help anyone get set up with any of the technologies, to find what you’re looking for fast. It’s also where we keep all the relevant pages for the Sigstore trust root, from signing ceremonies to security practices. -Ready to jump in? Check the [contributing guidelines](/about/contributing/). +Ready to jump in? Check the [contributing guidelines]({{< relref "about/contributing">}}). ## Learn more diff --git a/content/en/about/security.md b/content/en/about/security.md index 9ef19844..0db6a46a 100644 --- a/content/en/about/security.md +++ b/content/en/about/security.md @@ -6,7 +6,7 @@ title: Security Model weight: 3 --- -The Sigstore security model has a few key components, each aimed at establishing trust or proving identity. For a quick overview of the key services mentioned in this document, see [Tooling](/about/tooling/). +The Sigstore security model has a few key components, each aimed at establishing trust or proving identity. For a quick overview of the key services mentioned in this document, see [Tooling]({{< relref "about/tooling">}}). ## Proving Identity in Sigstore diff --git a/content/en/about/threat-model.md b/content/en/about/threat-model.md index 4a85bd1d..a7a23d48 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](/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 "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/key_management/import-keypair.md b/content/en/key_management/import-keypair.md index a96ca255..35dfa378 100644 --- a/content/en/key_management/import-keypair.md +++ b/content/en/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](/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 "key_management/overview">}}), importing is not necessary and the key can be [specified by resource name](/key_management/overview/#signing-and-verification). The importing of a key pair with `cosign` is as follows. diff --git a/content/en/key_management/signing_with_self-managed_keys.md b/content/en/key_management/signing_with_self-managed_keys.md index 3c947f06..178b908a 100644 --- a/content/en/key_management/signing_with_self-managed_keys.md +++ b/content/en/key_management/signing_with_self-managed_keys.md @@ -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](/key_management/overview/). +Read more about this in the [key management overview]({{< relref "key_management/overview">}}). The public key can be retrieved with: diff --git a/content/en/logging/CLI.md b/content/en/logging/CLI.md index ee9c306d..853b0e1f 100644 --- a/content/en/logging/CLI.md +++ b/content/en/logging/CLI.md @@ -7,11 +7,11 @@ weight: 1825 The following guide is targeted towards developers / software maintainers who would like to make a provenance entry into the rekor transparency log. -The steps outlined below will show how to sign your software and use the Rekor CLI to make and verify an entry. It uses GPG to demonstrate, but other types are outlined in the [Signing and Uploading Other Types](/logging/sign-upload/) page. +The steps outlined below will show how to sign your software and use the Rekor CLI to make and verify an entry. It uses GPG to demonstrate, but other types are outlined in the [Signing and Uploading Other Types]({{< relref "logging/sign-upload">}}) page. ## Prerequisites -You need to have Rekor CLI installed. See the [Installation](/logging/installation/) page for instructions. +You need to have Rekor CLI installed. See the [Installation]({{< relref "logging/installation">}}) page for instructions. ## Sign your release diff --git a/content/en/logging/installation.md b/content/en/logging/installation.md index bca54f17..eea27178 100644 --- a/content/en/logging/installation.md +++ b/content/en/logging/installation.md @@ -27,7 +27,7 @@ Rekor releases are available on the [Release page](https://github.com/sigstore/r Releases are available for both `rekor-server` and `rekor-cli`. -Review [Verifying Binaries](/logging/verify-release/) for details on how to verify Rekor release binaries. +Review [Verifying Binaries]({{< relref "logging/verify-release">}}) for details on how to verify Rekor release binaries. ## Build Rekor CLI manually @@ -45,7 +45,7 @@ There are a few ways you can deploy a Rekor Server: 1. We have a [docker-compose](https://github.com/sigstore/rekor/blob/main/docker-compose.yml) file available. 2. Alternatively, you can build a Rekor server yourself. -Note: The Rekor server manually creates a new Merkle tree (or shard) in the Trillian backend every time it starts up, unless an existing one is specified in via the `--trillian_log_server.tlog_id` flag. If you are building the server yourself and do not need [sharding](/logging/sharding/) functionality, you can find the existing tree's TreeID by issuing this client command while the server is running: +Note: The Rekor server manually creates a new Merkle tree (or shard) in the Trillian backend every time it starts up, unless an existing one is specified in via the `--trillian_log_server.tlog_id` flag. If you are building the server yourself and do not need [sharding]({{< relref "logging/sharding">}}) functionality, you can find the existing tree's TreeID by issuing this client command while the server is running: `CURRENT_TREE_ID=$(rekor-cli loginfo --format json | jq -r .TreeID)` @@ -150,4 +150,4 @@ rekor-server serve --enable_retrieve_api=false #### Next Steps -Congratulations! Your local Rekor server is now running. You can interact with it using the [Rekor CLI](/logging/cli/). +Congratulations! Your local Rekor server is now running. You can interact with it using the [Rekor CLI]({{< relref "logging/cli">}}). diff --git a/content/en/logging/overview.md b/content/en/logging/overview.md index 8f83bea5..1560d9f4 100644 --- a/content/en/logging/overview.md +++ b/content/en/logging/overview.md @@ -19,7 +19,7 @@ Rekor fulfils the signature transparency role of sigstore’s software signing i ## Usage and installation -You can download and setup the Rekor Server and Rekor CLI by following the instructions on the [Installation](/logging/installation/) page. +You can download and setup the Rekor Server and Rekor CLI by following the instructions on the [Installation]({{< relref "logging/installation">}}) page. A public instance of Rekor can be found at [rekor.sigstore.dev](https://rekor.sigstore.dev). The public instance offers an SLO of 99.5% availability and is monitored by an oncall team. diff --git a/content/en/logging/sign-upload.md b/content/en/logging/sign-upload.md index 4b078fba..21ac24c5 100644 --- a/content/en/logging/sign-upload.md +++ b/content/en/logging/sign-upload.md @@ -5,7 +5,7 @@ title: Signing and Uploading Other Types weight: 1835 --- -This documentation contains information on how to sign and upload data in different [pluggable types](/logging/pluggable-types/). +This documentation contains information on how to sign and upload data in different [pluggable types]({{< relref "logging/pluggable-types">}}). The following are covered: diff --git a/content/en/policy-controller/overview.md b/content/en/policy-controller/overview.md index 1e31c1ad..8ad012e8 100644 --- a/content/en/policy-controller/overview.md +++ b/content/en/policy-controller/overview.md @@ -12,7 +12,7 @@ The `policy-controller` admission controller can be used to enforce policy on a `policy-controller` also resolves the image tags to ensure the image being ran is not different from when it was admitted. -See the [installation instructions](/policy-controller/installation/) for more information. +See the [installation instructions]({{< relref "policy-controller/installation">}}) for more information. **This component is still actively under development!** diff --git a/content/en/signing/gitsign.md b/content/en/signing/gitsign.md index 22d76a09..e591e24b 100644 --- a/content/en/signing/gitsign.md +++ b/content/en/signing/gitsign.md @@ -14,7 +14,7 @@ you won’t need GPG keys and a complicated setup in order to sign your Git commits. After installing and configuring Gitsign within your project and signing your commits, you will be redirected to a browser window to authenticate with a supported OpenID provider, such as GitHub or Google. Signing details will -then be stored in the transparency log [Rekor](/logging/overview/) for subsequent verification. +then be stored in the transparency log [Rekor]({{< relref "logging/overview">}}) for subsequent verification. Gitsign is part of the Sigstore project. Join us on our [Slack channel](https://sigstore.slack.com/) if you want to learn more or get @@ -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](/signing/overview/) +This will redirect you through the [Sigstore Keyless]({{< relref "signing/overview">}}) flow to authenticate and sign the commit. Commits can then be verified using `git verify-commit`: diff --git a/content/en/signing/overview.md b/content/en/signing/overview.md index 5413bc04..dca26906 100644 --- a/content/en/signing/overview.md +++ b/content/en/signing/overview.md @@ -7,7 +7,7 @@ weight: 110 This document explains how identity-based, or "keyless" signing works in Sigstore. -To learn more about OIDC, please review [OIDC Usage in Fulcio](/certificate_authority/oidc-in-fulcio/). +To learn more about OIDC, please review [OIDC Usage in Fulcio]({{< relref "certificate_authority/oidc-in-fulcio">}}). Keyless signing associates identities, rather than keys, with an artifact signature. Fulcio issues short-lived certificates binding an ephemeral key to an OpenID Connect identity. Signing events are logged in Rekor, a signature transparency log, providing an auditable record of when a signature was created. @@ -100,4 +100,4 @@ If you're running your own sigtore 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](/system_config/custom_components/). +For information on custom roots of trust, see [Configuring Cosign with Custom Components]({{< relref "system_config/custom_components">}}). diff --git a/content/en/signing/quickstart.md b/content/en/signing/quickstart.md index bfc22dc7..f6a93e0d 100644 --- a/content/en/signing/quickstart.md +++ b/content/en/signing/quickstart.md @@ -16,7 +16,7 @@ Join us on our [Slack channel](https://sigstore.slack.com/). (Need an [invite](h ### 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](/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 "system_config/installation">}}). This will allow you to sign and verify both blobs and containers. ### Signing a blob @@ -113,16 +113,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](/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 "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](/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 "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](/signing/other_types/). For more information about blobs, review [Signing Blobs](/signing/signing_with_blobs/). For containers, see [Signing Containers](/signing/signing_with_containers/). +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" >}}). diff --git a/content/en/signing/signing_with_blobs.md b/content/en/signing/signing_with_blobs.md index 85dec432..764bf94b 100644 --- a/content/en/signing/signing_with_blobs.md +++ b/content/en/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](/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 "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](/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 "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/signing/signing_with_containers.md index 85695f58..87f71908 100644 --- a/content/en/signing/signing_with_containers.md +++ b/content/en/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](/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 "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](/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 "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](/key_management/overview/). +Read more about this in our [key management overview]({{< relref "key_management/overview">}}). ### Key stored in an environment variable diff --git a/content/en/verifying/inspecting.md b/content/en/verifying/inspecting.md index 0f281f05..29ef2225 100644 --- a/content/en/verifying/inspecting.md +++ b/content/en/verifying/inspecting.md @@ -200,7 +200,7 @@ nPkp+Sy1EwIwdOulWop3oJV/Qo7fau0mlsy0MCm3lBgyxo2lpAaI4gFRxGE2GhpV ### Verifying the Transparency Log -As part of signature verification, Gitsign not only checks that the given signature matches the commit, but also that the commit exists within the [Rekor](/logging/overview/) transparency log. +As part of signature verification, Gitsign not only checks that the given signature matches the commit, but also that the commit exists within the [Rekor]({{< relref "logging/overview">}}) transparency log. To manually validate that the commit exists in the transparency log, first you should obtain the relevant UUID from your Git history and then use `rekor-cli` to query for this entry. You can do this with the following commands: diff --git a/content/en/verifying/verify.md b/content/en/verifying/verify.md index 390901ad..ff0ba9a6 100644 --- a/content/en/verifying/verify.md +++ b/content/en/verifying/verify.md @@ -5,7 +5,7 @@ title: Verifying Signatures weight: 300 --- -> **Note**: To verify a signed artifact or blob, first [install Cosign](/system_config/installation/), then follow the instructions below. +> **Note**: To verify a signed artifact or blob, first [install Cosign]({{< relref "system_config/installation">}}), then follow the instructions below. The general verification format with the `cosign verify` command is as follows. @@ -223,7 +223,7 @@ AcxvLtLEgRjRI4TKnMAXtIGp8K4X4CTWPEXMqSYZZUa2I1YvHyLLY2bEzA== ``` ## Custom Components -For configuring Cosign to work with custom components, checkout the [Configuring Cosign with Custom Components](/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 "system_config/custom_components">}}) docs to find out how to achieve this. ### Custom Root Cert