diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 00000000..b55ec247 --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,33 @@ +name: MarkdownLint + +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + markdownlint: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - uses: tj-actions/changed-files@v37 + id: changed-files + with: + files: '**/*.md' + separator: "," + + - uses: DavidAnson/markdownlint-cli2-action@v11 + if: steps.changed-files.outputs.any_changed == 'true' + with: + config: '.markdownlint-cli2.jsonc' + globs: ${{ steps.changed-files.outputs.all_changed_files }} + separator: "," + continue-on-error: true diff --git a/archetypes/docs.md b/archetypes/docs.md index 8089a43c..f9c441e8 100644 --- a/archetypes/docs.md +++ b/archetypes/docs.md @@ -12,4 +12,5 @@ menu: identifier: "{{ .Name }}-{{ delimit (shuffle (split (md5 .Name) "" )) "" }}" weight: 999 toc: true +type: docs --- diff --git a/config/_default/params.toml b/config/_default/params.toml index d5cc5255..e0f1b399 100644 --- a/config/_default/params.toml +++ b/config/_default/params.toml @@ -93,8 +93,8 @@ lastMod = false clipBoard = true instantPage = true flexSearch = true - searchSectionsShow = [] - searchSectionsIndex = [] + searchSectionsShow = "ALL" + searchSectionsIndex = "ALL" darkMode = true bootStrapJs = true breadCrumb = true diff --git a/content/en/_index.md b/content/en/_index.md deleted file mode 100644 index f807c652..00000000 --- a/content/en/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title : "Docs" -description: "Docs Doks." -lead: "" -date: 2020-10-06T08:48:23+00:00 -lastmod: 2020-10-06T08:48:23+00:00 -draft: false -images: [] ---- diff --git a/content/en/docs/about/_index.html b/content/en/about/_index.html similarity index 93% rename from content/en/docs/about/_index.html rename to content/en/about/_index.html index 2a49136a..ca37717b 100644 --- a/content/en/docs/about/_index.html +++ b/content/en/about/_index.html @@ -1,4 +1,5 @@ --- +type: docs title: "About" description: "About Sigstore" lead: "" diff --git a/content/en/docs/about/api-stability.md b/content/en/about/api-stability.md similarity index 98% rename from content/en/docs/about/api-stability.md rename to content/en/about/api-stability.md index 6321a67c..38fc618f 100644 --- a/content/en/docs/about/api-stability.md +++ b/content/en/about/api-stability.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore description: API stability levels and deprecation policy title: API Stability and Deprecation Policy @@ -40,4 +41,4 @@ _Note: These guidelines will be followed on a best-effort basis. Since Sigstore is a security project, maintainers reserve the right to break things faster if necessary to address a security issue._ A list of features and associated levels will be available in each repository under FEATURES.md. -A deprecation table will be available in each repository under DEPRECATIONS.md. \ No newline at end of file +A deprecation table will be available in each repository under DEPRECATIONS.md. diff --git a/content/en/docs/about/contributing.md b/content/en/about/contributing.md similarity index 99% rename from content/en/docs/about/contributing.md rename to content/en/about/contributing.md index 0c47f30e..b219234c 100644 --- a/content/en/docs/about/contributing.md +++ b/content/en/about/contributing.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore description: Intro text title: Contributing @@ -75,4 +76,4 @@ Docs and other calendar invites may be shared directly with this group, so pleas ## Slack -You can also keep in touch by joining our [Slack channel](https://sigstore.slack.com). Use [this invite link](https://links.sigstore.dev/slack-invite) to join. \ No newline at end of file +You can also keep in touch by joining our [Slack channel](https://sigstore.slack.com). Use [this invite link](https://links.sigstore.dev/slack-invite) to join. diff --git a/content/en/docs/about/faq.md b/content/en/about/faq.md similarity index 99% rename from content/en/docs/about/faq.md rename to content/en/about/faq.md index e53fcb84..977bb73b 100644 --- a/content/en/docs/about/faq.md +++ b/content/en/about/faq.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore menuTitle: FAQs title: Frequently asked questions @@ -157,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/) \ No newline at end of file +- Yes. Using pluggable types you can create your own manifest layout and send it to Rekor. Head over to [pluggable types](/logging/pluggable-types/) diff --git a/content/en/docs/about/overview.md b/content/en/about/overview.md similarity index 99% rename from content/en/docs/about/overview.md rename to content/en/about/overview.md index 2206560b..124293b6 100644 --- a/content/en/docs/about/overview.md +++ b/content/en/about/overview.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore description: Documentation for sigstore home: true diff --git a/content/en/docs/about/research.md b/content/en/about/research.md similarity index 99% rename from content/en/docs/about/research.md rename to content/en/about/research.md index 96059283..f80a0940 100644 --- a/content/en/docs/about/research.md +++ b/content/en/about/research.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore description: '' title: Research @@ -30,4 +31,4 @@ Academic and industry research related to software supply chain security, transp * [sigstore/java](https://github.com/sigstore/sigstore-java) * [sigstore/sigstore-maven](https://github.com/sigstore/sigstore-maven) * [Sigstore Java meeting notes](https://docs.google.com/document/d/1R7mL-IUrc2Z_LuOIvwDWshVuPQS_2VNE_cIQx4Oy5zw/edit) -* Rust: [sigstore/sigstore-rs](https://github.com/sigstore/sigstore-rs) \ No newline at end of file +* Rust: [sigstore/sigstore-rs](https://github.com/sigstore/sigstore-rs) diff --git a/content/en/docs/about/security.md b/content/en/about/security.md similarity index 99% rename from content/en/docs/about/security.md rename to content/en/about/security.md index 5ed60a87..dee3d7cd 100644 --- a/content/en/docs/about/security.md +++ b/content/en/about/security.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore description: '' title: Security Model @@ -78,4 +79,4 @@ Clients like Cosign only need to find the correct Rekor entry to verify the arti - If an OIDC identity or OIDC provider is compromised, Fulcio might issue unauthorized certificates. However, these certificates are useless unless they are published to the certificate transparency log, so such compromise can be detected. - If Fulcio is compromised, it might issue unauthorized certificates. However, like before, these should be detectable. -- If no third parties monitor the logs, then any misbehavior by Rekor and Fulcio might go undetected. \ No newline at end of file +- If no third parties monitor the logs, then any misbehavior by Rekor and Fulcio might go undetected. diff --git a/content/en/docs/about/support.md b/content/en/about/support.md similarity index 96% rename from content/en/docs/about/support.md rename to content/en/about/support.md index 8e7753a0..7144a25a 100644 --- a/content/en/docs/about/support.md +++ b/content/en/about/support.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore description: '' title: Get Help @@ -29,4 +30,4 @@ Each repository has a `CODEOWNERS` file describing current maintainers. Join our # Asking questions -We welcome questions! You can either join the [Slack community][sc] and post them on `#general` channel or open a GitHub issue in the relevant repository. \ No newline at end of file +We welcome questions! You can either join the [Slack community][sc] and post them on `#general` channel or open a GitHub issue in the relevant repository. diff --git a/content/en/docs/about/threat-model.md b/content/en/about/threat-model.md similarity index 99% rename from content/en/docs/about/threat-model.md rename to content/en/about/threat-model.md index 120a1b5e..67e3e0b7 100644 --- a/content/en/docs/about/threat-model.md +++ b/content/en/about/threat-model.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore description: '' title: Threat Model @@ -133,4 +134,4 @@ That policy should cover: * Which Sigstore instance(s) do you trust, and how do you retrieve the key material for those instances? * How do you handle revocation? -The answers will be different in different settings. For instance, a small organization may be able to meet their security needs by requiring signatures from one fixed party, with a blocklist for revoked artifacts. A large package repository may need to manage signing identities that change frequently over time. We hope to provide more detailed guidance for a variety of settings in future documentation. \ No newline at end of file +The answers will be different in different settings. For instance, a small organization may be able to meet their security needs by requiring signatures from one fixed party, with a blocklist for revoked artifacts. A large package repository may need to manage signing identities that change frequently over time. We hope to provide more detailed guidance for a variety of settings in future documentation. diff --git a/content/en/docs/about/tooling.md b/content/en/about/tooling.md similarity index 97% rename from content/en/docs/about/tooling.md rename to content/en/about/tooling.md index a3f004ca..86f37608 100644 --- a/content/en/docs/about/tooling.md +++ b/content/en/about/tooling.md @@ -1,4 +1,5 @@ --- +type: docs category: About sigstore description: '' features: @@ -34,4 +35,4 @@ An identity layer that checks if you're who you say you are. It lets clients req ### Policy Controller An admission controller for Kubernetes for enforcing policy on -containers allowed to run. \ No newline at end of file +containers allowed to run. diff --git a/content/en/docs/certificate_authority/_index.html b/content/en/certificate_authority/_index.html similarity index 94% rename from content/en/docs/certificate_authority/_index.html rename to content/en/certificate_authority/_index.html index 5fc51a59..cada4bda 100644 --- a/content/en/docs/certificate_authority/_index.html +++ b/content/en/certificate_authority/_index.html @@ -1,4 +1,5 @@ --- +type: docs title: "Certificate Authority" description: "Documentation for Fulcio" lead: "" diff --git a/content/en/docs/certificate_authority/cert-transparency-log-info.md b/content/en/certificate_authority/cert-transparency-log-info.md similarity index 69% rename from content/en/docs/certificate_authority/cert-transparency-log-info.md rename to content/en/certificate_authority/cert-transparency-log-info.md index 84b010fd..994c13b5 100644 --- a/content/en/docs/certificate_authority/cert-transparency-log-info.md +++ b/content/en/certificate_authority/cert-transparency-log-info.md @@ -1,7 +1,8 @@ --- +type: docs category: Certificate authority title: Transparency Log Info weight: 1709 --- -Review Fulcio's [transparency log information](https://github.com/sigstore/fulcio/blob/main/docs/ctlog.md) on GitHub. \ No newline at end of file +Review Fulcio's [transparency log information](https://github.com/sigstore/fulcio/blob/main/docs/ctlog.md) on GitHub. diff --git a/content/en/docs/certificate_authority/cert_specification.md b/content/en/certificate_authority/cert_specification.md similarity index 92% rename from content/en/docs/certificate_authority/cert_specification.md rename to content/en/certificate_authority/cert_specification.md index 8bcc8d83..effcd72f 100644 --- a/content/en/docs/certificate_authority/cert_specification.md +++ b/content/en/certificate_authority/cert_specification.md @@ -1,7 +1,8 @@ --- +type: docs category: Certificate authority title: Certificate Specification weight: 1725 --- -Review Fulcio's [certificate specification](https://github.com/sigstore/fulcio/blob/main/docs/certificate-specification.md) on GitHub. \ No newline at end of file +Review Fulcio's [certificate specification](https://github.com/sigstore/fulcio/blob/main/docs/certificate-specification.md) on GitHub. diff --git a/content/en/docs/certificate_authority/certificate-issuing-overview.md b/content/en/certificate_authority/certificate-issuing-overview.md similarity index 99% rename from content/en/docs/certificate_authority/certificate-issuing-overview.md rename to content/en/certificate_authority/certificate-issuing-overview.md index 9eb1b0b7..3576bf25 100644 --- a/content/en/docs/certificate_authority/certificate-issuing-overview.md +++ b/content/en/certificate_authority/certificate-issuing-overview.md @@ -1,4 +1,5 @@ --- +type: docs category: Certificate authority menuTitle: Certificate Issuing title: Certificate Issuing Overview @@ -112,4 +113,4 @@ See [Certificate Transparency Log Information](https://github.com/sigstore/fulci ## 7 — Return certificate to client -![Fulcio return the certificate to the client](/fulcio-7-return-to-client.png) \ No newline at end of file +![Fulcio return the certificate to the client](/fulcio-7-return-to-client.png) diff --git a/content/en/docs/certificate_authority/hsm-support.md b/content/en/certificate_authority/hsm-support.md similarity index 66% rename from content/en/docs/certificate_authority/hsm-support.md rename to content/en/certificate_authority/hsm-support.md index f0ef668b..ae3f8006 100644 --- a/content/en/docs/certificate_authority/hsm-support.md +++ b/content/en/certificate_authority/hsm-support.md @@ -1,7 +1,8 @@ --- +type: docs category: Certificate authority title: HSM Support weight: 1720 --- -Review Fulcio's [HSM support](https://github.com/sigstore/fulcio/blob/main/docs/certificate-specification.md) on GitHub. \ No newline at end of file +Review Fulcio's [HSM support](https://github.com/sigstore/fulcio/blob/main/docs/certificate-specification.md) on GitHub. diff --git a/content/en/docs/certificate_authority/oidc-in-fulcio.md b/content/en/certificate_authority/oidc-in-fulcio.md similarity index 98% rename from content/en/docs/certificate_authority/oidc-in-fulcio.md rename to content/en/certificate_authority/oidc-in-fulcio.md index fed8a442..fbaf8bce 100644 --- a/content/en/docs/certificate_authority/oidc-in-fulcio.md +++ b/content/en/certificate_authority/oidc-in-fulcio.md @@ -1,4 +1,5 @@ --- +type: docs category: Certificate authority menuTitle: Using OIDC Tokens title: OIDC Usage in Fulcio @@ -168,4 +169,4 @@ Additionally, the configuration must include `SubjectDomain`, for example `examp * The issuer in the configuration must partially match the domain in the configuration. The top level domain and second level domain must match. The user who updates the Fulcio configuration must also have control over both the issuer and domain configuration fields (Verified either manually or through an ACME-style challenge). -`SubjectDomain` is appended to `sub` to form an email, `sub@SubjectDomain`, and included as a SAN email address. \ No newline at end of file +`SubjectDomain` is appended to `sub` to form an email, `sub@SubjectDomain`, and included as a SAN email address. diff --git a/content/en/docs/certificate_authority/overview.md b/content/en/certificate_authority/overview.md similarity index 94% rename from content/en/docs/certificate_authority/overview.md rename to content/en/certificate_authority/overview.md index 0beb53ed..b0f1ec22 100644 --- a/content/en/docs/certificate_authority/overview.md +++ b/content/en/certificate_authority/overview.md @@ -1,4 +1,5 @@ --- +type: docs category: Certificate authority menuTitle: Overview title: Fulcio @@ -13,4 +14,4 @@ Fulcio was designed to run as a centralized, public-good instance, auditable by Fulcio is being developed as part of the sigstore project. Join us on our [Slack channel](https://sigstore.slack.com/) (need an [invite](https://links.sigstore.dev/slack-invite)?) -You can learn more about Fulcio in the [Fulcio repo](https://github.com/sigstore/fulcio) and the [repo docs](https://github.com/sigstore/fulcio/tree/main/docs). \ No newline at end of file +You can learn more about Fulcio in the [Fulcio repo](https://github.com/sigstore/fulcio) and the [repo docs](https://github.com/sigstore/fulcio/tree/main/docs). diff --git a/content/en/docs/certificate_authority/release-log.md b/content/en/certificate_authority/release-log.md similarity index 80% rename from content/en/docs/certificate_authority/release-log.md rename to content/en/certificate_authority/release-log.md index d5be80ef..1f92c3dd 100644 --- a/content/en/docs/certificate_authority/release-log.md +++ b/content/en/certificate_authority/release-log.md @@ -1,7 +1,8 @@ --- +type: docs category: Certificate authority title: Release Log weight: 1715 --- -Review Fulcio's [Release log](https://github.com/sigstore/fulcio/releases) on GitHub. \ No newline at end of file +Review Fulcio's [Release log](https://github.com/sigstore/fulcio/releases) on GitHub. diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md deleted file mode 100644 index 064e9bd8..00000000 --- a/content/en/docs/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -category: About sigstore -description: Documentation for sigstore -menuTitle: Overview -title: Sigstore -weight: 1 ---- \ No newline at end of file diff --git a/content/en/docs/logging/pluggable-types.md b/content/en/docs/logging/pluggable-types.md deleted file mode 100644 index b8ced9e7..00000000 --- a/content/en/docs/logging/pluggable-types.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -category: Transparency Log -title: Pluggable Types -weight: 1830 ---- - -Rekor supports pluggable types (aka different schemas) for entries stored in the transparency log. This will allow you to develop your own manifest type in your preferred formatting style (json|yaml|xml). - -### Currently supported types - -The list of currently supported types and their schema is [maintained in the repository](https://github.com/sigstore/rekor/tree/main/pkg/types#currently-supported-types). - -## Base schema - -The base schema for all types is modeled off of the schema used by Kubernetes and can be found in `openapi.yaml` as `#/definitions/ProposedEntry`: - -``` -definitions: - ProposedEntry: - type: object - discriminator: kind - properties: - kind: - type: string - required: - - kind -``` - -The `kind` property is a [discriminator](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-13) that is used to differentiate between different pluggable types. Types can have one or more versions of the schema supported concurrently by the same Rekor instance; an example implementation can be seen in `rekord.go`. - -## Adding support for a new type - -To add a new type (called `newType` in this example): - -1. Add a new definition in `openapi.yaml` that is a derived type of ProposedEntry (expressed in the `allOf` list seen below); for example: - -```yaml -newType: - type: object - description: newType object - allOf: - - $ref: "#/definitions/ProposedEntry" - - properties: - version: - type: string - metadata: - type: object - additionalProperties: true - data: - type: object - $ref: "pkg/types/newType/newType_schema.json" - required: - - version - - data - additionalProperties: false -``` - -> Note: the `$ref` feature can be used to refer to an externally defined JSON schema document; however it is also permitted to describe the entirety of the type in valid Swagger (aka OpenAPI) v2 format within `openapi.yaml`. - -2. Create a subdirectory under `pkg/types/` with your type name (e.g. `newType`) as a new Go package - -3. In this new Go package, define a struct that implements the `TypeImpl` interface as defined in `pkg/types/types.go`: - -```go -type TypeImpl interface { - CreateProposedEntry(context.Context, version string, ArtifactProperties) (models.ProposedEntry, error) - DefaultVersion() string - SupportedVersions() []string - IsSupportedVersion(version string) bool - UnmarshalEntry(pe models.ProposedEntry) (EntryImpl, error) -} -``` - -- `CreateProposedEntry` creates an instance of a proposed entry based on the specified API version and the provided artifact properties -- `DefaultVersion` returns the default API version string across all types (to be used if a caller does not specify an explicit version) -- `SupportedVersions` returns the list of all API version strings that can currently be inserted into the log. -- `IsSupportedVersion` returns a boolean denoting whether the specified version could be inserted into the log -- `UnmarshalEntry` will be called with a pointer to a struct that was automatically generated for the type defined in `openapi.yaml` by the [go-swagger](http://github.com/go-swagger/go-swagger) tool used by Rekor - - This struct will be defined in the generated file at `pkg/generated/models/newType.go` (where `newType` is replaced with the name of the type you are adding) - - This method should return a pointer to an instance of a struct that implements the `EntryImpl` interface as defined in `pkg/types/types.go`, or a `nil` pointer with an error specified - -Also, the `Kind` constant must return the _exact_ same string as you named your new type in `openapi.yaml` (e.g. "`newType`") - -4. Also in this Go package, provide an implementation of the `EntryImpl` interface as defined in `pkg/types/entries.go`: - -```go -type EntryImpl interface { - APIVersion() string // the supported versions for this implementation - IndexKeys() ([]string, error) // the keys that should be added to the external index for this entry - Canonicalize(ctx context.Context) ([]byte, error) // marshal the canonical entry to be put into the tlog - Unmarshal(e models.ProposedEntry) error // unmarshal the abstract entry into the specific struct for this versioned type - CreateFromArtifactProperties(context.Context, ArtifactProperties) (models.ProposedEntry, error) - Verifier() (pki.PublicKey, error) - Insertable() (bool, error) // denotes whether the entry that was unmarshalled has the writeOnly fields required to validate and insert into the log -} -``` - -- `APIVersion` should return a version string that identifies the version of the type supported by the Rekor server -- `IndexKeys` should return a `[]string` containing the keys that are stored in the search index that should map to this log entry's ID. -- `Canonicalize` should return a `[]byte` containing the canonicalized contents representing the entry. The canonicalization of contents is important as we should have one record per unique signed object in the transparency log. -- `Unmarshal` will be called with a pointer to a struct that was automatically generated for the type defined in `openapi.yaml` by the [go-swagger](http://github.com/go-swagger/go-swagger) tool used by Rekor - - This method should validate the contents of the struct to ensure any string or cross-field dependencies are met to successfully insert an entry of this type into the transparency log -- `CreateFromArtifactProperties` returns a proposed entry of this specific entry implementation given the provided artifact properties -- `Verifier` returns the verification material that was used to verify the digital signature -- `Insertable` introspects the entry and determines if the object is sufficiently hydrated to make a new entry into the log. Entry instances that are created by reading the contents stored in the log may not be sufficiently hydrated. - -5. In the Go package you have created for the new type, be sure to add an entry in the `TypeMap` in `github.com/sigstore/rekor/pkg/types` for your new type in the `init` method for your package. The key for the map is the unique string used to define your type in `openapi.yaml` (e.g. `newType`), and the value for the map is the name of a factory function for an instance of `TypeImpl`. - -```go -func init() { - types.TypeMap.Set("newType", NewEntry) -} -``` - -6. Add an entry to `pluggableTypeMap` in `cmd/server/app/serve.go` that provides a reference to your package. This ensures that the `init` function of your type (and optionally, your version implementation) will be called before the server starts to process incoming requests and therefore will be added to the map that is used to route request processing for different types. - -7. After adding sufficient unit & integration tests, submit a pull request to `sigstore/rekor` for review and addition to the codebase. - -## Adding a new version of the `Rekord` type - -To add new version of the default `Rekord` type: - -1. Create a new subdirectory under `pkg/types/rekord/` for the new version - -2. If there are changes to the Rekord schema for this version, create a new JSON schema document and add a reference to it within the `oneOf` clause in `rekord_schema.json`. If there are no changes, skip this step. - -3. Provide an implementation of the `EntryImpl` interface as defined in `pkg/types/types.go` for the new version. - -4. In your package's `init` method, ensure there is a call to `SemVerToFacFnMap.Set()` which provides the link between the valid _semver_ ranges that your package can successfully process and the factory function that creates an instance of a struct for your new version. - -5. Add an entry to `pluggableTypeMap` in `cmd/server/app/serve.go` that provides a reference to the Go package implementing the new version. This ensures that the `init` function will be called before the server starts to process incoming requests and therefore will be added to the map that is used to route request processing for different types. - -6. After adding sufficient unit & integration tests, submit a pull request to `sigstore/rekor` for review and addition to the codebase. \ No newline at end of file diff --git a/content/en/docs/key_management/_index.html b/content/en/key_management/_index.html similarity index 95% rename from content/en/docs/key_management/_index.html rename to content/en/key_management/_index.html index f24b9dcd..f70a7846 100644 --- a/content/en/docs/key_management/_index.html +++ b/content/en/key_management/_index.html @@ -1,4 +1,5 @@ --- +type: docs title: "Key Management" description: "Documentation for key management with KMS providers" lead: "" diff --git a/content/en/docs/key_management/hardware-based-tokens.md b/content/en/key_management/hardware-based-tokens.md similarity index 99% rename from content/en/docs/key_management/hardware-based-tokens.md rename to content/en/key_management/hardware-based-tokens.md index 0ec6532b..eb694145 100644 --- a/content/en/docs/key_management/hardware-based-tokens.md +++ b/content/en/key_management/hardware-based-tokens.md @@ -1,4 +1,5 @@ --- +type: docs category: Key management title: Hardware Tokens weight: 515 @@ -263,4 +264,4 @@ uCPMJZqsNyWMmfksjulR9XAQvBCImkXncw== $ openssl verify -CAfile chain.pem key.crt key.crt: OK -``` \ No newline at end of file +``` diff --git a/content/en/docs/key_management/import-keypair.md b/content/en/key_management/import-keypair.md similarity index 98% rename from content/en/docs/key_management/import-keypair.md rename to content/en/key_management/import-keypair.md index 8175ff52..0471f825 100644 --- a/content/en/docs/key_management/import-keypair.md +++ b/content/en/key_management/import-keypair.md @@ -1,4 +1,5 @@ --- +type: docs category: Key management title: Importing Key Pairs weight: 510 @@ -29,4 +30,4 @@ $ cosign sign --key import-cosign.key $IMAGE_DIGEST Enter password for private key: tlog entry created with index: ***** Pushing signature to: ***** -``` \ No newline at end of file +``` diff --git a/content/en/docs/key_management/overview.md b/content/en/key_management/overview.md similarity index 99% rename from content/en/docs/key_management/overview.md rename to content/en/key_management/overview.md index 07bdd037..5a0c07e0 100644 --- a/content/en/docs/key_management/overview.md +++ b/content/en/key_management/overview.md @@ -1,4 +1,5 @@ --- +type: docs category: Key management title: Overview weight: 500 @@ -219,4 +220,4 @@ If you enabled `transit` secret engine at different path with the use of `-path` ```shell $ TRANSIT_SECRET_ENGINE_PATH="someotherpath" cosign generate-key-pair --kms hashivault://testkey -``` \ No newline at end of file +``` diff --git a/content/en/docs/key_management/signing_with_self-managed_keys.md b/content/en/key_management/signing_with_self-managed_keys.md similarity index 98% rename from content/en/docs/key_management/signing_with_self-managed_keys.md rename to content/en/key_management/signing_with_self-managed_keys.md index 50e25504..745459d4 100644 --- a/content/en/docs/key_management/signing_with_self-managed_keys.md +++ b/content/en/key_management/signing_with_self-managed_keys.md @@ -1,4 +1,5 @@ --- +type: docs category: Key management title: Signing with Self-Managed Keys weight: 505 @@ -46,4 +47,4 @@ This section shows traditional key signing from a key pair: $ cosign sign --key cosign.key user/demo Enter password for private key: Pushing signature to: index.docker.io/user/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig -``` \ No newline at end of file +``` diff --git a/content/en/docs/logging/CLI.md b/content/en/logging/CLI.md similarity index 99% rename from content/en/docs/logging/CLI.md rename to content/en/logging/CLI.md index 23e255f3..ee9c306d 100644 --- a/content/en/docs/logging/CLI.md +++ b/content/en/logging/CLI.md @@ -1,4 +1,5 @@ --- +type: docs category: Transparency Log title: CLI weight: 1825 @@ -92,4 +93,4 @@ For example: ```bash rekor-cli search --rekor_server https://rekor.sigstore.dev --sha sha256:e2e90d1a25f90a3156a27f00f3a4179578e3132ed4f010dc3498d09175b6071a -``` \ No newline at end of file +``` diff --git a/content/en/docs/logging/_index.html b/content/en/logging/_index.html similarity index 94% rename from content/en/docs/logging/_index.html rename to content/en/logging/_index.html index e4b49c45..1ae3628c 100644 --- a/content/en/docs/logging/_index.html +++ b/content/en/logging/_index.html @@ -1,4 +1,5 @@ --- +type: docs title: "Transparency Log" description: "Documentation for Rekor" lead: "" diff --git a/content/en/docs/logging/installation.md b/content/en/logging/installation.md similarity index 98% rename from content/en/docs/logging/installation.md rename to content/en/logging/installation.md index 3553e3eb..706ee2e1 100644 --- a/content/en/docs/logging/installation.md +++ b/content/en/logging/installation.md @@ -1,4 +1,5 @@ --- +type: docs category: Transparency Log title: Installation weight: 1805 @@ -149,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](/rekor/CLI/). \ No newline at end of file +Congratulations! Your local Rekor server is now running. You can interact with it using the [Rekor CLI](/rekor/CLI/). diff --git a/content/en/docs/logging/overview.md b/content/en/logging/overview.md similarity index 94% rename from content/en/docs/logging/overview.md rename to content/en/logging/overview.md index 341e02c1..8f83bea5 100644 --- a/content/en/docs/logging/overview.md +++ b/content/en/logging/overview.md @@ -1,4 +1,5 @@ --- +type: docs category: Transparency Log description: The Rekor overview menuTitle: Overview @@ -31,4 +32,5 @@ Learn more about transparency logs [here](https://transparency.dev/), and about There are few options for auditing and monitoring the Rekor log. We've built a monitor that runs on GitHub Actions, [Rekor monitor](https://github.com/sigstore/rekor-monitor). Follow the instructions to set up a new repository and use the [provided reusable workflow](https://github.com/sigstore/rekor-monitor/blob/main/.github/workflows/reusable_monitoring.yml) to audit the log. You can also monitor the log for specified identities, though this feature is a work in progress and supports a limited set of identities and entry types. -You can also run [omniwitness](https://github.com/transparency-dev/witness/tree/main/cmd/omniwitness) to audit the log, built by the team who created Trillian, which provides Rekor's verifiable log. +You can also run [omniwitness](https://github.com/transparency-dev/witness/tree/main/cmd/omniwitness) to +audit the log, built by the team who created Trillian, which provides Rekor's verifiable log. diff --git a/content/en/logging/pluggable-types.md b/content/en/logging/pluggable-types.md new file mode 100644 index 00000000..9b854c0f --- /dev/null +++ b/content/en/logging/pluggable-types.md @@ -0,0 +1,134 @@ +--- +type: docs +category: Transparency Log +title: Pluggable Types +weight: 1830 +--- + +Rekor supports pluggable types (aka different schemas) for entries stored in the transparency log. This will allow you to develop your own manifest type in your preferred formatting style (json|yaml|xml). + +## Currently supported types + +The list of currently supported types and their schema is [maintained in the repository](https://github.com/sigstore/rekor/tree/main/pkg/types#currently-supported-types). + +## Base schema + +The base schema for all types is modeled off of the schema used by Kubernetes and can be found in `openapi.yaml` as `#/definitions/ProposedEntry`: + +```bash +definitions: + ProposedEntry: + type: object + discriminator: kind + properties: + kind: + type: string + required: + - kind +``` + +The `kind` property is a [discriminator](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-13) that is used to differentiate between different pluggable types. Types can have one or more versions of the schema supported concurrently by the same Rekor instance; an example implementation can be seen in `rekord.go`. + +## Adding support for a new type + +To add a new type (called `newType` in this example): + +1. Add a new definition in `openapi.yaml` that is a derived type of ProposedEntry (expressed in the `allOf` list seen below); for example: + + ```yaml + newType: + type: object + description: newType object + allOf: + - $ref: "#/definitions/ProposedEntry" + - properties: + version: + type: string + metadata: + type: object + additionalProperties: true + data: + type: object + $ref: "pkg/types/newType/newType_schema.json" + required: + - version + - data + additionalProperties: false + ``` + + > Note: the `$ref` feature can be used to refer to an externally defined JSON schema document; however it is also permitted to describe the entirety of the type in valid Swagger (aka OpenAPI) v2 format within `openapi.yaml`. + +2. Create a subdirectory under `pkg/types/` with your type name (e.g. `newType`) as a new Go package + +3. In this new Go package, define a struct that implements the `TypeImpl` interface as defined in `pkg/types/types.go`: + + ```go + type TypeImpl interface { + CreateProposedEntry(context.Context, version string, ArtifactProperties) (models.ProposedEntry, error) + DefaultVersion() string + SupportedVersions() []string + IsSupportedVersion(version string) bool + UnmarshalEntry(pe models.ProposedEntry) (EntryImpl, error) + } + ``` + + - `CreateProposedEntry` creates an instance of a proposed entry based on the specified API version and the provided artifact properties + - `DefaultVersion` returns the default API version string across all types (to be used if a caller does not specify an explicit version) + - `SupportedVersions` returns the list of all API version strings that can currently be inserted into the log. + - `IsSupportedVersion` returns a boolean denoting whether the specified version could be inserted into the log + - `UnmarshalEntry` will be called with a pointer to a struct that was automatically generated for the type defined in `openapi.yaml` by the [go-swagger](http://github.com/go-swagger/go-swagger) tool used by Rekor + - This struct will be defined in the generated file at `pkg/generated/models/newType.go` (where `newType` is replaced with the name of the type you are adding) + - This method should return a pointer to an instance of a struct that implements the `EntryImpl` interface as defined in `pkg/types/types.go`, or a `nil` pointer with an error specified + + Also, the `Kind` constant must return the _exact_ same string as you named your new type in `openapi.yaml` (e.g. "`newType`") + +4. Also in this Go package, provide an implementation of the `EntryImpl` interface as defined in `pkg/types/entries.go`: + + ```go + type EntryImpl interface { + APIVersion() string // the supported versions for this implementation + IndexKeys() ([]string, error) // the keys that should be added to the external index for this entry + Canonicalize(ctx context.Context) ([]byte, error) // marshal the canonical entry to be put into the tlog + Unmarshal(e models.ProposedEntry) error // unmarshal the abstract entry into the specific struct for this versioned type + CreateFromArtifactProperties(context.Context, ArtifactProperties) (models.ProposedEntry, error) + Verifier() (pki.PublicKey, error) + Insertable() (bool, error) // denotes whether the entry that was unmarshalled has the writeOnly fields required to validate and insert into the log + } + ``` + + - `APIVersion` should return a version string that identifies the version of the type supported by the Rekor server + - `IndexKeys` should return a `[]string` containing the keys that are stored in the search index that should map to this log entry's ID. + - `Canonicalize` should return a `[]byte` containing the canonicalized contents representing the entry. The canonicalization of contents is important as we should have one record per unique signed object in the transparency log. + - `Unmarshal` will be called with a pointer to a struct that was automatically generated for the type defined in `openapi.yaml` by the [go-swagger](http://github.com/go-swagger/go-swagger) tool used by Rekor + - This method should validate the contents of the struct to ensure any string or cross-field dependencies are met to successfully insert an entry of this type into the transparency log + - `CreateFromArtifactProperties` returns a proposed entry of this specific entry implementation given the provided artifact properties + - `Verifier` returns the verification material that was used to verify the digital signature + - `Insertable` introspects the entry and determines if the object is sufficiently hydrated to make a new entry into the log. Entry instances that are created by reading the contents stored in the log may not be sufficiently hydrated. + +5. In the Go package you have created for the new type, be sure to add an entry in the `TypeMap` in `github.com/sigstore/rekor/pkg/types` for your new type in the `init` method for your package. The key for the map is the unique string used to define your type in `openapi.yaml` (e.g. `newType`), and the value for the map is the name of a factory function for an instance of `TypeImpl`. + + ```go + func init() { + types.TypeMap.Set("newType", NewEntry) + } + ``` + +6. Add an entry to `pluggableTypeMap` in `cmd/server/app/serve.go` that provides a reference to your package. This ensures that the `init` function of your type (and optionally, your version implementation) will be called before the server starts to process incoming requests and therefore will be added to the map that is used to route request processing for different types. + +7. After adding sufficient unit & integration tests, submit a pull request to `sigstore/rekor` for review and addition to the codebase. + +## Adding a new version of the `Rekord` type + +To add new version of the default `Rekord` type: + +1. Create a new subdirectory under `pkg/types/rekord/` for the new version + +2. If there are changes to the Rekord schema for this version, create a new JSON schema document and add a reference to it within the `oneOf` clause in `rekord_schema.json`. If there are no changes, skip this step. + +3. Provide an implementation of the `EntryImpl` interface as defined in `pkg/types/types.go` for the new version. + +4. In your package's `init` method, ensure there is a call to `SemVerToFacFnMap.Set()` which provides the link between the valid _semver_ ranges that your package can successfully process and the factory function that creates an instance of a struct for your new version. + +5. Add an entry to `pluggableTypeMap` in `cmd/server/app/serve.go` that provides a reference to the Go package implementing the new version. This ensures that the `init` function will be called before the server starts to process incoming requests and therefore will be added to the map that is used to route request processing for different types. + +6. After adding sufficient unit & integration tests, submit a pull request to `sigstore/rekor` for review and addition to the codebase. diff --git a/content/en/docs/logging/sharding.md b/content/en/logging/sharding.md similarity index 74% rename from content/en/docs/logging/sharding.md rename to content/en/logging/sharding.md index 039fb97c..ce29812d 100644 --- a/content/en/docs/logging/sharding.md +++ b/content/en/logging/sharding.md @@ -1,4 +1,5 @@ --- +type: docs category: Transparency Log description: Sharding the Rekor Log title: Sharding @@ -21,7 +22,6 @@ Sharding the log allows for: * Easier and faster querying for entries from the tree * Easier scaling and platform migrations - ## How does this impact user experience? It shouldn't! @@ -33,8 +33,7 @@ Querying by log index works as well, since log indices are distinct and increase For more details around sharding, see the original [design doc](https://docs.google.com/document/d/1QBTyK-wquplNdeUB5_aqztQHigJOepCvd-4FL4H-zl8/edit?resourcekey=0-grdVbSltkTvpNvhj03laCQ#heading=h.al4txfo7pxwl)! -_Note: You'll need to join the sigstore-dev@googlegroups.com Google group for access to the doc._ - +_Note: You'll need to join the [sigstore-dev@googlegroups.com](https://groups.google.com/g/sigstore-dev/about) Google group for access to the doc._ ## How do I shard the Rekor log? @@ -42,40 +41,42 @@ _Note: You'll need to join the sigstore-dev@googlegroups.com Google group for ac This is necessary because you'll need the length of the current shard later on, so new entries can't be added while sharding is in progress. Follow these steps to shard the log: + 1. Stop all traffic to Rekor so new entries can't be added to the log 2. Store the tree ID and length of the current active shard: -``` -CURRENT_TREE_ID=$(rekor-cli loginfo --format json | jq -r .TreeID) -CURRENT_SHARD_LENGTH=$(rekor-cli loginfo --format json | jq -r .TreeSize) -``` + + ```bash + CURRENT_TREE_ID=$(rekor-cli loginfo --format json | jq -r .TreeID) + CURRENT_SHARD_LENGTH=$(rekor-cli loginfo --format json | jq -r .TreeSize) + ``` 3. Connect to the production cluster. Port-forward the running `trillian_logserver` container and run the [createtree](https://github.com/google/trillian/blob/master/cmd/createtree/main.go) script. This will create a new Merkle Tree which will become the new active shard. -``` -kubectl port-forward -n trillian-system deploy/trillian-log-server 8090:8090 -# This is the Tree ID of the new active shard -NEW_TREE_ID=$(createtree --admin_server localhost:8090) -``` + ```bash + kubectl port-forward -n trillian-system deploy/trillian-log-server 8090:8090 + # This is the Tree ID of the new active shard + NEW_TREE_ID=$(createtree --admin_server localhost:8090) + ``` 4. Update the Rekor `sharding-config` ConfigMap with details of the inactive shard: -``` -kubectl edit configmap sharding-config -n rekor-system -``` + ```bash + kubectl edit configmap sharding-config -n rekor-system + ``` -Append the following onto the `sharding-config.yaml` key (it will be empty if this is the first shard): + Append the following onto the `sharding-config.yaml` key (it will be empty if this is the first shard): -```yaml -- treeID: $CURRENT_TREE_ID - treeLength: $CURRENT_SHARD_LENGTH -``` + ```yaml + - treeID: $CURRENT_TREE_ID + treeLength: $CURRENT_SHARD_LENGTH + ``` 5. In your rekor-server [Deployment](https://github.com/sigstore/rekor/blob/main/config/rekor.yaml), update the `--trillian_log_server.tlog_id` flag to point to the new Tree ID. -``` -"--trillian_log_server.tlog_id=$NEW_TREE_ID", -``` + ```bash + "--trillian_log_server.tlog_id=$NEW_TREE_ID", + ``` 6. Redeploy Rekor to the cluster with these changes. @@ -85,7 +86,7 @@ Append the following onto the `sharding-config.yaml` key (it will be empty if th ## Identifier Definitions: EntryID, UUID, LogID, Log Index -An **EntryID** is the unique identifier for an artifact in Rekor. It is made up of two parts, the TreeID and UUID: +An **EntryID** is the unique identifier for an artifact in Rekor. It is made up of two parts, the TreeID and UUID: `EntryID = TreeID (8 byte hex) + UUID (32 byte hex)` @@ -93,4 +94,4 @@ The **TreeID** refers to the specific trillian tree (also known as log or shard) The **UUID** refers to the specific artifact within a specified tree. -The **LogIndex** of an artifact identifies the index or order in which the artifact was entered into a specific tree. \ No newline at end of file +The **LogIndex** of an artifact identifies the index or order in which the artifact was entered into a specific tree. diff --git a/content/en/docs/logging/sign-upload.md b/content/en/logging/sign-upload.md similarity index 99% rename from content/en/docs/logging/sign-upload.md rename to content/en/logging/sign-upload.md index 330f813d..4b078fba 100644 --- a/content/en/docs/logging/sign-upload.md +++ b/content/en/logging/sign-upload.md @@ -1,4 +1,5 @@ --- +type: docs category: Transparency Log title: Signing and Uploading Other Types weight: 1835 diff --git a/content/en/docs/logging/verify-release.md b/content/en/logging/verify-release.md similarity index 99% rename from content/en/docs/logging/verify-release.md rename to content/en/logging/verify-release.md index c1c48e2d..b0421d5c 100644 --- a/content/en/docs/logging/verify-release.md +++ b/content/en/logging/verify-release.md @@ -1,4 +1,5 @@ --- +type: docs category: Transparency Log title: Verifying Binaries weight: 1840 @@ -201,4 +202,4 @@ So we now know that the binary you downloaded was signed by the individual in co In turn, this account has 2FA enabled and is monitored for misuse, since records are transparent within the public Rekor transparency log. -There is a lot more we could do well. Using the sha256 digest you could retrieve the signing materials for a release binary, *even* if you sourced the binary from elsewhere! \ No newline at end of file +There is a lot more we could do well. Using the sha256 digest you could retrieve the signing materials for a release binary, *even* if you sourced the binary from elsewhere! diff --git a/content/en/docs/policy-controller/_index.html b/content/en/policy-controller/_index.html similarity index 94% rename from content/en/docs/policy-controller/_index.html rename to content/en/policy-controller/_index.html index 7f1dde23..f2a9aba0 100644 --- a/content/en/docs/policy-controller/_index.html +++ b/content/en/policy-controller/_index.html @@ -1,4 +1,5 @@ --- +type: docs title: "Policy Controller" description: "Documentation for Kubernetes Policy Controller" lead: "" diff --git a/content/en/docs/policy-controller/installation.md b/content/en/policy-controller/installation.md similarity index 96% rename from content/en/docs/policy-controller/installation.md rename to content/en/policy-controller/installation.md index df67cdf6..0000a36e 100644 --- a/content/en/docs/policy-controller/installation.md +++ b/content/en/policy-controller/installation.md @@ -1,4 +1,5 @@ --- +type: docs category: Kubernetes Policy Controller menuTitle: Installation title: Installation @@ -29,4 +30,4 @@ The `policy-controller` resyncs `ClusterImagePolicies` by default every 10 hours Customize the resync period by using the `--policy-resync-period` argument and defining a duration for the `policy-webhook` deployment. See the [Golang time package's ParseDuration](https://pkg.go.dev/time#example-ParseDuration) for example duration string formats. -See the [Configuring policy-controller ClusterImagePolicy](/policy-controller/overview/#configuring-policy-controller-clusterimagepolicy) instructions for more details on configuration. \ No newline at end of file +See the [Configuring policy-controller ClusterImagePolicy](/policy-controller/overview/#configuring-policy-controller-clusterimagepolicy) instructions for more details on configuration. diff --git a/content/en/docs/policy-controller/overview.md b/content/en/policy-controller/overview.md similarity index 99% rename from content/en/docs/policy-controller/overview.md rename to content/en/policy-controller/overview.md index 353ec666..1e31c1ad 100644 --- a/content/en/docs/policy-controller/overview.md +++ b/content/en/policy-controller/overview.md @@ -1,4 +1,5 @@ --- +type: docs category: Kubernetes Policy Controller menuTitle: Overview title: Kubernetes Policy Controller @@ -998,4 +999,4 @@ Authority that matches `tsa-organization` and `commonName`. and TrustRoot. We will fix this in a newer API version, but can't do it without reving the API version due to backwards compatibility. In CIP the ctLog refers to Rekor, which in TrustRoot was correctly named `tLog`. Whereas in TrustRoot -the `ctLog` correctly refers to the `Certificate Transparency Log`. \ No newline at end of file +the `ctLog` correctly refers to the `Certificate Transparency Log`. diff --git a/content/en/docs/policy-controller/sample-policies.md b/content/en/policy-controller/sample-policies.md similarity index 99% rename from content/en/docs/policy-controller/sample-policies.md rename to content/en/policy-controller/sample-policies.md index 5988005f..a56081b2 100644 --- a/content/en/docs/policy-controller/sample-policies.md +++ b/content/en/policy-controller/sample-policies.md @@ -1,4 +1,5 @@ --- +type: docs category: Kubernetes Policy Controller menuTitle: Sample Policies title: Sample Policies @@ -153,4 +154,4 @@ Next, sign your container using the KMS key and Cosign. ``` cosign sign --key "awskms:///<< arn of kms key >>" "${IMAGE}" -``` \ No newline at end of file +``` diff --git a/content/en/docs/signing/_index.html b/content/en/signing/_index.html similarity index 94% rename from content/en/docs/signing/_index.html rename to content/en/signing/_index.html index 2827b800..3eeab4c4 100644 --- a/content/en/docs/signing/_index.html +++ b/content/en/signing/_index.html @@ -1,4 +1,5 @@ --- +type: docs title: "Signing" description: "Documentation for Cosign" lead: "" diff --git a/content/en/docs/signing/git_support.md b/content/en/signing/git_support.md similarity index 99% rename from content/en/docs/signing/git_support.md rename to content/en/signing/git_support.md index 576db1c7..af2c806f 100644 --- a/content/en/docs/signing/git_support.md +++ b/content/en/signing/git_support.md @@ -1,4 +1,5 @@ --- +type: docs category: Signing title: Git Support weight: 133 @@ -79,4 +80,4 @@ 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 -``` \ No newline at end of file +``` diff --git a/content/en/docs/signing/gitsign.md b/content/en/signing/gitsign.md similarity index 99% rename from content/en/docs/signing/gitsign.md rename to content/en/signing/gitsign.md index df76be73..22d76a09 100644 --- a/content/en/docs/signing/gitsign.md +++ b/content/en/signing/gitsign.md @@ -1,4 +1,5 @@ --- +type: docs category: Signing menuTitle: Signing Git Commits title: Gitsign @@ -253,4 +254,4 @@ fatal: failed to write commit object By default, gitsign will try and write to your terminal if there is a TTY available. If you are running in an environment where there is not a TTY, you can use the `GITSIGN_LOG` environment variable to tee logs into a readable -location for debugging. \ No newline at end of file +location for debugging. diff --git a/content/en/docs/signing/other_types.md b/content/en/signing/other_types.md similarity index 99% rename from content/en/docs/signing/other_types.md rename to content/en/signing/other_types.md index 2bb59e65..ba19b640 100644 --- a/content/en/docs/signing/other_types.md +++ b/content/en/signing/other_types.md @@ -1,4 +1,5 @@ --- +type: docs category: Signing title: Signing Other Types weight: 140 @@ -289,4 +290,4 @@ $ crane manifest user/demo@sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa20fa } ] } -``` \ No newline at end of file +``` diff --git a/content/en/docs/signing/overview.md b/content/en/signing/overview.md similarity index 98% rename from content/en/docs/signing/overview.md rename to content/en/signing/overview.md index d2b79d0c..5413bc04 100644 --- a/content/en/docs/signing/overview.md +++ b/content/en/signing/overview.md @@ -1,4 +1,5 @@ --- +type: docs category: Signing title: Overview weight: 110 @@ -99,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/). \ No newline at end of file +For information on custom roots of trust, see [Configuring Cosign with Custom Components](/system_config/custom_components/). diff --git a/content/en/docs/signing/pkcs11.md b/content/en/signing/pkcs11.md similarity index 99% rename from content/en/docs/signing/pkcs11.md rename to content/en/signing/pkcs11.md index 6723f8f6..1e687bd3 100644 --- a/content/en/docs/signing/pkcs11.md +++ b/content/en/signing/pkcs11.md @@ -1,4 +1,5 @@ --- +type: docs category: Signing title: PKCS11 Tokens weight: 136 @@ -96,4 +97,4 @@ The following checks were performed on each of these signatures: - The code-signing certificate was verified using trusted certificate authority certificates [{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}] -``` \ No newline at end of file +``` diff --git a/content/en/docs/signing/quickstart.md b/content/en/signing/quickstart.md similarity index 99% rename from content/en/docs/signing/quickstart.md rename to content/en/signing/quickstart.md index 903123a2..bfc22dc7 100644 --- a/content/en/docs/signing/quickstart.md +++ b/content/en/signing/quickstart.md @@ -1,4 +1,5 @@ --- +type: docs category: Signing description: '' menuTitle: Quick Start @@ -124,4 +125,4 @@ Attestations provide an additional semantic-layer on top of plain cryptographic 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/). \ No newline at end of file +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/). diff --git a/content/en/docs/signing/signing_with_blobs.md b/content/en/signing/signing_with_blobs.md similarity index 99% rename from content/en/docs/signing/signing_with_blobs.md rename to content/en/signing/signing_with_blobs.md index 16d2e7d2..85dec432 100644 --- a/content/en/docs/signing/signing_with_blobs.md +++ b/content/en/signing/signing_with_blobs.md @@ -1,4 +1,5 @@ --- +type: docs category: Signing title: Signing Blobs weight: 130 @@ -94,4 +95,4 @@ You can sign it with the normal `cosign sign` command and flags: ```shell $ cosign sign gcr.io/user/demo/artifact -``` \ No newline at end of file +``` diff --git a/content/en/docs/signing/signing_with_containers.md b/content/en/signing/signing_with_containers.md similarity index 99% rename from content/en/docs/signing/signing_with_containers.md rename to content/en/signing/signing_with_containers.md index 5ee1b84b..85695f58 100644 --- a/content/en/docs/signing/signing_with_containers.md +++ b/content/en/signing/signing_with_containers.md @@ -1,4 +1,5 @@ --- +type: docs category: Signing title: Signing Containers weight: 125 @@ -345,4 +346,4 @@ Some registries support deletion too (DockerHub does not): ```shell $ cosign clean $IMAGE -``` \ No newline at end of file +``` diff --git a/content/en/docs/system_config/_index.html b/content/en/system_config/_index.html similarity index 95% rename from content/en/docs/system_config/_index.html rename to content/en/system_config/_index.html index b7d91bcb..fe98d886 100644 --- a/content/en/docs/system_config/_index.html +++ b/content/en/system_config/_index.html @@ -1,4 +1,5 @@ --- +type: docs title: "System Configuration" description: "Documentation for installing and configuring Sigstore tools" lead: "" diff --git a/content/en/docs/system_config/custom_components.md b/content/en/system_config/custom_components.md similarity index 99% rename from content/en/docs/system_config/custom_components.md rename to content/en/system_config/custom_components.md index 86b2c095..da1cc3ac 100644 --- a/content/en/docs/system_config/custom_components.md +++ b/content/en/system_config/custom_components.md @@ -1,4 +1,5 @@ --- +type: docs category: System configuration title: Configuring Cosign with Custom Components weight: 955 @@ -20,4 +21,4 @@ There are three options to configure Cosign to verify against custom components: | ---------- | ------------------- | | SIGSTORE_REKOR_PUBLIC_KEY | This specifies an out of band PEM-encoded public key to use for a custom Rekor. | | SIGSTORE_ROOT_FILE | This specifies an out of band PEM-encoded X.509 certificate for a custom Fulcio root certificate. | -| SIGSTORE_CT_LOG_PUBLIC_KEY_FILE | This specifies an out of band PEM-encoded or DER formatted public key for a custom CT log. | \ No newline at end of file +| SIGSTORE_CT_LOG_PUBLIC_KEY_FILE | This specifies an out of band PEM-encoded or DER formatted public key for a custom CT log. | diff --git a/content/en/docs/system_config/installation.md b/content/en/system_config/installation.md similarity index 98% rename from content/en/docs/system_config/installation.md rename to content/en/system_config/installation.md index 579ab671..b0754b53 100644 --- a/content/en/docs/system_config/installation.md +++ b/content/en/system_config/installation.md @@ -1,4 +1,5 @@ --- +type: docs category: System configuration title: Installation weight: 950 @@ -16,7 +17,7 @@ The resulting binary will be placed at `$GOPATH/bin/cosign` (or `$GOBIN/cosign`, ## With the Cosign binary or rpm/dpkg package -Download the binary for your platform at https://github.com/sigstore/cosign/releases/latest. +Download the binary for your platform from the [Cosign releases page](https://github.com/sigstore/cosign/releases/latest). ```console # binary @@ -201,4 +202,4 @@ COSIGN_DIGEST=$(crane digest gcr.io/projectsigstore/cosign:$COSIGN_VERSION) cosign verify gcr.io/projectsigstore/cosign@$COSIGN_DIGEST \ --certificate-identity keyless@projectsigstore.iam.gserviceaccount.com --certificate-oidc-issuer https://accounts.google.com -``` \ No newline at end of file +``` diff --git a/content/en/docs/system_config/public_deployment.md b/content/en/system_config/public_deployment.md similarity index 98% rename from content/en/docs/system_config/public_deployment.md rename to content/en/system_config/public_deployment.md index 816ff3d4..f084cd39 100644 --- a/content/en/docs/system_config/public_deployment.md +++ b/content/en/system_config/public_deployment.md @@ -1,4 +1,5 @@ --- +type: docs category: System configuration title: Public Deployment weight: 960 @@ -36,4 +37,4 @@ To use this instance, follow the steps below: In order to revert, we need to clear the local TUF root data and re-initialize with the default production TUF root data. 1. `rm -r ~/.sigstore` -1. `cosign initialize` \ No newline at end of file +1. `cosign initialize` diff --git a/content/en/docs/system_config/registry_support.md b/content/en/system_config/registry_support.md similarity index 97% rename from content/en/docs/system_config/registry_support.md rename to content/en/system_config/registry_support.md index 356a655a..60b9aa88 100644 --- a/content/en/docs/system_config/registry_support.md +++ b/content/en/system_config/registry_support.md @@ -1,4 +1,5 @@ --- +type: docs category: System configuration title: Registry Support weight: 965 @@ -69,4 +70,4 @@ This will replace the repo in the provided image: export COSIGN_REPOSITORY=gcr.io/my-new-repo gcr.io/user-vmtest2/demo -> gcr.io/my-new-repo/demo:sha256-DIGEST.sig ``` -So the signature for `gcr.io/user-vmtest2/demo` will be stored in `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`. \ No newline at end of file +So the signature for `gcr.io/user-vmtest2/demo` will be stored in `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`. diff --git a/content/en/docs/system_config/specifications.md b/content/en/system_config/specifications.md similarity index 98% rename from content/en/docs/system_config/specifications.md rename to content/en/system_config/specifications.md index 0b012206..9152b577 100644 --- a/content/en/docs/system_config/specifications.md +++ b/content/en/system_config/specifications.md @@ -1,4 +1,5 @@ --- +type: docs category: System configuration title: Specifications weight: 970 @@ -49,4 +50,4 @@ That looks like: } } ``` -**Note:** This can be generated for an image reference using `cosign generate `. \ No newline at end of file +**Note:** This can be generated for an image reference using `cosign generate `. diff --git a/content/en/docs/verifying/_index.html b/content/en/verifying/_index.html similarity index 94% rename from content/en/docs/verifying/_index.html rename to content/en/verifying/_index.html index a6aeabd7..affc8a79 100644 --- a/content/en/docs/verifying/_index.html +++ b/content/en/verifying/_index.html @@ -1,4 +1,5 @@ --- +type: docs title: "Verifying" description: "Documentation for Verifying with OpenID Connect" lead: "" diff --git a/content/en/docs/verifying/attestation.md b/content/en/verifying/attestation.md similarity index 99% rename from content/en/docs/verifying/attestation.md rename to content/en/verifying/attestation.md index 2cfdcecd..2b9740af 100644 --- a/content/en/docs/verifying/attestation.md +++ b/content/en/verifying/attestation.md @@ -1,4 +1,5 @@ --- +type: docs category: verifying title: In-Toto Attestations weight: 310 @@ -160,4 +161,4 @@ There are 2 number of errors occurred during the validation: - unexpected time: 2021-10-11T17:16:08Z - unexpected data: foo Error: 2 validation errors occurred -``` \ No newline at end of file +``` diff --git a/content/en/docs/verifying/inspecting.md b/content/en/verifying/inspecting.md similarity index 99% rename from content/en/docs/verifying/inspecting.md rename to content/en/verifying/inspecting.md index f4279e28..0f281f05 100644 --- a/content/en/docs/verifying/inspecting.md +++ b/content/en/verifying/inspecting.md @@ -1,4 +1,5 @@ --- +type: docs category: verifying menuTitle: Inspecting Gitsign Signatures title: Inspecting Gitsign Commit Signatures @@ -326,4 +327,4 @@ nPkp+Sy1EwIwdOulWop3oJV/Qo7fau0mlsy0MCm3lBgyxo2lpAaI4gFRxGE2GhpV -----END CERTIFICATE----- ``` -Notice that **the Rekor entry uses the same certificate that was used to generate the Git commit signature**. This can be used to correlate the two messages, even though they signed different content! \ No newline at end of file +Notice that **the Rekor entry uses the same certificate that was used to generate the Git commit signature**. This can be used to correlate the two messages, even though they signed different content! diff --git a/content/en/docs/verifying/timestamps.md b/content/en/verifying/timestamps.md similarity index 97% rename from content/en/docs/verifying/timestamps.md rename to content/en/verifying/timestamps.md index 325e7c5c..c8c971d8 100644 --- a/content/en/docs/verifying/timestamps.md +++ b/content/en/verifying/timestamps.md @@ -1,4 +1,5 @@ --- +type: docs category: verifying title: Timestamps weight: 305 @@ -51,7 +52,7 @@ cosign verify --timestamp-certificate-chain ts_chain.pem ### mTLS connection to the TSA server -`cosign sign` accepts several additional optional parameters to pass the CA certificate of +`cosign sign` and `cosign sign-blob` accept several additional optional parameters to pass the CA certificate of the TSA server in cases where it uses a custom CA, or to establish a mutual TLS connection to the TSA server: ``` --timestamp-client-cacert='': @@ -75,4 +76,4 @@ the TSA server in cases where it uses a custom CA, or to establish a mutual TLS We would like to make timestamps immutable in Rekor. While the clock would not be verifiable and trust isn't distributed, it would make mutations to the timestamps detectable. We would like to include a signed timestamp, which could come from a 3rd party TSA or from a TSA operated by the Sigstore community, in the Rekor entry so that it is a part of the Merkle leaf hash computation and therefore becomes immutable. -As a long-term goal, we would also like to support [Roughtime](https://blog.cloudflare.com/roughtime/), which distributes trust across a set of time providers. The specification is still under development, and there are opportunities for client & server development. \ No newline at end of file +As a long-term goal, we would also like to support [Roughtime](https://blog.cloudflare.com/roughtime/), which distributes trust across a set of time providers. The specification is still under development, and there are opportunities for client & server development. diff --git a/content/en/docs/verifying/verify.md b/content/en/verifying/verify.md similarity index 99% rename from content/en/docs/verifying/verify.md rename to content/en/verifying/verify.md index 3a35336e..9b555dfc 100644 --- a/content/en/docs/verifying/verify.md +++ b/content/en/verifying/verify.md @@ -1,4 +1,5 @@ --- +type: docs category: verifying title: Verifying Signatures weight: 300 @@ -249,4 +250,4 @@ For more details on how the `bundle` annotation is formatted, review the Cosign To verify the `bundle` annotation, follow these steps: 1. Marshal the `bundle` Payload into JSON 1. Canonicalize the payload by following RFC 8785 rules -1. Verify the canonicalized payload and signedEntryTimestamp against the transparency logs public key \ No newline at end of file +1. Verify the canonicalized payload and signedEntryTimestamp against the transparency logs public key diff --git a/i18n/en.yaml b/i18n/en.yaml new file mode 100644 index 00000000..723e08c3 --- /dev/null +++ b/i18n/en.yaml @@ -0,0 +1,17 @@ +- id: get-started + translation: "Get Started" + +- id: on-this-page + translation: "On this page" + +- id: search-text + translation: "Search" + +- id: 404-title + translation: "404 — Page not found." + +- id: 404-text + translation: "The page you are looking for doesn't exist or has been moved." + +- id: browse + translation: "Browse" diff --git a/layouts/404.html b/layouts/404.html index 76d447a2..5ce85e74 100644 --- a/layouts/404.html +++ b/layouts/404.html @@ -1,10 +1,10 @@ {{ define "main" }} -
+
-

