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

Cosign is a tool designed to improve the security of container images by enabling the signing, verification, and storage of these images and other related artifacts in an OCI (Open Container Initiative) registry. With increased focus on supply chain security, cosign offers a transparent and auditable way to confirm the integrity and origin of a container image using cryptographic signatures.

Use case 1: Generate a key-pair

Code:

cosign generate-key-pair

Motivation: Generating a key-pair is a fundamental step in using cosign, as it provides you with a private and a public key essential for signing and verifying container images. The process of creating these keys is similar to setting up a bank account, where you receive a PIN (private key) and a bank card (public key) to perform secure transactions.

Explanation: The cosign generate-key-pair command initiates the creation of an asymmetric key-pair. This involves two keys: a private key (cosign.key) which should be kept secure and confidential, and a public key (cosign.pub) which can be shared freely. Cosign uses these keys to perform cryptographic signing of container images and verification, ensuring image integrity and trust.

Example Output:

Enter password for private key:
Enter password for private key again:

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 ensures its integrity by attaching a cryptographic signature which can be verified at any time. This is akin to signing a document, thereby confirming its authenticity. Storing the signature in the registry enables automation and integration into a wider security posture, benefiting developers and auditors who need to verify whether an image has remained untouched since its signing.

Explanation:

• sign: This sub-command is used to sign the container image.
• -key cosign.key: Specifies the private key (cosign.key) used to sign the image. It implies that you have previously generated this key and stored it securely.
• image: This placeholder represents the container image you wish to sign, typically identified in common registry notation, such as docker.io/library/nginx:latest.

Example Output:

Pushing signature to: <registry_path_of_signature>

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: Using Kubernetes secrets to store key pairs is beneficial for securing sensitive information in a cloud-native environment, such as a Kubernetes cluster. This approach seamlessly integrates with your Kubernetes resources, allowing you to automate the signing process and manage secrets centrally without exposing private keys across your infrastructure.

Explanation:

• sign: Sub-command for signing the container image.
• -key k8s://namespace/key: Specifies that the private key is stored in a Kubernetes secret. Here, namespace should be replaced with the Kubernetes namespace where the secret resides, and key with the name of the secret itself.
• image: Represents the container image you wish to sign.

Example Output:

Using key material from k8s://namespace/key
Pushing signature to: <registry_path_of_signature>

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

Code:

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

Motivation: Containers aren’t the only assets needing security; sometimes, you need to ensure the integrity of individual files (blobs). You might do this when adding critical configuration files or specific binaries into your service architecture, similar to signing digital invoices in a business setting.

Explanation:

• sign-blob: Command to sign a single file (or blob), rather than a container image.
• --key cosign.key: Provides the path to the local private key file used for signing.
• path/to/file: Represents the path to the actual file or artifact you wish to sign.

Example Output:

{"Critical":{"Identity":{},"Image":null,"Timestamp":"2023-04-29T12:01:57Z"},"Optional":{}}

Use case 5: Verify a container against a public key

Code:

cosign verify -key cosign.pub image

Motivation: To ensure a container image has not been tampered with, verification against a public key is essential. This is like matching the signature on a signed letter with a signature specimen to confirm authenticity, thus ensuring the image retains its intended contents from the trusted source.

Explanation:

• verify: The command to check the validity of the container image’s signature.
• -key cosign.pub: Specifies the public key used to authenticate the image’s signature.
• image: Denotes the container image you are verifying.

Example Output:

The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were validated against the specified 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: Integrating security checks directly into Dockerfiles ensures that the build process only uses verified images. It injects a check-point in containerized application development, ensuring that every component is verified similarly to how a chef checks ingredients before preparation.

Explanation:

• dockerfile verify: A command specific to verifying a Dockerfile’s image signatures.
• -key cosign.pub: Public key used to verify the container image signatures within the Dockerfile.
• path/to/Dockerfile: Path to the Dockerfile containing references to images that need verification.

Example Output:

Verified image references in Dockerfile:
- Image: docker.io/library/alpine
  Verification successful

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

Code:

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

Motivation: By storing public keys in Kubernetes secrets, you orchestrate a streamlined process for verification across multiple environments. It aids in redundant management across clusters and facilitates dynamic applications monitoring, much like banks using centralized encryption keys across different branches.

Explanation:

• verify: The command for validating the container image signature.
• -key k8s://namespace/key: Indicates that the public key for verification is stored as a Kubernetes secret. Replace namespace with your cluster’s namespace and key with the name of the secret.
• image: Represents the container image to verify.

Example Output:

Fetching key from k8s://namespace/key
The following checks were performed on the specified signature:
  - Cosign claims validated
  - Signatures authenticated with the provided public key

Use case 8: Copy a container image and its signatures

Code:

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

Motivation: The ability to duplicate container images with their respective signatures allows for smooth transitions between environments and supports compliance with distributed or hybrid cloud layouts. It’s much like having the ability to photocopy a notarized document and retain its legal standing in another jurisdiction.

Explanation:

• copy: Command to duplicate a container image and its associated signatures.
• example.com/src:latest: Represents the source registry where the image currently resides.
• example.com/dest:latest: Indicates the target registry receiving the image copy and its signatures.

Example Output:

Copying image and signatures from example.com/src:latest to example.com/dest:latest
Copy complete

Conclusion:

Cosign is a robust utility that addresses the pressing need for enhanced security in containerized environments. Through these examples, users can understand how cosign facilitates crucial actions like signing, verifying, and securely managing container image signatures, making it an indispensable tool in modern DevOps and cloud-native workflows.