Container image signing

You can use container image signing to help ensure the use of approved images inside your organization, which can help you meet your security and compliance requirements. You can sign and verify container images anytime during the development or deployment phases. You begin by creating a signing profile, a unique AWS Signer identity, to cryptographically sign images in your repository with client-side tools. Signer manages the signing keys, rotates code signing certificates, provides audit logs, and stores the signatures alongside your images. Amazon EKS and Kubernetes customers can choose their preferred admission controllers – like Gatekeeper or Kyverno, or develop their own tooling – to help enforce image verification before deploying images.

Prerequisites for signing container images
To prepare your signing environment

1. Prepare the AWS CLI - Install and configure the latest version of the AWS CLI. Installing or updating the latest version of the AWS CLI
2. Prepare Amazon ECR - Have an existing container image stored in an Amazon ECR private repository to sign. Pushing an image
3. Download the container-signing tools Two software packages need to be installed in your local environment for you to sign images:

• The AWS Signer plugin for Notation
• The open source supply chain security program Notation, developed by the Notary Project AWS Signer provides an installer, which installs both the AWS Signer plugin for Notation and the Notation client. Separate installers are available for the AWS Signer plugin alone and the combined AWS Signer plugin with the Notation binary.

The installer includes the following.

• Notation binary and third party license
• AWS Signer plugin binary and third party license
• Notation license
• Trust store and root certificate
• A configurable trust policy

To download the required files to a Linux or MacOS environment, you can use wget:
$ wget download-link

On a Windows environment, you can use curl:
curl -UseBasicParsing download-link -o [filename].msi

1. Install the packages
2. Verify the package installation After downloading and installing the package, to verify the installation was successful, do the following. a). Verify that the Notation directory structure for your operating system was created. For more information, see Notation directory structure for system configuration in the Notation documentation. b). Use the following command to display the Notation client version.

notation version

c). Use the following command to list the installed plugins for the Notation client and verify that you see the com.amazonaws.signer.notation.plugin plugin.

notation plugin ls

Procedure for signing an image
The following steps can be used to create the resources necessary to sign a container image and store the signature in an Amazon ECR private repository. Notation signs images using the digest.
To sign an image

1. Create an AWS Signer signing profile using the Notation-OCI-SHA384-ECDSA signing platform. You can optionally specify a signature validity period using the --signature-validity-period parameter. This value may be specified using DAYS, MONTHS, or YEARS. If no validity period is specified, the default value of 135 months is used.

aws signer put-signing-profile --profile-name ecr_signing_profile --platform-id Notation-OCI-SHA384-ECDSA

1. Authenticate the Notation client to your default registry. The following example uses the AWS CLI to authenticate the Notation CLI to an Amazon ECR private registry.

aws ecr get-login-password --region region | notation login --username AWS --password-stdin 111122223333.dkr.ecr.region.amazonaws.com

1. Use the Notation CLI to sign the image, specifying the image using the repository name and the SHA digest. This creates the signature and pushes it to the same Amazon ECR private repository that the image being signed is in.

In the following example, we are signing an image in the curl repository with SHA digest sha256:ca78e5f730f9a789ef8c63bb55275ac12dfb9e8099e6EXAMPLE.

notation sign 111122223333.dkr.ecr.region.amazonaws.com/curl@sha256:ca78e5f730f9a789ef8c63bb55275ac12dfb9e8099e6EXAMPLE --plugin "com.amazonaws.signer.notation.plugin" --id "arn:aws:signer:region:111122223333:/signing-profiles/ecrSigningProfileName"

Verify an image locally after signing
After you sign a container image using AWS Signer and Notation, you or an authorized member of your team can verify the origin and integrity of the image by cryptographic means.
Complete the following steps to verify that an image is valid with Notation.
To verify an image

1. A trust store is required for verification. If you used the installer for the AWS Signer plugin and Notation, a trust store was set up automatically and provisioned with a root certificate.
2. Set up a trust policy similar to the one below, modifying as needed the names of the signing profiles you are using to verify images.

{
   "version":"1.0",
   "trustPolicies":[
      {
         "name":"aws-signer-tp",
         "registryScopes":[
            "*"
         ],
         "signatureVerification":{
            "level":"strict"
         },
         "trustStores":[
            "signingAuthority:aws-signer-ts"
         ],
         "trustedIdentities":[
            "arn:aws:signer:region:111122223333:/signing-profiles/ecr_signing_profile",
            "arn:aws:signer:region:111122223333:/signing-profiles/ecr_signing_profile2"
         ]
      }
   ]
}

1. Import the policy into Notation.

notation policy import mypolicy.json

1. Verify the signature, specifying the signature using the repository name and the SHA digest.

notation verify 111122223333.dkr.ecr.region.amazonaws.com/curl@SHA256_digest

Verifying an image during deployment on Amazon EKS or Kubernetes clusters
For AWS Signer customers wishing to verify signed container images at the time of deployment, there are various open-source solutions such as the following.

• Gatekeeper and Ratify – Use Gatekeeper as the admission controller and Ratify configured with an AWS Signer plugin as a web hook for validating signatures.

• Kyverno – A Kubernetes policy engine configured with a AWS Signer plugin for validating signatures.