# Ratify support for Cosign signature verification at K8s admission ## Overview Currently Ratify supports verifying both Cosign keyed signature and keyless signature see https://ratify.dev/docs/1.0/external%20plugins/Verifier/cosign. This document only focus on the enterprise users who use keyed signature. Improvements on Keyless signature are not in the scope. The existing solution can only support verification using a single key. The configuration only support specifying key file path, however, we have scenarios that users manage keys in a KMS, such as Azure Key Vault (AKV). The existing solution does not support RSA key, which [cosign document](https://docs.sigstore.dev/key_management/signing_with_self-managed_keys/) states "Cosign supports RSA, ECDSA, and ED25519 keys. For RSA, Cosign only supports RSA PKCS#1.5 padded keys.", so if customs sign with RSA key, Ratify cannot verify it successfully. With keyed signature, users may configure custom rekor server to pubish transparent log, however it is not configurable today. ## User stories Bob, a DevOps engineer on the DC team at Contoso LLC, is tasked with securing containerized applications. The DC team opts for the Sigstore tooling called Cosign to sign the container images that they build. While Cosign is renowned for its keyless signing approach, Bob chooses not to use this method due to its reliance on other Sigstore infrastructures and security considerations, so Bob sets up a workflow that signs container images with Cosign keyed signatures. Bob wants to set up a policy that verifies container images signed with Cosign before deploying those images in AKS clusters. ### Verify images signed with keys stored in a KMS, such as AKV Some of images are signed with keys stored in a KMS, such as AKV, so Bob wants to set up the policy to use keys in a KMS for verification. ### Verify images signed with Self-Managed keys Some of images are signed with Self-Managed keys, so Bob wants to set up the policy to use Self-Managed keys for verification. ### Verify images with multiple keys Images can be signed by different teams using different keys, so Bob wants to set up the policy to verify images with multiple keys. ### Verify images signed with transparent logs uploaded to a Rekor server Contoso builds their own Rekor server for uploading transparent logs, so Bob wants to set up the policy to verify images with transparent logs uploaded to a specified Rekor server. ## Goals/Non-goals ### Goals - Provide users with a built-in rego policy that verifies images against Cosign signatures, and users just need to configure relevant parameters. - Users can update the parameters in real-time. - Support verifying images signed with multiple keys - Support verifying images with Keys managed in AKV - Support verifying images with Self-Managed keys - Support configure Rekor server ### Non-goals - Keyless signature - Distribution of public key - Policy in CI/CD pipelines - Policy at container runtime ## User experience ### Verify images signed with a public key stored in a KMS, such as AKV Prerequisites: - Ratify is installed - Gatekeeper is installed - Create a key named `myKey` in a AKV named`myAKV` - Ratify oras store is configured Steps: 1. Create and apply a KMS store resource with AKV as the provider, see below ```shell $ cat <<EOF | kubectl create -f - apiVersion: config.ratify.deislabs.io/v1beta1 kind: KeyManagementSystem metadata: name: azurekms spec: provider: azurekeyvault parameters: vaultName: myAKV keys: | array: - | keyName: myKey # Optional, fetch latest version if empty version: tenantID: myTenantID clientID: myClientID EOF ``` 2. Create and apply the cosign verfier resource, see below ```shell $ cat <<EOF | kubectl create -f - apiVersion: config.ratify.deislabs.io/v1beta1 kind: Verifier metadata: name: cosign spec: name: cosign artifactTypes: application/vnd.dev.cosign.artifact.sig.v1+json parameters: KMS: keys: - azurekms EOF ``` 3. Use default rego policy, which allows images to be deployed only if they pass all the verifications by verifiers ### Verify images signed with a Self-Managed public key 1. Create and apply a inline store resource, see below ```shell $ cat <<EOF | kubectl create -f - apiVersion: config.ratify.deislabs.io/v1beta1 kind: KeyManagementSystem metadata: name: inline-store spec: provider: inline parameters: publickKeys: | -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8nX MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8nX -----END PUBLIC KEY----- EOF ``` 2. Create and apply the cosign verfier resource, see below ```shell $ cat <<EOF | kubectl create -f - apiVersion: config.ratify.deislabs.io/v1beta1 kind: Verifier metadata: name: cosign spec: name: cosign artifactTypes: application/vnd.dev.cosign.artifact.sig.v1+json parameters: kms: keys: - inline-store EOF ``` 3. Use default rego policy, which allows images to be deployed only if they pass all the verifications by verifiers ### Verify images with multiple public keys 1. create a AKV KMS resource `azurekms` and an inline store `inline-store` as previous scenarios 2. create an addiontal AKV KMS resource `azurekms2` ```shell $ cat <<EOF | kubectl create -f - apiVersion: config.ratify.deislabs.io/v1beta1 kind: KeyManagementSystem metadata: name: azurekms2 spec: provider: azurekeyvault parameters: vaultName: myAKV2 keys: | array: - | keyName: myKey2 # Optional, fetch latest version if empty version: tenantID: myTenantID2 clientID: myClientID2 EOF ``` 2. Create and apply the cosign verfier resource, see below ```shell $ cat <<EOF | kubectl create -f - apiVersion: config.ratify.deislabs.io/v1beta1 kind: Verifier metadata: name: cosign spec: name: cosign artifactTypes: application/vnd.dev.cosign.artifact.sig.v1+json parameters: kms: keys: - inline-store - azurekms - azurekms2 EOF ``` 3. Use default rego policy, which allows images to be deployed only if they pass all the verifications by verifiers ### Verify images signed with transparent logs uploaded to a Rekor server Reuse the KMS resources that created in previous scenarios, and configure the sigstore rekor server. ```shell $ cat <<EOF | kubectl create -f - apiVersion: config.ratify.deislabs.io/v1beta1 kind: Verifier metadata: name: cosign spec: name: cosign artifactTypes: application/vnd.dev.cosign.artifact.sig.v1+json parameters: kms: keys: - inline-store - azurekms - azurekms2 rekorURL: https://rekor.sigstore.dev EOF ``` ## Requirements ### Functional Requirements | Feature | Priority | Dependency | | --------------------------------------------------------------------------- | -------- | ---------- | | Support verifying images signed by Cosign with multiple local keys | P0 | | | Support verifying images signed by Cosign with multiple Keys managed in AKV | P0 | | | Support verifying Cosign signature uploaded to the transparent log | P1 | | ## Apendix