diff --git a/docs/content/docs/configuration/configuration.md b/docs/content/docs/configuration/configuration.md index 44c8a44d3..f63d05c05 100644 --- a/docs/content/docs/configuration/configuration.md +++ b/docs/content/docs/configuration/configuration.md @@ -111,6 +111,10 @@ default-secrets: "mysecrets" # the configuration in the secrets section. default-secrets-plugin: "kubernetes.secret" +# Use the signer configuration name mysigner. +# If not specified, bundles and invocation images cannot be signed. +default-signer: "mysigner" + # Defines storage accounts storage: # The storage account name @@ -145,6 +149,23 @@ secrets: # The subscription where the vault is defined subscription-id: "${env.AZURE_SUBSCRIPTION_ID}" +# Define signers +signer: + # The signer name + - name: "mysigner" + + # The plugin used to sign bundles + plugin: "cosign" + + # Additional configuration for the signer + # These values vary depending on the plugin used + config: + # Path to the public key + publickey: /home/porter/cosign.pub + + # Path to the public key + privatekey: /home/porter/cosign.key + # Log command output to a file in PORTER_HOME/logs/ logs: # Log command output to a file diff --git a/docs/content/docs/operations/signing-bundles.md b/docs/content/docs/operations/signing-bundles.md index ef6a00bfc..c4db1232a 100644 --- a/docs/content/docs/operations/signing-bundles.md +++ b/docs/content/docs/operations/signing-bundles.md @@ -4,4 +4,89 @@ description: Signing of Porter bundles weight: 7 --- -TODO \ No newline at end of file +Porter has built-in support for signing bundles and the associated invocation image using [Cosign] or [Notation]. +Learn how to configure Porter to sign bundles. + +- [Cosign](#cosign) +- [Notation](#notation) + +## Cofiguration + +### Cosign + +#### Prerequisites + +1. Cosign is installed and is available on the on the `PATH`. +2. A key-pair for signing is available. + +Instructions on for the install Cosign can be found on the [Cosign Installation page](https://docs.sigstore.dev/system_config/installation/), and instructions on how to generate a key-pair can be found in the [Cosign Quickstart Guide](https://docs.sigstore.dev/signing/quickstart/#signing-with-a-generated-key). + +🚧 Currently Porter does not support [Keyless Signing](https://docs.sigstore.dev/signing/overview/). + +#### Configuration + +Porter have to be configure to use [Cosign] to sign bundles and invocation images. All configuration is done through the [Porter config file](/docs/configuration/configuration/). To configure [Cosign] add the following to the configuration file. + +```yaml +# ~/.porter/config.yaml + +default-signer: "mysigner" + +signer: + - name: "mysigner" + plugin: "cosign" + config: + publickey: + privatekey: + + # Set the mode for fetching references from the registry. allowed: legacy, oci-1-1. + # If set to oci-1-1, experimental must be set the true. + # registrymode: legacy + + # Enable Cosign experimental features. + # Required if regsitrymode is set to oci-1-1. + # experimental: false + + # Allow signing of bundles in registries with expired or self-signed certificates. + # insecureregistry: false +``` + +### Notation + +#### Prerequisites + +1. Notation is installed and is available on the on the `PATH`. +2. A signing key and certificate have been configured. +3. A trust policy for verification have been configured. + +Instructions on for the install Notation can be found on the [Notation Installation page](https://notaryproject.dev/docs/user-guides/installation/cli/), and instructions on how to configure a signing key, certificate and trust policy can be found in the [Notation Quickstart Guide](https://notaryproject.dev/docs/quickstart-guides/quickstart-sign-image-artifact/). + +#### Configuration + +Porter have to be configure to use [Notation] to sign bundles and invocation images. All configuration is done through the [Porter config file](/docs/configuration/configuration/). To configure [Notation] add the following to the configuration file. + +```yaml +# ~/.porter/config.yaml + +default-signer: "mysigner" + +signer: + - name: "mysigner" + plugin: "notation" + config: + key: + + # Allow signing of bundles HTTP registries + # insecureregistry: false +``` + +## Sign bundle + +To sign run [porter publish](/cli/porter_publish/) with the `--sign-bundle` flag. + +## Verify bundle + +A bundle can be verified before installation by adding the `--verify-bundle` flag to [porter install](/cli/porter_publish/). + +[Cosign]: https://docs.sigstore.dev/signing/quickstart/ +[Notation]: https://notaryproject.dev/docs/quickstart-guides/quickstart-sign-image-artifact/ \ No newline at end of file