// Module included in the following assemblies:
//
// * nodes/nodes-sigstore-using.adoc

:_mod-docs-content-type: CONCEPT
[id="nodes-sigstore-configure_{context}"]
= About configuring sigstore support

[role="_abstract"]
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.
+
[NOTE]
====
The default `ClusterImagePolicy` object, named `openshift`, provides sigstore support for the required {product-title} 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
[source,yaml]
----
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
# ...
----

[id="nodes-sigstore-configure-parameters_{context}"]
== 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.

[id="nodes-sigstore-configure-parameters-modify_{context}"]
== 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.

[NOTE]
====
The default `ClusterImagePolicy` object, named `openshift`, provides sigstore support for the required {product-title} 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.