{{ i18n "404-title" }}

-

{{ i18n "404-text" }}

+

{{ i18n "404-title" }}

+

{{ i18n "404-text" }}

-{{ end }} \ No newline at end of file +{{ end }} diff --git a/layouts/index.redirects b/layouts/index.redirects deleted file mode 100644 index 12b93503..00000000 --- a/layouts/index.redirects +++ /dev/null @@ -1,13 +0,0 @@ -{{- range $p := .Site.Pages -}} -{{- range .Aliases }} -{{ . }} {{ $p.RelPermalink }} -{{- end }} -{{- end }} - -# /docs/1.0/prologue/ /docs/1.0/prologue/introduction/ -# /docs/1.0/help/ /docs/1.0/help/how-to-update/ -# /docs/1.0/ /docs/1.0/prologue/introduction/ -# /docs/ /docs/1.0/prologue/introduction/ -# -# /docs/0.1/* https://v0-1-0--doks-versioning-poc.netlify.app/docs/0.1/:splat 200 -# /docs/0.2/* https://v0-2-0--doks-versioning-poc.netlify.app/docs/0.2/:splat 200 diff --git a/layouts/partials/sidebar/auto-collapsible-menu.html b/layouts/partials/sidebar/auto-collapsible-menu.html index dd4ab49c..3b90f76c 100644 --- a/layouts/partials/sidebar/auto-collapsible-menu.html +++ b/layouts/partials/sidebar/auto-collapsible-menu.html @@ -1,9 +1,9 @@
    {{ $currentPage := . -}} - {{ $section := $currentPage.Section -}} - {{ range (where .Site.Sections "Section" "in" $section) }} - {{ range .Sections }} + + + {{ range site.Sections }} {{ $active := in $currentPage.RelPermalink .RelPermalink }}
{{ end }} - {{ end }} diff --git a/static/_redirects b/static/_redirects new file mode 100644 index 00000000..87605eb7 --- /dev/null +++ b/static/_redirects @@ -0,0 +1,40 @@ +#redirect file for moved web pages. +/main-concepts /tooling +/history /research +/cosign/overview /signing/quickstart +/cosign/installation /system_config/installation +/cosign/signing_with_self-managed_keys /key_management/signing_with_self-managed_keys +/cosign/import-keypair /key_management/import-keypair +/cosign/signing_with_containers /signing/signing_with_containers +/cosign/verify /verifying/verify +/cosign/signing_with_blobs /signing/signing_with_blobs +/cosign/other_types /signing/other_types +/cosign/attestation /verifying/attestation +/cosign/git_support /signing/git_support +/cosign/timestamps /verifying/timestamps +/cosign/hardware-based-tokens /key_management/hardware-based-tokens +/cosign/openid_signing /signing/overview +/cosign/registry_support /system_config/registry_support +/cosign/kms_support /key_management/overview +/cosign/specifications /system_config/specifications +/cosign/custom_components /system_config/custom_components +/cosign/public_deployment /system_config/public_deployment +/cosign/pkcs11 /signing/pkcs11 +/gitsign/overview /signing/gitsign +/gitsign/installation /signing/gitsign +/gitsign/usage /signing/gitsign +/gitsign/inspecting /verifying/inspecting +/fulcio/overview /certificate_authority/overview +/fulcio/oidc-in-fulcio /certificate_authority/oidc-in-fulcio +/fulcio/certificate-issuing-overview /certificate_authority/certificate-issuing-overview +/fulcio/release-log /certificate_authority/release-log/ +/rekor/overview /logging/overview +/rekor/public-instance /logging/overview +/rekor/installation /logging/installation +/rekor/CLI /logging/CLI +/rekor/sign-upload /logging/sign-upload +/rekor/pluggable-types /logging/pluggable-types +/rekor/verify-release /logging/verify-release +/rekor/sharding /logging/sharding +/community /contributing +