You are viewing the development docs which are in progress. There is no guarantee that the development documentation will be accurate, including instructions, links, and other information. For the latest stable documentation, click here.

Check the Signatures

Verify the integrity of the ISO by checking the signatures.

Check the Signatures

Our ISO releases have sha256 files to checksum the validity of the artifacts. At the same time, our sha256 files are signed automatically in the CI during the release workflow to verify that they haven’t been tampered with, adding an extra step to the supply chain.

It is recommended that before starting any installation the whole security chain is validated by verifying our sha256 signature and validating that the checksum matches with the download artifacts.

To validate the whole chain you need:

  1. sha256sum which is usually installed by default on most linux distributions.
  2. cosign to verify the signatures of the sha256 file. You can install cosign via their installation docs
  3. sha256, certificate and signature files that you want to verify

In this example we will use the master version and @flavor flavor and @flavorRelease flavor release.

First we check that we have all needed files:

$ ls      
kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso         kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.pem
kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256  kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.sig

Then we verify that the sha256 checksums haven’t been tampered with (substitute $VERSION with the exact Kairos version you are verifying as the certificate identity is the release job that signs it):

$ cosign verify-blob --cert kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.pem --signature kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.sig --certificate-identity https://github.com/kairos-io/kairos/.github/workflows/reusable-release.yaml@refs/tags/$VERSION --certificate-oidc-issuer https://token.actions.githubusercontent.com kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256 
Verified OK

Once we see that Verified OK we can be sure that the file hasn’t been tampered with, and we can continue verifying the iso checksum.

For an example of a failure validation see below:

$ cosign verify-blob --cert kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.pem --signature kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.sig --certificate-identity https://github.com/kairos-io/kairos/.github/workflows/reusable-release.yaml@refs/tags/$VERSION --certificate-oidc-issuer https://token.actions.githubusercontent.com kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.modified 
Error: verifying blob [kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.modified]: invalid signature when validating ASN.1 encoded signature
main.go:62: error during command execution: verifying blob [kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256.modified]: invalid signature when validating ASN.1 encoded signature

Now we can verify that the integrity of the ISO hasnt been compromise:

$ sha256sum -c kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso.sha256
kairos-@flavor-@flavorRelease-core-amd64-generic-master.iso: OK

Once we reached this point, we can be sure that from the ISO hasn’t been tampered with since it was created by our release workflow.

Last modified June 10, 2025: Update check-the-signatures.md (#423) (65c1a79)