You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: modules/tutorials/pages/enabling_verification_of_image_signatures.adoc
+29-28Lines changed: 29 additions & 28 deletions
Original file line number
Diff line number
Diff line change
@@ -44,25 +44,34 @@ If the `subjectRegExp` field in the policy is changed to something like `https:/
44
44
45
45
== Verifying image signatures in an air-gapped environment
46
46
47
-
// intro
48
-
As mentioned before, our images and Helm charts for SDP are signed keyless. Keyless signing is more complex than "classic" signing with a private and public key, but brings several https://www.chainguard.dev/unchained/benefits-of-keyless-software-signing[benefits]. It's also in line with Kubernetes, https://kubernetes.io/docs/tasks/administer-cluster/verify-signed-artifacts/[which uses keyless signing as well].
47
+
As mentioned before, our images and Helm charts for SDP are signed keyless. Keyless signing is more complex than "classic" signing with a private and public key, especially when you want to verify signatures in an air-gapped environment. However, it brings several https://www.chainguard.dev/unchained/benefits-of-keyless-software-signing[benefits] and by signing our images keyless, we're also in line with Kubernetes, https://kubernetes.io/docs/tasks/administer-cluster/verify-signed-artifacts/[which uses keyless signing as well].
49
48
50
49
=== The general setup
51
50
52
-
The Policy Controller needs an up-to-date version of the root of trust, this is distributed as a collection of files and in an online setting it is automatically fetched from the https://tuf-repo-cdn.sigstore.dev/[Sigstore TUF Repo CDN].
51
+
To verify keyless signatures, the Policy Controller needs an up-to-date version of the root of trust, which is distributed as a collection of files (to put it simply). In an online setting, these files are automatically fetched from a CDN, by default the https://tuf-repo-cdn.sigstore.dev/[Sigstore TUF Repo CDN].
53
52
54
-
NOTE: https://theupdateframework.io/[The Update Framework (TUF)] is the mechanism used by the Policy Controller to update the root of trust.
53
+
NOTE: https://docs.sigstore.dev/signing/overview/#root-of-trust[The Update Framework (TUF)] is the mechanism used by the Policy Controller to initialize and update the root of trust.
55
54
56
-
In an air-gapped environment, the CDN is not available, and so instead you have to provide the root of trust files yourself.
57
-
There are multiple ways to do this, and you should pick the way that works best for your air-gapped environment.
55
+
In an air-gapped environment, this CDN is not reachable, so instead you have to provide those files yourself. You can get these files from https://github.com/sigstore/root-signing/tree/main/repository/repository[GitHub].
56
+
There two multiple ways how you can provide these files to the Policy Controller, please pick the one that works best for your air-gapped environment:
58
57
59
-
The files hosted in the CDN are available also on https://github.com/sigstore/root-signing/tree/main/repository/repository[GitHub].
60
-
This is the source where you need to get the files.
61
-
Then there are two ways to provide these files to the Policy Controller inside of your air-gapped Kubernetes.
62
-
Either by hosting them with a HTTP server that is reachable by the Policy Controller, or by zipping the files, serializing them and putting them directly into a custom resource.
63
-
For both options we refer to the Sigstore documentation: https://docs.sigstore.dev/policy-controller/overview/#configuring-trustroot-for-custom-tuf-root[configuring a mirror] or https://docs.sigstore.dev/policy-controller/overview/#configuring-trustroot-for-custom-tuf-repository[serializing the files into a custom resource].
58
+
1. Serve them via an HTTP server that is reachable by the Policy Controller. +
Now you can provide the host's IP address and port (8081 in the example) as the mirror URL. For how to do this exactly, we refer to the https://docs.sigstore.dev/policy-controller/overview/#configuring-trustroot-for-custom-tuf-root[Policy Controller's documentation].
69
+
+
70
+
NOTE: Since we're using Sigstore's TUF repository, you don't have to provide the `.spec.root` attribute in the `TrustRoot` resource, `.spec.mirror` is sufficient.
71
+
72
+
2. Packing the files into an archive, serializing them and putting them directly into a the `TrustRoot` resource. This is explained in the https://docs.sigstore.dev/policy-controller/overview/#configuring-trustroot-for-custom-tuf-repository[Policy Controller's documentation].
64
73
65
-
Both options yield you a TrustRoot custom resource which you then need to configure in your ClusterImagePolicy.
74
+
Both options yield you a `TrustRoot` custom resource which you then need to configure in your `ClusterImagePolicy`.
66
75
This is done via the `trustRootRef` attribute, as shown https://docs.sigstore.dev/policy-controller/overview/#configuring-verification-against-different-sigstore-instances[in the Policy Controller's documentation].
67
76
68
77
=== Updating
@@ -71,26 +80,18 @@ The problem for air-gapped environments is that expiration of keys is built into
71
80
That means, to verify image signatures continuously, the Policy Controller needs an up-to-date version of the root of trust.
72
81
73
82
Depending on which way you are providing the root of trust (mirror or direct files), you need to update that accordingly.
74
-
If your cluster has access to for example a bastion host that in turn has limited internet access, configuring a mirror might be the easier way to go for you.
75
-
You might even be able to simply configure a reverse proxy to https://tuf-repo-cdn.sigstore.dev/ to avoid manually updating files periodically.
83
+
If, for example, you can reach a bastion host from your air-gapped environment that has internet access, configuring a mirror might be the easier way to go for you. In that case, you could simply configure a reverse proxy to https://tuf-repo-cdn.sigstore.dev/ on the bastion host, to avoid manually updating files periodically.
76
84
77
-
If your setup is completely air-gapped, you will have to do periodic manual updates of the files that you deployed earlier.
85
+
If your setup is completely air-gapped, you will have to do periodic manual updates of the files that you deployed earlier (e.g. in the first example, you could run `git pull` daily).
78
86
It is not clear how often the root of trust needs to be updated (TODO: research if we can find out more)
79
87
80
-
Either refresh your mirror or periodically supply the files directly via other methods into your airgapped system.
81
-
82
-
The Policy Controller does not need to be restarted. (TODO verify)
88
+
The Policy Controller does not need to be restarted after the files have been updated. (TODO: verify this)
83
89
84
90
== Further reading
85
91
86
-
...
87
-
88
-
=== Background: How it usually works online with Fulcio
89
-
90
-
Describing the whole flow with all the components is out of scope for this documentation, so we will try to provide a summary of the most important parts instead: +
91
-
To verify that an image has been signed by Stackable, customers check that the image has a valid signature and that this signature was created by Stackable's CI (Github Actions). More specifically, they check that the identity of the signer is one of Stackable's Github Actions workflows and that this identity has been confirmed by a trusted authority (Github in that case). The role of the Sigstore project https://github.com/sigstore/fulcio[Fulcio] is to issue a certificate for exactly that: +
92
-
"This Fulcio instance confirms that this signature was created by `https://github.com/stackabletech/docker-images/.github/workflows/release.yml@refs/tags/23.11.0` and `https://token.actions.githubusercontent.com` confirmed that identity".
93
-
94
-
By default, the public Fulcio instance hosted by Sigstore is used for this, which is what we do at Stackable as well.
92
+
There's a lot more to learn about how keyless signing and verification works. We recommend the following resources:
95
93
96
-
That means customers wanting to verify these image signatures need to trust the Fulcio instance, which issues the certificates that attest the identity of the signer. The root of trust for Sigstore components like the public Fulcio instance is distributed by a framework called https://docs.sigstore.dev/signing/overview/#root-of-trust[The Update Framework (TUF)]. Thankfully, the whole initialization of the root of trust via TUF is handled by the Policy Controller.
0 commit comments