How to use docker trust sign command to sign an image

Introduction

In this lab, you will learn how to use the docker trust sign command to secure your Docker images. We will begin by inspecting an unsigned image to understand its characteristics before signing. You will then practice signing an image tag as a repository administrator, asserting its authenticity, and subsequently verifying the signature. Finally, you will explore the process of signing and verifying a tag as a designated signer, demonstrating the collaborative nature of Docker Content Trust.

Skills Graph

%%%%{init: {'theme':'neutral'}}%%%% flowchart RL docker(("Docker")) -.-> docker/ImageOperationsGroup(["Image Operations"]) docker(("Docker")) -.-> docker/ContainerOperationsGroup(["Container Operations"]) docker/ContainerOperationsGroup -.-> docker/inspect("Inspect Container") docker/ImageOperationsGroup -.-> docker/pull("Pull Image from Repository") docker/ImageOperationsGroup -.-> docker/tag("Tag an Image") docker/ImageOperationsGroup -.-> docker/push("Push Image to Repository") subgraph Lab Skills docker/inspect -.-> lab-555255{{"How to use docker trust sign command to sign an image"}} docker/pull -.-> lab-555255{{"How to use docker trust sign command to sign an image"}} docker/tag -.-> lab-555255{{"How to use docker trust sign command to sign an image"}} docker/push -.-> lab-555255{{"How to use docker trust sign command to sign an image"}} end

Inspect an unsigned image

In this step, we will learn how to inspect a Docker image that has not been signed. Docker Content Trust provides a way to verify the integrity and authenticity of Docker images. However, not all images are signed. Inspecting an unsigned image helps us understand the basic information about the image before we delve into the concepts of signing and verification.

First, we need to pull an unsigned image from a Docker registry. We will use the hello-world image, which is typically not signed by default.

docker pull hello-world

This command downloads the hello-world image from the Docker Hub registry to your local machine. You should see output indicating the download progress and completion.

Next, we will inspect the pulled image using the docker inspect command. This command provides detailed information about a Docker object, including images, containers, volumes, and networks.

docker inspect hello-world

The output of this command will be a large JSON document containing various details about the hello-world image. You can examine this output to see information such as the image ID, creation date, architecture, operating system, and configuration.

Since this image is unsigned, you will not find any information related to signatures or trust in the output of the docker inspect command. This is the key characteristic of an unsigned image when viewed through the lens of Docker Content Trust.

Sign a tag as a repository admin

In this step, we will learn how to sign a Docker image tag as a repository administrator. Docker Content Trust uses digital signatures to ensure that the images you pull are exactly what the publisher intended. As a repository administrator, you have the authority to sign image tags, asserting their authenticity.

Before we can sign an image, we need to enable Docker Content Trust. This is done by setting the DOCKER_CONTENT_TRUST environment variable to 1.

export DOCKER_CONTENT_TRUST=1

This command enables content trust for subsequent Docker commands in your current terminal session.

Now, let's tag the hello-world image we pulled in the previous step with a new tag that includes a repository name. We will use a placeholder repository name your_docker_username/my-signed-image. Replace your_docker_username with your actual Docker Hub username if you have one, or just use labexuser for this lab.

docker tag hello-world labexuser/my-signed-image:latest

This command creates a new tag labexuser/my-signed-image:latest that points to the same image as hello-world.

Now, we will push this tagged image to a registry. When Docker Content Trust is enabled, pushing an image tag that hasn't been signed will prompt you to sign it.

docker push labexuser/my-signed-image:latest

When you execute this command, Docker will prompt you to create a new signing key or use an existing one. Since this is likely your first time signing, you will be asked to create a new key. You will need to provide a passphrase for the new key. Remember this passphrase, as you will need it later to sign other images or rotate keys.

After entering and confirming the passphrase, Docker will sign the image tag and push it to the registry. You should see output indicating the signing process and the successful push.

Verify the signature as a repository admin

In this step, we will verify the signature of the image tag we signed in the previous step. As a repository administrator, you can use Docker Content Trust to ensure that the image you are pulling is the one you signed.

