Product Docs
Open Source
Education
Chainguard Enforce Signing is in Beta Preview. You can request access to the product selecting Chainguard Enforce on the inquiry form.
Powered by the open source security tool suite Sigstore, Chainguard Enforce Signing enables you to generate digital signatures for software artifacts inside your own organization using the individual identities of your team members and ephemeral keys. Enforce Signing can be monitoried and audited against your organization’s compliance and privacy requirements so you have full control. Learn more about Enforce Signing in our Overview and FAQs doc.
This guide will onboard you to Chainguard Enforce Signing.
In addition to having access to Chainguard Enforce (which you can request via our inquiry form) and an IAM group set up, you will need the following tools and versions noted in order to follow this guide.
chainctl
With these tools and setup in place you are ready to begin.
Now that you’ve provided Enforce with references to your CA service, you’ll need to give Chainguard authorization to use those resources.
To set up your account association, you’ll be using Terraform. Follow our guidance on Cloud Account Association to complete this setup for either GCP or AWS.
You can confirm that resources were set up as expected with your cloud provider. In GCP, you can navigate to your Workload Identity Pools. On this page should be a resource called Chainguard Pool. If you click on the pool details and review the connected service accounts, you’ll have a few service accounts that are now prefixed with chainguard. The service account chainguard-enforce-signer that the Enforce Signing service will be running under to request certificates.
chainguard
chainguard-enforce-signer
To confirm that the account association setup was successful, run the relevant chainctl command for GCP or AWS, respectively.
chainctl iam groups check-gcp
chainctl iam groups check-aws
You may need to select the Group that you are currently working with.
If everything is set up correctly, you’ll receive output similar to the following.
... role impersonation was successful!
With everything set up, we are now ready to work with a software artifact.
If you have a container already in a container registry that you can use for demonstration purposes, feel free to skip this step and proceed to Step 5.
Otherwise, we’ll quickly set up a demo image and publish it so that we can sign and verify it with Chainguard Enforce Signing in the next step.
Let’s create and move into a directory for our container image. Replace $USERNAME below with a username you may use on a container registry, or your name.
$USERNAME
mkdir -p ~/$USERNAME/hello-signing && cd $_
In this diretory create a Dockerfile and open it in a text editor. For example, you can use Nano.
nano Dockerfile
Type the following into your editor.
FROM alpine CMD ["echo", "Let's sign with Enforce Signing!"]
Once you are satisfied that your Dockerfile is the same as the text above, you can save and close the file.
We will publish this container to ttl.sh, which is an anonymous and ephemeral container registry. If you would prefer to publish this in another container registry, feel free to do so.
We’ll start by building the image. The 1h tag tells ttl.sh to store the image in their registry for one hour, you can modify the time for your purposes.
1h
sudo docker build -t ttl.sh/$USERNAME/hello-signing:1h .
Next, push the image to the registry.
docker push ttl.sh/$USERNAME/hello-signing:1h
At this point, you will receive output that your container was published and you are ready to continue to the final step.
You are now ready to sign and verify an image with your brand new Certificate Authority!
First, log into Chainguard:
chainctl auth login
This workflow will ask you to go through an OIDC flow to authenticate with Chainguard.
Next, you’ll need to set up your environment to point Cosign to your personal Enforce Signing instance. Here, replace $ENFORCE_CA_NAME with the name of your Enforce CA. You can pull this up again by running chainctl sigstore ca ls .
$ENFORCE_CA_NAME
chainctl sigstore ca ls
eval $(chainctl sigstore env $ENFORCE_CA_NAME)
You will have to authenticate again, to get an authentication token unique to your instance of Enforce Signing. This command will set the required environment variables for Cosign to sign your image with your private CA.
You are now ready to sign by following the steps below. If you followed Step 4, replace $IMAGE with ttl.sh/$USERNAME/hello-signing:1h, otherwise fill in your own image that you would like to sign.
$IMAGE
ttl.sh/$USERNAME/hello-signing:1h
eval $(chainctl sigstore env $ENFORCE_CA_NAME) cosign sign $IMAGE
Finally, you are ready to verify your image. The cosign verify command expects both a certificate identity and an issuer. The issuer, https://auth.chainguard.dev, is already set by the sigstore env command. The certificate identity will correspond to the email address you used to authenticate to Chainguard. Replace $EMAIL below with that email address.
cosign verify
https://auth.chainguard.dev
sigstore env
$EMAIL
eval $(chainctl sigstore env $ENFORCE_CA_NAME) cosign verify $IMAGE --certificate-identity=$EMAIL
You can also verify with a wildcard certificate identity, as in the following command.
eval $(chainctl sigstore env $ENFORCE_CA_NAME) cosign verify $IMAGE --certificate-identity-regexp=".*"
After running this command, you should receive output that returns that the Cosign claims and certificate were verified.
Verification for $IMAGE -- The following checks were performed on each of these signatures: - The cosign claims were validated - The code-signing certificate was verified using trusted certificate authority certificates [{"critical":{"identity":{"docker-reference":"$IMAGE"},"image":{"docker-manifest-digest":"sha256:77...9"},"type":"cosign container image signature"},"optional":{"...":"https://auth.chainguard.dev/","Issuer":"https://auth.chainguard.dev/","..."},"Subject":"$EMAIL"}}]
This output indicates that software artifact’s signature was successfully verified.
To understand more about Enforce Signing, review the Overview and FAQs.
If you would like to learn more about Sigstore, the open source tool suite that Enforce Signing is built on, check out Chainguard Academy’s section on Sigstore.
Now that you have a signed image, you can proceed to create Enforce policies with this tutorial on Example Policy for Enforce Signed Images.