How to use the command 'cosign' (with examples)

The cosign command is used to perform container signing, verification, and storage in an OCI registry. This command is part of the sigstore project and provides a secure way to sign and verify container images with cryptographic signatures. It also supports key management and storage in various environments such as local files, Kubernetes secrets, and OCI registries.

Use case 1: Generate a key-pair

Code:

cosign generate-key-pair

Motivation: Generating a key-pair is the first step in using cosign for signing and verifying container images. With cosign generate-key-pair, a new cryptographic key-pair is generated locally, which consists of a private key (cosign.key) and a public key (cosign.pub). These keys are used for subsequent signing and verification operations.

Explanation: This command generates a new key-pair locally. The private key (cosign.key) is used for signing container images, while the public key (cosign.pub) is used for verifying the signatures. By default, the keys are stored in the current working directory.

Example output:

Key-pair generated successfully.
Private key: cosign.key
Public key: cosign.pub

Use case 2: Sign a container and store the signature in the registry

Code:

cosign sign -key cosign.key image

Motivation: Signing a container image provides a way to ensure its integrity and authenticity. By signing a container image, it can be verified later to verify that it has not been tampered with and that it comes from a trusted source.

Explanation: This command signs a container image (image) using the private key (cosign.key) generated in the previous step. The resulting signature is stored in the registry alongside the container image. The signature provides a proof that the image was signed by the owner of the private key.

Example output:

Container image signed successfully and signature stored in the registry.

Use case 3: Sign a container image with a key pair stored in a Kubernetes secret

Code:

cosign sign -key k8s://namespace/key image

Motivation: In some cases, it may be desirable to store the key pair used for signing container images in a secure and centralized location. Kubernetes secrets provide a suitable mechanism for storing sensitive information like keys.

Explanation: This command signs a container image (image) using a key pair stored in a Kubernetes secret. The k8s://namespace/key argument specifies the Kubernetes secret where the key pair is stored. The secret should be in the format keypair-private for the private key and keypair-public for the public key.

Example output:

Container image signed successfully using the key pair from the Kubernetes secret.

Use case 4: Sign a blob with a local key pair file

Code:

cosign sign-blob --key cosign.key path/to/file

Motivation: Apart from signing container images, the cosign command can also be used to sign arbitrary blobs of data. This can be useful for signing other files or data that may not be in the form of container images.

Explanation: This command signs a blob (file) specified by path/to/file using the private key (cosign.key) generated earlier. The resulting signature is not stored in the registry, but it can be used for verification purposes.

Example output:

Blob signed successfully.
Signature: 3e0d46885767d1ec0b45a8e6e8a6a2c89311ebb732d43b5c95eacf123456789

Use case 5: Verify a container against a public key

Code:

cosign verify -key cosign.pub image

Motivation: After signing a container image, it is important to have a way to verify its authenticity and integrity. The cosign verify command allows users to verify a container image against a public key to ensure that it has not been tampered with and is from a trusted source.

Explanation: This command verifies the signature of a container image (image) against a public key (cosign.pub). If the signature is valid and matches the image, it indicates that the image has not been tampered with and is from a trusted source.

Example output:

Container image verified successfully against the public key.

Use case 6: Verify images with a public key in a Dockerfile

Code:

cosign dockerfile verify -key cosign.pub path/to/Dockerfile

Motivation: Dockerfiles are commonly used to define container images and their configuration. The cosign dockerfile verify command allows users to verify the authenticity and integrity of the images specified in a Dockerfile using a public key.

Explanation: This command verifies the signatures of container images specified in a Dockerfile (path/to/Dockerfile) against a public key (cosign.pub). If all signatures are valid and match the corresponding images, it indicates that the images have not been tampered with and are from trusted sources.

Example output:

Images specified in the Dockerfile verified successfully against the public key.

Use case 7: Verify an image with a public key stored in a Kubernetes secret

Code:

cosign verify -key k8s://namespace/key image

Motivation: Just like signing with a key pair stored in a Kubernetes secret, verifying against a public key stored in a Kubernetes secret provides an additional layer of security. It ensures that the public key used for verification is retrieved from a trusted and secured source.

Explanation: This command verifies the signature of a container image (image) against a public key stored in a Kubernetes secret. The k8s://namespace/key argument specifies the Kubernetes secret where the public key is stored. The secret should be in the format keypair-public.

Example output:

Container image verified successfully against the public key from the Kubernetes secret.

Use case 8: Copy a container image and its signatures

Code:

cosign copy example.com/src:latest example.com/dest:latest

Motivation: Occasionally, there is a need to copy a container image and its associated signatures to a different location or registry. The cosign copy command enables users to perform this operation securely.

Explanation: This command copies a container image (example.com/src:latest) and its signatures to a different location (example.com/dest:latest). The metadata and cryptographic signatures are also copied, ensuring the integrity and authenticity of the image and its signatures.

Example output:

Container image and its signatures copied successfully.

Conclusion:

The cosign command provides a secure and convenient way to sign, verify, and store container images and their signatures. By employing cryptographic signatures, cosign helps ensure the integrity and authenticity of container images, making it easier to trust and deploy containerized applications.