First, let's make sure Docker Content Trust is still enabled. If you opened a new terminal session, you might need to set the environment variable again.

export DOCKER_CONTENT_TRUST=1

Now, we will attempt to pull the signed image tag. Because Docker Content Trust is enabled, Docker will verify the signature before pulling the image.

docker pull labexuser/my-signed-image:latest

When you run this command, Docker will check for a valid signature for the labexuser/my-signed-image:latest tag. If the signature is valid and trusted, the image will be pulled. You should see output indicating that the image is being pulled and that the signature is being verified. The output will explicitly mention "Verifying trust data for".

If the signature were invalid or missing (and content trust is enabled), the pull operation would fail, preventing you from using a potentially compromised image.

To further inspect the trust information associated with the image, you can use the docker trust inspect command.

docker trust inspect labexuser/my-signed-image:latest

This command will display detailed information about the signatures associated with the specified image tag. You should see information about the signers and the signed tags. This output confirms that the image tag has been successfully signed and the signature is recognized by Docker Content Trust.

Sign a tag as a signer

In this step, we will explore how a designated "signer" can sign a Docker image tag. In a real-world scenario, a repository might have multiple signers, each responsible for signing specific tags or releases. This allows for a more distributed and secure signing process.

First, ensure Docker Content Trust is enabled:

export DOCKER_CONTENT_TRUST=1

Now, let's create a new tag for our image, simulating a different version or release that a signer might be responsible for.

docker tag labexuser/my-signed-image:latest labexuser/my-signed-image:v1.0.0

This creates a new tag labexuser/my-signed-image:v1.0.0 pointing to the same image.

To sign this new tag as a different "signer", we use the docker trust sign command. This command allows you to explicitly sign a specific tag with a specific key.

docker trust sign labexuser/my-signed-image:v1.0.0

When you execute this command, Docker will prompt you for the passphrase of the signing key you want to use. If you are using the same key generated in Step 2, enter that passphrase. If you were a different signer with a different key, you would use that key's passphrase.

After successfully entering the passphrase, Docker will sign the labexuser/my-signed-image:v1.0.0 tag. You should see output confirming the signing process.

Finally, we need to push the updated trust data to the registry. The docker push command for the signed tag will include the new signature information.

docker push labexuser/my-signed-image:v1.0.0

This command pushes the v1.0.0 tag along with its associated signature to the registry.

Verify the signature as a signer

In this final step, we will verify the signature of the v1.0.0 image tag that we signed as a "signer" in the previous step. This demonstrates how any user with Docker Content Trust enabled can verify the authenticity of an image signed by a trusted signer.

First, ensure Docker Content Trust is enabled.

export DOCKER_CONTENT_TRUST=1

Now, let's attempt to pull the v1.0.0 image tag. Since Content Trust is enabled, Docker will verify the signature associated with this tag.

docker pull labexuser/my-signed-image:v1.0.0

Similar to the verification in Step 3, you should see output indicating that Docker is verifying the trust data for the image and then pulling it. This confirms that the signature you applied as a signer is valid and recognized.

To further confirm the signing information, you can again use the docker trust inspect command.

docker trust inspect labexuser/my-signed-image:v1.0.0

The output of this command will show the signers for the v1.0.0 tag. You should see the key information of the signer you used in the previous step listed here. This provides concrete evidence that the tag has been signed by a trusted entity.

This concludes our exploration of signing and verifying Docker image tags using Docker Content Trust. By enabling content trust and using signing keys, you can significantly enhance the security of your container workflow by ensuring the integrity and authenticity of the images you use.

Summary

In this lab, we learned how to work with Docker Content Trust by first inspecting an unsigned image to understand its basic information and the absence of signature details. We then explored the process of signing a Docker image tag as a repository administrator, which involves enabling content trust and using the docker trust sign command to assert the authenticity of the image.

Following the signing process, we learned how to verify the signature as a repository administrator to ensure the image's integrity. We also practiced signing a tag as a designated signer, demonstrating the delegation of signing authority within a repository. Finally, we verified the signature as a signer, confirming the successful application and verification of the delegated signature.