Red Hat OpenShift Container Platform

Creating a cluster image policy CR

A cluster administrator can use a ClusterImagePolicy custom resource (CR) 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 the nodes in the cluster.

The following example shows general guidelines on how to configure a ClusterImagePolicy object. For more details on the parameters, see "About cluster and image policy parameters."

The default ClusterImagePolicy object, named openshift, provides sigstore support for the required Red Hat OpenShift Container Platform images, which are stored in the quay.io/openshift-release-dev/ocp-release repository. You must not remove or modify this cluster image policy object. Cluster image policy names beginning with openshift are reserved for future system use.

Prerequisites

You have a sigstore-supported public key infrastructure (PKI) key, a Bring Your Own Public Key Infrastructure (BYOPKI) certificate, or provide a Cosign public and private key pair for signing operations.
You have a signing process in place to sign your images.
You have access to a registry that supports Cosign signatures, if you are using Cosign signatures.
If a mirror registry is configured for the Red Hat OpenShift Container Platform release image repositories, quay.io/openshift-release-dev/ocp-release and quay.io/openshift-release-dev/ocp-v4.0-art-dev, you must mirror the sigstore signatures for the Red Hat OpenShift Container Platform release images into your mirror registry. Otherwise, the default openshift cluster image policy, which enforces signature verification for the release repository, blocks the ability of the Cluster Version Operator to move the CVO pod to new nodes, preventing the node update.

You can use the oc image mirror command to mirror the signatures. For example:
```
$ oc image mirror quay.io/openshift-release-dev/ocp-release:sha256-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef.sig \
mirror.com/image/repo:sha256-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef.sig
```

Procedure

Create a cluster image policy object similar to the following examples. See "About image policy parameters" for specific details on these parameters.

The following example cluster image policy object uses a public key policy and the MatchRepoDigestOrExact match policy:
```
apiVersion: config.openshift.io/v1
kind: ClusterImagePolicy
metadata:
  name: p1
spec:
  scopes:
    - example.com
  policy:
    rootOfTrust:
      policyType: PublicKey
      publicKey:
        keyData: a2V5RGF0YQ==
        rekorKeyData: cmVrb3JLZXlEYXRh
    signedIdentity:
      matchPolicy: MatchRepoDigestOrExact
```
where:
kind

Specifies that the configuration is for a ClusterImagePolicy object.

spec.scopes

Specifies a list of repositories or images assigned to this policy. In a cluster image policy, make sure that the policy does not block the deployment of the Red Hat OpenShift Container Platform images in the quay.io/openshift-release-dev/ocp-release and quay.io/openshift-release-dev/ocp-v4.0-art-dev repositories. Images in these repositories are required for cluster operation.

spec.policy

Specifies the parameters that define how the images are verified.

spec.policy.rootOfTrust

Specifies a root of trust for the policy.

spec.policy.rootOfTrust.policyType

Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a Fulcio certificate. This example uses a public key with Rekor verification.

spec.policy.rootOfTrust.publicKey.keyData

For a public key policy, specifies a base64-encoded public key in the PEM format. The maximum length is 8192 characters.

spec.policy.rootOfTrust.publicKey.rekorKeyData

Specifies a base64-encoded Rekor public key in the PEM format. The maximum length is 8192 characters. This parameter is optional.

spec.policy.signedIdentity

Specifies the process to verify the identity in the signature and the actual image identity. This parameter is optional. Specify one of the following processes:

MatchRepoDigestOrExact.

MatchRepository.

ExactRepository. The exactRepository parameter must be specified.

RemapIdentity. The prefix and signedPrefix parameters must be specified.
The following example cluster image policy object uses a BYOPKI policy and the MatchRepository match policy:
```
apiVersion: config.openshift.io/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: pki-policy
spec:
  scopes:
  - example.io
  policy:
    rootOfTrust:
      policyType: PKI
      pki:
        caRootsData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk....URS0tLS0t
        caIntermediatesData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1J....lDQVRFLS0tLS0=
        pkiCertificateSubject:
          email: email@example.com
          hostname: myhost.example.com
    signedIdentity:
      matchPolicy: MatchRepository
```
where:
kind

Specifies that the configuration is for a ClusterImagePolicy object.

spec.scopes

Specifies a list of repositories or images assigned to this policy. In a cluster image policy, make sure that the policy does not block the deployment of the Red Hat OpenShift Container Platform images in the quay.io/openshift-release-dev/ocp-release and quay.io/openshift-release-dev/ocp-v4.0-art-dev repositories. Images in these repositories are required for cluster operation.

spec.policy

Specifies the parameters that define how the images are verified.

spec.policy.rootOfTrust

Specifies a root of trust for the policy.

spec.policy.rootOfTrust.policyType

Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a Fulcio certificate. This example uses a BYOPKI certificate.

spec.policy.rootOfTrust.pki

For a BYOPKI certificate, specifies caRootsData. This parameter specifies a base64-encoded CA root certificate in the PEM format. The maximum length is 8192 characters. Optionally with caIntermediatesData, specifies a base64-encoded intermediate CA root certificate in the PEM format. The maximum length is 8192 characters.

spec.policy.rootOfTrust.pki.pkiCertificateSubject

Specifies a subject alternative name (SAN) to authenticate the user’s identity by using a hostname and an email address:

email. Specifies the email address specified when the certificate was generated.

hostname. Specifies the hostname specified when the certificate was generated.

spec.policy.signedIdentity.matchPolicy

