Secure supply chain
A secure supply chain infrastructure can verify the validity of its parts, or links. It lets users and developers show the chain of custody of its software components, or artifacts. It's an active approach to mitigate security issues.
The Sigstore project provides tools and infrastructure for this. It's for validating the integrity of the artifact supply chain.
Kubewarden uses cosign together with the fulcio and rekor infrastructure offered by the Sigstore project.
Cluster operators can configure Kubewarden to only run policies signed by trusted entities. Policy developers can sign their policies and publish them in a registry.
Prerequisites
In the following sections, you need a few tools to be installed.
These are so users can sign and verify OCI artifacts signatures.
The examples show the use of cosign and kwctl utilities for signing and inspecting policies.
Users may also want to use GitHub to sign their policies. In which case, they need to install Github actions
Keyless signing uses the default fulcio and rekor instances provided by the Sigstore project. Check the Sigstore documentation for details on how to use your own infrastructure for this, if needed.
Signing policies
Kubewarden recommends using Sigstore's cosign utility to signing policies.
This section shows a key-based method of signing policies.
Users need to generate a private-public key-pair for this.
The generated keys help to verify if the signed artifacts came from the expected user.
To generate this key-pair use this cosign generate-key-pair command:
cosign generate-key-pair
Resulting in a prompt to type and verify a password:
Enter password for private key: ●●●●●●●●
Enter password for private key again: ●●●●●●●●
Private key written to cosign.key
Public key written to cosign.pub
Now you can use this key to sign policies.
The private key file, cosign.key, shouldn't be shared.
This is a secret file only for use by the key owner for signing policies.
To sign a policy you can use cosign sign passing the --key command line argument with your private key file:
cosign sign --key cosign.key ghcr.io/kubewarden/policies/user-group-psp:latest
Resulting in a prompt for the password, for the specified private key:
an error occurred: no provider found for that key reference, will try to load key from disk...
Enter password for private key: ●●●●●●●●
Pushing signature to: ghcr.io/kubewarden/policies/user-group-psp
This command signs the policy by creating a new signature object. The signature object is then uploaded into the registry, with the policy. Now the policy is ready to use in a Kubewarden installation using signature verification.
The same policy can be signed multiple times, by the same user or different ones. These signatures are added to the signature object along with the original signature.
For more information about how the signing process works, check out the Sigstore project documentation.
Keyless signing
Often policies are automatically built in CI/CD pipelines. This complicates the key generation process. This Sigstore keyless workflow is for these situations. Instead of using long-lived singing keys, the keyless workflow uses certificate authorities (CAs) and certificate chains.
A short-lived certificate key is generated, and linked into a chain of trust. It's done by an identity challenge to confirm the signer's identity. The life of the certificate key is long enough for the signing to occur. The identity challenge is done by authenticating against an OpenID Connect (OIDC) provider. Sigstore's Fulcio public infrastructure is used for the chain of trust.
Signing uses Sigstore's cosign utility.
$ cosign sign ghcr.io/kubewarden/policies/user-group-psp:latest
cosign output
This signs the policy and pushes it to the repository. There are no keys generated as a byproduct.
How to sign artifacts in GitHub workflows
When using keyless signing, in a GitHub action,
cosign doesn't need the user to log in to an OIDC provider.
A GitHub token is available during the execution of the GitHub workflow.
It's used to authenticate the user and generate the ephemeral keys.
The signing process is the same used in the keyless mode.
This is an example of how the Kubewarden project signs its policies:
YAML describing Kubewarden policy signing
Policy developers can use the Kubewarden policy templates. They have GitHub actions to build, test, sign and publish policies.
Listing policy signatures
You can check signature in a published policy with kwctl inspect.
This shows the information about the policy and its signatures as shown below:
kwctl inspect registry://ghcr.io/kubewarden/policies/us....
Verifying policies
You can check if a policy is correctly signed with cosign or kwctl.
They have similar command line options for checking policy signatures.
To check if the binary is signed with a key, use kwctl like this:
$ kwctl verify -k cosign.pub ghcr.io/kubewarden/policies/user-group-psp:latest
2022-03-29T14:49:31.878180Z INFO kwctl::verify: Policy successfully verified
Or cosign :
$ cosign verify --key cosign.pub ghcr.io/kubewarden/policies/user-group-psp:latest
Verification for ghcr.io/kubewarden/policies/user-group-psp:latest --
The following checks were performed on each of these signatures:
- The cosign claims were validated
- The signatures were verified against the specified public key
- Any certificates were verified against the Fulcio roots.
[{"critical":{"identity":{"docker-reference":"ghcr.io/kubewarden/policies/user-group-psp"},"image":{"docker-manifest-digest":"sha256:af520a8ccee03811d426c48634b7007f1220c121cc23e14962bb64510585ce97"},"type":"cosign container image signature"},"optional":null}]
Configuring the policy server to check policy signatures
You can configure Kubewarden with a ConfigMap to only run trusted policies.
The ConfigMap structure described in Signature Config Reference.
It's used to verify a policy using kwctl.
The ConfigMap should define allowable configurations under the verification-config field.
For example, you want to run policies signed by the Kubewarden GitHub organization. Then a sample ConfigMap for this scenario would be:
$ cat kubewarden_signatures.yaml
You can use kwctl scaffold verification-config to generate a default verification configuration file for the ConfigMap:
$ kwctl scaffold verification-config > verification_config.yaml
$ cat verification_config.yaml
You can use this verification_config.yml to create the ConfigMap.
$ kubectl create configmap my-signatures-configuration --from-file==verification_config.yaml
configmap/my-signatures-configuration created
Then we can inspect with get configmap.
kubectl get configmap
After creating the ConfigMap to store the signature requirements, you can configure a Policy Server.
To start validating policy signatures by setting the ConfigMap name in the highlighted field verificationConfig.
apiVersion: policies.kubewarden.io/v1alpha2
kind: PolicyServer
metadata:
name: default
finalizers:
- kubewarden
spec:
image: ghcr.io/kubewarden/policy-server:v0.2.7
serviceAccountName: policy-server
replicas: 1
verificationConfig: your_configmap #name of the confimap with the signatures requirements
env:
- name: KUBEWARDEN_ENABLE_METRICS
value: "1"
- name: KUBEWARDEN_LOG_FMT
value: otlp
- name: "KUBEWARDEN_LOG_LEVEL"
value: "info"
If you deploy the default Policy Server using the kubewarden-defaults
Helm chart then you configure this field by setting the ConfigMap name in the
policyServer.verificationConfig value.
Now, the PolicyServer rejects untrusted AdmissionPolicies and ClusterAdmissionPolicies by refusing to start. You need to remove the untrusted policy, or change the signatures requirement, for a running PolicyServer.
Signature configuration reference
You can validate signature requirements contained in a file. Here is an example:
A file of signature requirements
Signature validation
The configuration above contains the two highlighted sections, allOf and anyOf:
-
allOf: The policy is trusted only if all signature requirements here are valid. -
anyOf: The policy is trusted if theminimumMatchescriterion is met. Above, theminimumMatchesfield is 2. So, at least two of the signature requirements must be met. The default value forminimumMatchesfield is1.
All the signatures requirements from allOf and the minimum number from anyOf must be met.
Public key validation
To check a policy is signed with the correct public key, you specify the key data and the owner of the key.
In this example, kind is set to pubKey and the key has the public key.
The owner field is optional, but can be useful to clarify who owns the key.
- kind: pubKey
owner: bob # optional
key: |
-----BEGIN PUBLIC KEY-----
MBFKHFDGHKIJH0CAQYIKoZIzj0DAQcDQgAEX0HFTtCfTtPmkx5p1RbDE6HJSGAVD
BVDF6SKFSF87AASUspkQsN3FO4iyWodCy5j3o0CdIJD/KJHDJFHDFIu6sA==
-----END PUBLIC KEY-----
Keyless signature validation
A policy signed in keyless mode doesn't have a public key we can verify.
You can still verify the policy with the OIDC data used during the signing process.
For that, it's necessary to define the signature validation as genericIssuer.
It's possible to verify information from the signature:
issuer(mandatory): this matches theIssuerattribute in the certificate generated by Fulcio. This shows the OIDC used to sign the policy.subject: field used to match theSubjectattribute in Fulcio's certificate. TheSubject(Fulcio) field contains the user used to authenticate against the OIDC provider. The verification field,subject, can have one of two sub fields:equal: theSubject(Fulcio) from the certificate must be equal to the value in the signature validation;urlPrefix: the certificate'sSubject(Fulcio) field value must be prefixed by the value defined in the signature validation.
Both the cosign verify and the kwctl inspect can show information about keyless signatures.
For example, this configuration means the policy must have a keyless signature from Alice using the GitHub OIDC:
- kind: genericIssuer
issuer: https://github.com/login/oauth
subject:
equal: alice@example.com
This configuration needs the policy to be signed in GitHub actions,
from a repository owned by the GitHub user flavio:
- kind: genericIssuer
issuer: https://token.actions.githubusercontent.com
subject:
urlPrefix: https://github.com/flavio
GitHub actions signature verification
The "kind", githubAction is to validate policies signed in GitHub Actions.
You can do this with the genericIssuer kind as well.
To simplify the signature requirement process, use two extra fields for githubAction:
owner(mandatory): GitHub ID of the user or organization to trustrepo: the name of the repository to trust
For example, the last snippet, using genericIssuer, could be rewritten as:
- kind: githubAction
owner: flavio
Signature annotations validation
All signature types can have other optional validation fields, annotations.
These fields are key/value data added by during the signing process.
With Kubewarden, you can ensure policies are signed by trusted users and have specific annotations.
The next validation checks 2 conditions for the policy:
- that it's signed with a specific key
- it has a production environment annotation.
- kind: pubKey
key: |
-----BEGIN PUBLIC KEY-----
MBFKHFDGHKIJH0CAQYIKoZIzj0DAQcDQgAEX0HFTtCfTtPmkx5p1RbDE6HJSGAVD
BVDF6SKFSF87AASUspkQsN3FO4iyWodCy5j3o0CdIJD/KJHDJFHDFIu6sA==
-----END PUBLIC KEY-----
annotations:
environment: production
Using a signature verification configuration file to check a policy OCI artifact
You can test if a policy passes verification using the verification config file.
Use the --verification-config-path flag of the kwctl verify command
$ cat signatures_requirements.yaml
apiVersion: v1
allOf:
- kind: pubKey
key: |
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5Q+cN1Jj2S7N05J4AXnqwP2DyzSg
Mc+raYce2Wthrd30MSgFtoh5ADAkCd/nML2Nx8UD9KBuASRb0gG5jXqgMQ==
-----END PUBLIC KEY-----
$ kwctl verify --verification-config-path signatures_requirements.yaml ghcr.io/kubewarden/policies/user-group-psp:latest
2022-03-29T17:34:37.847169Z INFO kwctl::verify: Policy successfully verified
This last example tests if a given policy came from the Kubewarden organization:
$ cat kubewarden_signatures.yaml
apiVersion: v1
allOf:
- kind: githubAction
owner: kubewarden
$ kwctl verify --verification-config-path kubewarden_signatures.yaml ghcr.io/kubewarden/policies/user-group-psp:latest
2022-03-29T18:07:39.062292Z INFO kwctl::verify: Policy successfully verified