Red Hat OpenShift Container Platform

About configuring sigstore support

You can use the ClusterImagePolicy and ImagePolicy custom resource (CR) objects to enable and configure sigstore support for the entire cluster or a specific namespace.

The ClusterImagePolicy and ImagePolicy objects contain a policy that specifies the images and repositories to be verified by using sigstore tooling and how the signatures must be verified.

Cluster image policy. A cluster image policy object enables a cluster administrator to configure a sigstore signature verification policy for the entire cluster. When enabled, the Machine Config Operator (MCO) watches the ClusterImagePolicy object and updates the /etc/containers/policy.json and /etc/containers/registries.d/sigstore-registries.yaml files on all nodes in the cluster.

The default ClusterImagePolicy object, named openshift, provides sigstore support for the required Red Hat OpenShift Container Platform images in the quay.io/openshift-release-dev/ocp-release repository.

Image policy. An image policy enables a cluster administrator or application developer to configure a sigstore signature verification policy for a specific namespace. The MCO watches an ImagePolicy instance in different namespaces and creates or updates the /etc/crio/policies/<namespace>.json and /etc/containers/registries.d/sigstore-registries.yaml files on all nodes in the cluster.

If the image or repository in an image policy is nested under one of the images or repositories in a cluster image policy, only the policy from cluster image policy is applied. For example, if an image policy specifies example.com/global/image, and the cluster image policy specifies example.com/global, the namespace uses the policy from the cluster image policy. The image policy object is created and shows an error similar to the following message:
Example image policy with a conflicting image identity
```
API Version:  config.openshift.io/v1
Kind:         ImagePolicy
Name:         p0
Namespace:    mynamespace
# ...
Status:
  Conditions:
    Message: has conflicting scope(s) ["example.com/global/image"] that equal to or nest inside existing clusterimagepolicy, only policy from clusterimagepolicy scope(s) will be applied
    Reason: ConflictScopes
# ...
```

About cluster and image policy parameters

The following parameters apply to cluster and image policies. For information on using these parameters, see "Creating a cluster image policy CR" and "Creating an image policy CR."

scopes

Defines a list of repositories and images assigned to a policy. You must list at least one of the following scopes:

An individual image, by using a tag or digest, such as example.com/namespace/image:latest
A repository, by omitting the tag or digest, such as example.com
A repository namespace, such as example.com/namespace/
A registry host, by specifying only the host name and port number or a wildcard expression starting with *., such as *.example.com

If multiple scopes match a single scope in the same a cluster or image policy, the policy for only the most specific scope applies.

If a scoped image or repository in an image policy is nested under one of the scoped images or repositories in a cluster image policy, only the policy from cluster image policy is applied. However, the image policy object is created. For example, if an image policy specifies example.com/global/image, and the cluster image policy specifies example.com/global, the namespace inherits the policy from the cluster image policy.

policy

Contains configuration to allow images from the sources listed in scopes to be verified, and defines how images not matching the verification policy are treated. You must configure a rootOfTrust and optionally, a signedIdentity.

rootOfTrust: Specifies the root of trust for the policy. Configure either a public key, a Bring Your Own Public Key Infrastructure (BYOPKI) certificate, or a Fulcio certificate.
- publicKey: Indicates that the policy relies on a sigstore public key. You must specify a base64-encoded PEM format public key. You can optionally include Rekor verification.
- PKI Indicates that the policy relies on a certificate from your own public key infrastructure (PKI) that is compatible with Cosign Bring Your Own Public Key Infrastructure (BYOPKI) verification. You must specify a base64-encoded PEM format public key. BYOPKI enables you to validate container images using an existing X.509 certificate while aligning with Cosign’s bring-your-own PKI signing workflow.
- FulcioCAWithRekor: Indicates that the policy is based on a Fulcio certificate. You must specify the following parameters:
  - A base64-encoded PEM-format Fulcio CA
  - An OpenID Connect (OIDC) issuer
  - The email of the Fulcio authentication configuration
  - The Rekor verification
signedIdentity: Specifies the approach used to verify the image in the signature and the actual image itself. To configure a signed identity, you must specify one of the following parameters as the match policy:
- MatchRepoDigestOrExact. The image referenced in the signature must be in the same repository as the image itself. If the image carries a tag, the image referenced in the signature must match exactly. This is the default.
- MatchRepository. The image referenced in the signature must be in the same repository as the image itself. If the image carries a tag, the image referenced in the signature does not need to match exactly. This is useful to pull an image that contains the latest tag if the image is signed with a tag specifying an exact image version.
- ExactRepository. The image referenced in the signature must be in the same repository that is specified by the exactRepository parameter. The exactRepository parameter must be specified.
- RemapIdentity. If the scoped repository or image matches a specified prefix, that prefix is replaced by a specified signedPrefix. If the image identity does not match, the prefix is unchanged and no remapping takes place. This option can be used when verifying signatures for a mirror of some other repository namespace that preserves the vendor’s repository structure.
  
  The prefix and signedPrefix can be either host[:port] values that match the exact host[:port] string, repository namespaces, or repositories. The prefix and signedPrefix must not contain tags or digests. For example, to specify a single repository, use example.com/library/busybox and not busybox. To specify the parent namespace of example.com/library/busybox, you can use example.com/library.
  
  You must specify the following parameters:
  - prefix: Specifies the image prefix to be matched.
  - signedPrefix: Specifies the image prefix to be remapped, if needed.

About modifying or removing image policies

You can modify or remove a cluster image policy or an image policy by using the same commands as any other custom resource (CR) object.

You can modify an existing policy by editing the policy YAML and running an oc apply command on the file or directly editing the ClusterImagePolicy or ImagePolicy object. Both methods apply the changes in the same manner.

The default ClusterImagePolicy object, named openshift, provides sigstore support for the required Red Hat OpenShift Container Platform images. You must not remove or modify this cluster image policy object. Cluster image policy names beginning with openshift are reserved for future system use.

You can create multiple policies for a cluster or namespace. This allows you to create different policies for different images or repositories.

You can remove a policy by deleting the ClusterImagePolicy and ImagePolicy objects.