Skip to content

Commit bb28e76

Browse files
mburke5678mburke5678
authored
Merge pull request #97651 from mburke5678/node-byopik-sigstore
OCPNODE 3039 Tech Preview Support BYOPKI for image verification in OCP
2 parents 2e99c96 + 68c1afa commit bb28e76

File tree

3 files changed

+180
-8
lines changed

3 files changed

+180
-8
lines changed

‎modules/nodes-sigstore-configure-cluster-policy.adoc‎

Lines changed: 86 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ include::snippets/technology-preview.adoc[]
1717

1818
.Prerequisites
1919
// Taken from https://issues.redhat.com/browse/OCPSTRAT-918
20-
* You have a sigstore-supported public key infrastructure (PKI) or a link:https://docs.sigstore.dev/cosign/[Cosign public and private key pair] for signing operations.
20+
* You have a sigstore-supported public key infrastructure (PKI) key, a Bring Your Own Public Key Infrastructure (BYOPKI) certificate, or provide a link:https://docs.sigstore.dev/cosign/signing/overview/[Cosign public and private key pair] for signing operations.
2121
* You have a signing process in place to sign your images.
2222
* You have access to a registry that supports Cosign signatures, if you are using Cosign signatures.
2323
* If registry mirrors are configured for the {product-title} release image repositories, `quay.io/openshift-release-dev/ocp-release` and `quay.io/openshift-release-dev/ocp-v4.0-art-dev`, before enabling the Technology Preview feature set, you must mirror the sigstore signatures for the {product-title} 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 that results from the feature set change.
@@ -30,6 +30,30 @@ $ oc image mirror quay.io/openshift-release-dev/ocp-release:sha256-1234567890abc
3030
mirror.com/image/repo:sha256-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef.sig
3131
----
3232
33+
* If you are using a BYOPKI certificate as the root of trust, you enabled the required Technology Preview features for your cluster by editing the `FeatureGate` CR named `cluster`:
34+
+
35+
[source,terminal]
36+
----
37+
$ oc edit featuregate cluster
38+
----
39+
+
40+
.Example `FeatureGate` CR
41+
[source,yaml]
42+
----
43+
apiVersion: config.openshift.io/v1
44+
kind: FeatureGate
45+
metadata:
46+
name: cluster
47+
spec:
48+
featureSet: TechPreviewNoUpgrade <1>
49+
----
50+
<1> Enables the required `SigstoreImageVerificationPKI` feature.
51+
+
52+
[WARNING]
53+
====
54+
Enabling the `TechPreviewNoUpgrade` feature set on your cluster cannot be undone and prevents minor version updates. This feature set allows you to enable these Technology Preview features on test clusters, where you can fully test them. Do not enable this feature set on production clusters.
55+
====
56+
3357
.Procedure
3458