For a BYOPKI certificate, specifies the MatchRepository parameter to verify the identity in the signature and the actual image identity. The default signed identity is matchRepoDigestOrExact, which requires a digest reference in the signature identity for verification. The signature identity in this case uses a repository reference, and does not include the image digest.
The following example cluster image policy object uses a Fulcio certificate policy and the remapIdentity match policy:
```
apiVersion: config.openshift.io/v1
kind: ClusterImagePolicy
metadata:
  name: p1
spec:
  scopes:
    - example.com
  policy:
    rootOfTrust:
      policyType: FulcioCAWithRekor
      fulcioCAWithRekor:
        fulcioCAData: a2V5RGF0YQ==
        fulcioSubject:
          oidcIssuer: "https://expected.OIDC.issuer/"
          signedEmail: "expected-signing-user@example.com"
        rekorKeyData: cmVrb3JLZXlEYXRh
    signedIdentity:
      matchPolicy: RemapIdentity
      remapIdentity:
        prefix: example.com
        signedPrefix: mirror-example.com
```
where:
kind

Specifies that the configuration is for a ClusterImagePolicy object.

spec.scopes

Specifies a list of repositories or images assigned to this policy. In a cluster image policy, make sure that the policy does not block the deployment of the Red Hat OpenShift Container Platform images in the quay.io/openshift-release-dev/ocp-release and quay.io/openshift-release-dev/ocp-v4.0-art-dev repositories. Images in these repositories are required for cluster operation.

spec.policy

Specifies the parameters that define how the images are verified.

spec.policy.rootOfTrust

Specifies a root of trust for the policy.

spec.policy.rootOfTrust.policyType

Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a Fulcio certificate. This example uses a Fulcio certificate with required Rekor verification.

spec.policy.rootOfTrust.fulcioCAWithRekor

For a Fulcio certificate policy, the following parameters are required:

fulcioCAData: Specifies a base64-encoded Fulcio certificate in the PEM format. The maximum length is 8192 characters.

fulcioSubject: Specifies the OIDC issuer and the email of the Fulcio authentication configuration.

rekorKeyData: Specifies a base64-encoded Rekor public key in the PEM format. This parameter is required when the policyType is FulcioCAWithRekor. The maximum length is 8192 characters.

spec.policy.signedIdentity.matchPolicy

Specifies one of the following processes to verify the identity in the signature and the actual image identity. This parameter is optional.

MatchRepoDigestOrExact.

MatchRepository.

ExactRepository. The exactRepository parameter must be specified.

RemapIdentity. The prefix and signedPrefix parameters must be specified.

spec.policy.signedIdentity.remapIdentity.prefix

For the remapIdentity match policy, specifies the prefix that should be matched against the scoped image prefix. If the two match, the scoped image prefix is replaced with the value of signedPrefix. The maximum length is 512 characters.

spec.policy.signedIdentity.remapIdentity.signedPrefix

For the remapIdentity match policy, specifies the image prefix to be remapped, if needed. The maximum length is 512 characters.
Create the cluster image policy object:
```
$ oc create -f <file_name>.yaml
```
The Machine Config Operator (MCO) updates the machine config pools (MCP) in your cluster. Scheduling on each node is disabled as the change is being applied.

Verification

After the nodes in your cluster are updated, you can verify that the cluster image policy has been configured:

Start a debug pod for the node by running the following command:
```
$ oc debug node/<node_name>
```
Set /host as the root directory within the debug shell by running the following command:
```
sh-5.1# chroot /host/
```

Examine the policy.json file by running the following command:

sh-5.1# cat /etc/containers/policy.json

Example output for the cluster image policy object with a public key showing the new cluster image policy

# ...
  "transports": {
# ...
    "docker": {
      "example.com": [
        {
          "type": "sigstoreSigned",
          "keyData": "a2V5RGF0YQ==",
          "rekorPublicKeyData": "cmVrb3JLZXlEYXRh",
          "signedIdentity": {
            "type": "matchRepoDigestOrExact"
          }
        }
      ],
# ...

Example output for the cluster image policy object for a BYOPKI certificate showing the new cluster image policy

# ...
  "transports": {
# ...
    "docker": {
      "example.io": [
        {
          "type": "sigstoreSigned",
          "pki": {
            "caRootsData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk....URS0tLS0t",
            "caIntermediatesData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1J....lDQVRFLS0tLS0=",
            "subjectEmail": "email@example.com",
            "subjectHostname": "myhost.example.com"
          },
          "signedIdentity": {
            "type": "matchRepository"
          }
        }
      ],

Example output for the cluster image policy object with a Fulcio certificate showing the new cluster image policy

# ...
  "transports": {
# ...
    "docker": {
      "example.com": [
        {
          "type": "sigstoreSigned",
          "fulcio": {
            "caData": "a2V5RGF0YQ==",
            "oidcIssuer": "https://expected.OIDC.issuer/",
            "subjectEmail": "expected-signing-user@example.com"
          },
          "rekorPublicKeyData": "cmVrb3JLZXlEYXRh",
          "signedIdentity": {
            "type": "remapIdentity",
            "prefix": "example.com",
            "signedPrefix": "mirror-example.com"
          }
        }
      ],
# ...

Examine the sigstore-registries.yaml file by running the following command:
```
sh-5.1# cat /etc/containers/registries.d/sigstore-registries.yaml
```
Example output showing that the scoped registry was added
```
docker:
  example.com:
    use-sigstore-attachments: true
  quay.io/openshift-release-dev/ocp-release:
    use-sigstore-attachments: true
```
where:

docker.example.com.use-sigstore-attachments

When true, specifies that sigstore signatures are going to be read along with the image.