Cosign reorg (#323)

* 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 <[email protected]>

* Addressing comments about formatting and signing with a generated key.

Signed-off-by: hayleycd <[email protected]>

* Addressing language client comment.

Signed-off-by: hayleycd <[email protected]>

---------

Signed-off-by: hayleycd <[email protected]>

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">}})

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
 

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.
 

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
+---

content/en/key_management/hardware-based-tokens.md → 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.
 
----
-**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)
 
----
-
 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:

content/en/key_management/import-keypair.md → 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.
 

content/en/key_management/overview.md → 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

content/en/key_management/signing_with_self-managed_keys.md → 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 <some provider>://<some key>
 ```
 
-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:
 

content/en/signing/git_support.md → 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 <some provider>://<owner>/<project>
+cosign generate-key-pair <some provider>://<owner>/<project>
 ```
 
 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://<owner>/<project> > gitlab.pub
-$ cosign verify --key gitlab.pub gcr.io/user-vmtest2/demo
+cosign public-key --key gitlab://<owner>/<project> > gitlab.pub
+cosign verify --key gitlab.pub gcr.io/user-vmtest2/demo
 ```

content/en/signing/gitsign.md → 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 [[email protected]]
 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).

content/en/signing/overview.md → 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">}}).

content/en/signing/signing_with_blobs.md → 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
 

content/en/signing/signing_with_containers.md → 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 <some provider>://<some 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
 

content/en/verifying/verify.md → 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
 

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
+---