3559
. Create a cluster image policy object similar to the following examples. See "About image policy parameters" for specific details on these parameters.
@@ -58,7 +82,7 @@ spec:
5882
<2> Defines 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 {product-title} 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.
5983
<3> Specifies the parameters that define how the images are verified.
6084
<4> Defines a root of trust for the policy.
61-
<5> Specifies the policy types that define the root of trust, either a public key or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certifice]. Here, a public key with Rekor verification.
85+
<5> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. This example uses a public key with Rekor verification.
6286
<6> For a public key policy, specifies a base64-encoded public key in the PEM format. The maximum length is 8192 characters.
6387
<7> Optional: Specifies a base64-encoded Rekor public key in the PEM format. The maximum length is 8192 characters.
6488
<8> Optional: Specifies one of the following processes to verify the identity in the signature and the actual image identity:
@@ -69,6 +93,41 @@ spec:
6993
--
7094
+
7195
--
96+
.Example cluster image policy object for a BYOPKI policy and the `MatchRepository` match policy
97+
[source,yaml]
98+
----
99+
apiVersion: config.openshift.io/v1alpha1
100+
kind: ClusterImagePolicy <1>
101+
metadata:
102+
name: pki-policy
103+
spec:
104+
scopes:
105+
- example.io <2>
106+
policy: <3>
107+
rootOfTrust: <4>
108+
policyType: PKI <5>
109+
pki: <6>
110+
caRootsData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk....URS0tLS0t
111+
caIntermediatesData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1J....lDQVRFLS0tLS0=
112+
pkiCertificateSubject: <7>
113+
email: email@example.com
114+
hostname: myhost.example.com
115+
signedIdentity:
116+
matchPolicy: MatchRepository <8>
117+
----
118+
<1> Creates a `ClusterImagePolicy` object.
119+
<2> Defines 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 {product-title} 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.
120+
<3> Specifies the parameters that define how the images are verified.
121+
<4> Defines a root of trust for the policy.
122+
<5> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. This example uses a BYOPKI certificate.
123+
<6> For a BYOPKI certificate, specify `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.
124+
<7> Specifies a subject alternative name (SAN) to authenticate the user’s identity by using a hostname and an email address:
125+
* `email`. Specifies the email address specified when the certificate was generated.
126+
* `hostname`. Specifies the hostname specified when the certificate was generated.
127+
<8> For a BYOPKI certificate, specify 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.
128+
--
129+
+
130+
--
72131
.Example cluster image policy object with a Fulcio certificate policy and the `remapIdentity` match policy
73132
[source,yaml]
74133
----
@@ -98,7 +157,7 @@ spec:
98157
<2> Defines 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 {product-title} 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.
99158
<3> Specifies the parameters that define how the images are verified.
100159
<4> Defines a root of trust for the policy.
101-
<5> Specifies the policy types that define the root of trust, either a public key or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. Here, a Fulcio certificate with required Rekor verification.
160+
<5> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. This example uses a Fulcio certificate with required Rekor verification.
102161
<6> For a Fulcio certificate policy, the following parameters are required:
103162
* `fulcioCAData`: Specifies a base64-encoded Fulcio certificate in the PEM format. The maximum length is 8192 characters.
104163
* `fulcioSubject`: Specifies the OIDC issuer and the email of the Fulcio authentication configuration.
@@ -119,7 +178,7 @@ spec:
119178
$ oc create -f <file_name>.yaml
120179
----
121180
+
122-
The Machine Config Operator (MCO) updates the machine config pools (MCP) in your cluster.
181+
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.
123182

124183
.Verification
125184

@@ -166,6 +225,29 @@ sh-5.1# cat /etc/containers/policy.json
166225
# ...
167226
----
168227
+
228+
.Example output for the cluster image policy object for a BYOPKI certificate showing the new cluster image policy
229+
[source,json]
230+
----
231+
# ...
232+
"transports": {
233+
# ...
234+
"docker": {
235+
"example.io": [
236+
{
237+
"type": "sigstoreSigned",
238+
"pki": {
239+
"caRootsData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk....URS0tLS0t",
240+
"caIntermediatesData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1J....lDQVRFLS0tLS0=",
241+
"subjectEmail": "email@example.com",
242+
"subjectHostname": "myhost.example.com"
243+
},
244+
"signedIdentity": {
245+
"type": "matchRepository"
246+
}
247+
}
248+
],
249+
----
250+
+
169251
.Example output for the cluster image policy object with a Fulcio certificate showing the new cluster image policy
170252
[source,json]
171253
----

‎modules/nodes-sigstore-configure-image-policy.adoc‎

Lines changed: 87 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,32 @@ The following example shows general guidelines on how to configure an `ImagePoli
1717

1818
.Prerequisites
1919
// Taken from https://issues.redhat.com/browse/OCPSTRAT-918
20-
* You have a sigstore-supported public key infrastructure (PKI) or provide link:https://docs.sigstore.dev/cosign/[Cosign public and private key pair] for signing operations.
20+
* You have a sigstore-supported public key infrastructure (PKI) key, a Bring Your Own Public Key Infrastructure (BYOPKI) certificate, or provide a link:https://docs.sigstore.dev/cosign/signing/overview/[Cosign public and private key pair] for signing operations.
2121
* You have a signing process in place to sign your images.
2222
* You have access to a registry that supports Cosign signatures, if you are using Cosign signatures.
23+
* If you are using a BYOPKI certificate as the root of trust, you enabled the required Technology Preview features for your cluster by editing the `FeatureGate` CR named `cluster`:
24+
+
25+
[source,terminal]
26+
----
27+
$ oc edit featuregate cluster
28+
----
29+
+
30+
.Example `FeatureGate` CR
31+
[source,yaml]
32+
----
33+
apiVersion: config.openshift.io/v1
34+
kind: FeatureGate
35+
metadata:
36+
name: cluster
37+
spec:
38+
featureSet: TechPreviewNoUpgrade <1>
39+
----
40+
<1> Enables the required `SigstoreImageVerification` feature.
41+
+
42+
[WARNING]
43+
====
44+
Enabling the `TechPreviewNoUpgrade` feature set on your cluster cannot be undone and prevents minor version updates. This feature set allows you to enable these Technology Preview features on test clusters, where you can fully test them. Do not enable this feature set on production clusters.
45+
====
2346
2447
.Procedure
2548

@@ -51,7 +74,7 @@ spec:
5174
<3> Defines a list of repositories or images assigned to this policy.
5275
<4> Specifies the parameters that define how the images are verified.
5376
<5> Defines a root of trust for the policy.
54-
<6> Specifies the policy types that define the root of trust, either a public key or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. Here, a public key with Rekor verification.
77+
<6> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. Here, a public key with Rekor verification.
5578
<7> For a public key policy, specifies a base64-encoded public key in the PEM format. The maximum length is 8192 characters.
5679
<8> Optional: Specifies a base64-encoded Rekor public key in the PEM format. The maximum length is 8192 characters.
5780
<9> Optional: Specifies one of the following processes to verify the identity in the signature and the actual image identity:
@@ -62,6 +85,44 @@ spec:
6285
--
6386
+
6487
--
88+
.Example image policy object for a BYOPKI policy and the `MatchRepository` match policy
89+
[source,yaml]
90+
----
91+
apiVersion: config.openshift.io/v1alpha1
92+
kind: ImagePolicy <1>
93+
metadata:
94+
name: pki-policy
95+
namespace: mynamespace <2>
96+
spec:
97+
scopes:
98+
- example.io <3>
99+
policy: <4>
100+
rootOfTrust: <5>
101+
policyType: PKI <6>
102+
pki: <7>
103+
caRootsData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk....RVJUSUZJQ0FURS0tLS0t
104+
caIntermediatesData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURkVENDQ....0QT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
105+
pkiCertificateSubject: <8>
106+
email: email@example.com
107+
hostname: myhost.example.com
108+
signedIdentity:
109+
matchPolicy: MatchRepository <9>
110+
----
111+
<1> Creates an `ImagePolicy` object.
112+
<2> Specifies the namespace where the image policy is applied.
113+
<3> Defines a list of repositories or images assigned to this policy.
114+
<4> Specifies the parameters that define how the images are verified.
115+
<5> Defines a root of trust for the policy.
116+
<6> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. Here, a BYOPKI certificate.
117+
<7> For a BYOPKI certificate, specify `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.
118+
<8> Specifies a subject alternative name (SAN) to authenticate the user’s identity by using a hostname and an email address:
119+
* `email`. Specifies the email address specified when the certificate was generated.
120+
* `hostname`. Specifies the hostname specified when the certificate was generated.
121+
<9> For a BYOPKI certificate, specify `MatchRepository` to verify the identity in the signature and the actual image identity. The default signed identity is `matchRepoDigestOrExact`, which requires digest specification. The signature in this case was not created for digested image.
122+
--
123+
// <9> is from the test case: https://polarion.engineering.redhat.com/polarion/#/project/OSE/workitem?id=OCP-83752
124+
+
125+
--
65126
.Example image policy object with a Fulcio certificate policy and the `ExactRepository` match policy
66127
[source,yaml]
67128
----
@@ -92,7 +153,7 @@ spec:
92153
<3> Defines a list of repositories or images assigned to this policy.
93154
<4> Specifies the parameters that define how the images are verified.
94155
<5> Defines a root of trust for the policy.
95-
<6> Specifies the policy types that define the root of trust, either a public key or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. Here, a Fulcio certificate with required Rekor verification.
156+
<6> Specifies the policy types that define the root of trust, either a public key, a BYOPKI certificate, or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate]. Here, a Fulcio certificate with required Rekor verification.
96157
<7> For a Fulcio certificate policy, the following parameters are required:
97158
* `fulcioCAData`: Specifies a base64-encoded Fulcio certificate in the PEM format. The maximum length is 8192 characters.
98159
* `fulcioSubject`: Specifies the OIDC issuer and the email of the Fulcio authentication configuration.
@@ -158,6 +219,29 @@ sh-5.1# cat /etc/crio/policies/<namespace>.json
158219
# ...
159220
----
160221
+
222+
.Example output for the image policy object for a BYOPKI certificate showing the new image policy
223+
[source,json]
224+
----
225+
# ...
226+
"transports": {
227+
# ...
228+
"docker": {
229+
"docker.io": [
230+
{
231+
"type": "sigstoreSigned",
232+
"pki": {
233+
"caRootsData": "LS0t...LS0t",
234+
"caIntermediatesData": "LS0t...LS0t"
235+
"subjectEmail": "email@example.com",
236+
"subjectHostname": "myhost.example.com"
237+
},
238+
"signedIdentity": {
239+
"type": "matchRepository"
240+
}
241+
}
242+
],
243+
----
244+
+
161245
.Example output for the image policy object with a Fulcio certificate showing the new image policy
162246
[source,json]
163247
----

‎modules/nodes-sigstore-configure.adoc‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,14 @@ If multiple scopes match a single scope in the same a cluster or image policy, t
6565
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.
6666
6767
`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`.
68-
* `rootOfTrust`: Specifies the root of trust for the policy. Configure either a public key or a link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate].
68+
* `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 link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio certificate].
6969
** `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 link:https://docs.sigstore.dev/logging/overview/[Rekor verification].
70+
** `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.
71+
+
72+
--
73+
:FeatureName: sigstore BYOPKI support
74+
include::snippets/technology-preview.adoc[]
75+
--
7076
** `FulcioCAWithRekor`: Indicates that the policy is based on a Fulcio certificate. You must specify the following parameters:
7177
*** A base64-encoded PEM-format Fulcio CA
7278
*** An OpenID Connect (OIDC) issuer

0 commit comments

Comments
 (0)