# Code signing workflows in Signer Code signing workflows The signing procedures for AWS services by Signer are service-specific workflows. The following topics describe workflows for signing IoT binaries, Lambda zip files, and container images. **Important** Steps common to all workflows have been covered in [Get started with AWS Signer](getting-started.md). Workflow steps in the following topics are not interchangeable. **Topics** + [ # Sign Internet of Things (IoT) objects ](iot-workflow.md) + [ # Sign AWS Lambda code ](lambda-workflow.md) + [ # Sign container images in Signer ](container-workflow.md) # Sign Internet of Things (IoT) objects Internet of Things (IoT) This section describes procedures for signing binary objects intended for deployment on Internet of Things (IoT) devices. Before you begin, make sure you have completed the prerequisites listed in [Get started with AWS Signer](getting-started.md). **Topics** + [ # Obtain and import a code-signing certificate ](obtain-cert.md) + [ # Create and populate an Amazon S3 source bucket for your unsigned object files ](s3-source-iot.md) + [ # Create an Amazon S3 destination bucket for your signed object files ](s3-destination-iot.md) + [ # Create a signing job for IoT in AWS Signer ](signing-jobs-iot.md) # Obtain and import a code-signing certificate Obtain certificate Before you can use AWS Signer with AWS IoT Device Management or Amazon FreeRTOS, you must have or obtain a code-signing certificate. Code-signing certificates typically contain a `Digital Signature` value in the `Key Usage` extension and a `Code Signing` value in the `Extended Key Usage` extension. ``` Certificate: Data: Version: 3 (0x2) Serial Number: 4111 (0x100f) Signature Algorithm: sha256WithRSAEncryption Issuer: C=US, ST=Washington, L=Seattle, O=Example Company, OU=Corp, CN=www.example.com/emailAddress=corp@www.example.com Validity Not Before: Nov 14 17:32:30 2017 GMT Not After : Nov 14 17:32:30 2018 GMT Subject: C=US, ST=Washington, L=Seattle, O=Example Company, OU=corp, CN=www.example.com Subject Public Key Info: Public Key Algorithm: rsaEncryption Public-Key: (2048 bit) Modulus: 00:ac:96:8f:64:1a:4d:5c:cc:e4:50:a9:19:f3:c1: 03:8f:1a:db:f5:15:18:65:fb:6e:3f:84:ae:02:9e: a2:e1:62:40:05:10:b6:35:59:63:c7:b3:17:4a:e1: 12:9f:29:42:e4:2b:bb:83:db:b1:cd:42:83:0a:9f: 70:ca:81:6a:9b:58:1d:4e:a0:69:04:bc:0b:f4:7e: 34:fc:af:79:f1:31:6c:7e:a5:eb:b1:85:9e:5e:ef: df:34:7c:aa:13:01:f5:cc:ee:a1:9c:d9:4d:17:e8: c8:8b:d0:77:2e:80:3f:7e:41:ea:84:2f:11:22:59: bd:fa:90:eb:26:ec:e7:b2:0e:9d:ce:b5:8a:a0:b9: 17:4c:8b:3a:b5:28:61:eb:d3:a6:ed:db:5c:26:e6: 7d:af:33:b6:9f:f0:9d:fb:fc:10:e0:52:cb:60:5c: 08:c3:33:4a:b4:8a:4e:3a:54:4e:43:3d:b9:f2:5e: 4e:89:95:c2:a5:df:88:a2:24:71:d3:ee:b3:ef:0b: 18:1d:55:54:16:ff:9b:95:6e:ae:71:d3:f2:d1:7e: f2:8b:67:34:f8:11:fe:ab:8f:6b:88:c3:b9:8e:1d: 07:bc:62:27:45:7e:0c:a0:7b:ef:bf:26:f8:50:df: ac:d8:8f:a5:ed:fe:9f:ee:20:dc:a6:33:3e:94:25: ce:67 Exponent: 65537 (0x10001) X509v3 extensions: X509v3 Basic Constraints: CA:FALSE X509v3 Subject Key Identifier: 22:93:86:26:D3:1B:32:1C:79:1B:5C:E4:EB:2A:6A:DB:77:87:D7:FB X509v3 Authority Key Identifier: keyid:0D:CE:76:F2:E3:3B:93:2D:36:05:41:41:16:36:C8:82:BC:CB:F8:A0 X509v3 Key Usage: Digital Signature X509v3 Extended Key Usage: Code Signing Signature Algorithm: sha256WithRSAEncryption 38:41:ba:c3:f0:88:97:3e:a1:0f:e3:d4:55:d6:d0:a2:4e:ac: da:83:67:27:49:23:88:9b:20:e1:e1:b7:55:78:3c:5a:9b:7a: 75:ee:3a:0f:ed:20:4e:23:31:29:ac:07:91:61:f1:86:75:08: fa:f5:3c:4a:7b:79:3c:39:a5:45:97:10:5c:f4:a0:04:af:e8: 5b:ca:d1:a5:ce:14:dc:14:c6:54:b1:ba:6a:2c:52:2c:2f:07: 52:8a:a7:00:97:c7:ee:65:bb:df:36:7f:53:d0:7d:a4:6e:ba: bb:d2:d4:b5:25:bb:b1:0d:bd:91:10:28:e1:34:df:79:01:78: 45:4e ``` **Important** We recommend that you purchase a code-signing certificate from a company with a good reputation for security. Do not use a self-signed certificate for any purpose other than testing. Encouraging your users to trust arbitrary certificates with no reputational backing is a poor security practice. After you have obtained the certificate, you must import it into AWS Certificate Manager (ACM). ACM returns an Amazon Resource Name (ARN) for the certificate. You must use the ARN when you call the [StartSigningJob](signer/latest/api/API_StartSigningJob.html) action. For more information about importing, see [Importing Certificates](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html) in the AWS Certificate Manager User Guide. # Create and populate an Amazon S3 source bucket for your unsigned object files Create source S3 bucket This topic discusses how to prepare an Amazon S3 bucket and add your unsigned object files to it. To create a bucket, sign into the AWS Management Console at [https://console.aws.amazon.com/console/home](https://console.aws.amazon.com/console/home) and follow the procedure in [Create your first S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html). While you are configuring the bucket, note the following requirements: + Accept the default security option **Block *all* public access**. + Set **Bucket Versioning** to **Enable**. After you create the bucket, you can add objects to it as described in the [Upload an object to your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-an-object-bucket.html) topic. # Create an Amazon S3 destination bucket for your signed object files Create destination S3 bucket This topic discusses how to prepare an Amazon S3 destination bucket where AWS Signer can deposit your signed object files. To create a bucket, sign into the AWS Management Console at [https://console.aws.amazon.com/console/home](https://console.aws.amazon.com/console/home) and follow the procedure in [Create your first S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html). While you are configuring the bucket, note the following requirement. + Accept the default security option **Block *all* public access**. # Create a signing job for IoT in AWS Signer Create a signing job To start a signing job, you need to specify the following: + The source S3 bucket of the IoT binary to be signed + A signing profile + The destination S3 bucket for the signed file A signing job has a status of `InProgress` while it is being processed, and after completion, the status changes to `Succeeded`. If Signer is unable to generate a signature, the signing job updates to `Failed`. Signing fails for a zip file if the file is empty, already has a signature, or is malformed. **To perform a signing job (CLI)** Use the following CLI commands to run and manage signing jobs. + [https://docs.aws.amazon.com/cli/latest/reference/signer/start-signing-job.html](https://docs.aws.amazon.com/cli/latest/reference/signer/start-signing-job.html) To get the status of a particular signing job, use the following action or command: + [https://docs.aws.amazon.com/cli/latest/reference/signer/describe-signing-job.html](https://docs.aws.amazon.com/cli/latest/reference/signer/describe-signing-job.html) For a list of all available signing jobs, including those in the Failed state, use the following action or command: + [https://docs.aws.amazon.com/cli/latest/reference/signer/list-signing-jobs.html](https://docs.aws.amazon.com/cli/latest/reference/signer/list-signing-jobs.html) **To perform a signing job (API)** Use the following API actions to run and manage signing jobs. + [https://docs.aws.amazon.com/signer/latest/api/API_StartSigningJob.html](https://docs.aws.amazon.com/signer/latest/api/API_StartSigningJob.html) + [https://docs.aws.amazon.com/signer/latest/api/API_DescribeSigningJob.html](https://docs.aws.amazon.com/signer/latest/api/API_DescribeSigningJob.html) + [https://docs.aws.amazon.com/signer/latest/api/API_ListSigningJobs.html](https://docs.aws.amazon.com/signer/latest/api/API_ListSigningJobs.html) For more information about configurations and parameters related to signing jobs, see [https://docs.aws.amazon.com/signer/latest/api/API_SigningJob.html](https://docs.aws.amazon.com/signer/latest/api/API_SigningJob.html) in the *AWS Signer API Reference.* # Sign AWS Lambda code AWS Lambda This section describes procedures for signing code intended for deployment on AWS Lambda. Before you begin, make sure you have completed the prerequisites listed in [Get started with AWS Signer](getting-started.md). **Topics** + [ # Create and populate an Amazon S3 source bucket for your unsigned object files ](s3-source-lambda.md) + [ # Create an Amazon S3 destination bucket for your signed object files ](s3-destination-lambda.md) + [ # Create a signing job for Lambda in AWS Signer ](signing-jobs-lambda.md) # Create and populate an Amazon S3 source bucket for your unsigned object files Creating source S3 bucket This topic discusses how to prepare an Amazon S3 bucket and add your unsigned object files it. To create a bucket, sign into the AWS Management Console at [https://console.aws.amazon.com/console/home](https://console.aws.amazon.com/console/home) and follow the procedure in [Create your first S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html). While you are configuring the bucket, note the following requirements: + Accept the default security option **Block *all* public access**. + Set **Bucket Versioning** to **Enable**. After you create the bucket, you can add objects to it as described in [Upload an object to your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-an-object-bucket.html) topic. # Create an Amazon S3 destination bucket for your signed object files Create destination S3 bucket This topic discusses how to prepare an Amazon S3 destination bucket where AWS Signer can deposit your signed object files. To create a bucket, sign into the AWS Management Console at [https://console.aws.amazon.com/console/home](https://console.aws.amazon.com/console/home) and follow the procedure in [Create your first S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html). While you are configuring the bucket, note the following requirements: + Accept the default security option **Block *all* public access**. # Create a signing job for Lambda in AWS Signer Create a signing job To start a signing job, you need to specify the following: + The source S3 bucket of the IoT code or Lambda zip file to be signed + A signing profile + The destination S3 bucket for the signed file A signing job has a status of `InProgress` while it is being processed, and after completion, the status changes to `Succeeded`. If Signer is unable to generate a signature, the signing job updates to `Failed`. Signing fails for a zip file if the file is empty, already has a signature, or is malformed. **To perform a signing job (console)** 1. Log into the AWS Signer console. 1. Choose **Start signing jobs**. 1. From the list of profiles, choose a signing profile to perform code signing for your Lambda application. 1. Do either of the following: + For **Code asset source location**, enter the URL for the Amazon S3 bucket that contains your code. + Choose **Browse**, and locate the S3 bucket that contains your code. **Note** Be sure your file is in zip format. The AWS Signer console does not accept other file formats. 1. Do one of the following: + In the **Signature Destination path with Prefix**, enter the URL for the S3 bucket where you store your signed code. + Choose **Browse** and locate the S3 bucket that stores your signed code. 1. Choose **Start**. AWS Signer updates the **Manage signing jobs** page with your new profile, and displays the following information: + **Job ID** – The generated ID number + **Profile name** – The name of the profile + **Signing status** – The signing status of the job + **Revocation status** – The status of the revocation if any 1. If you receive a **Failed** under **Signing status**, return to the list of the signing jobs, and choose **Failed** to see the details of the signing job. The **Signing job details** page lists the following information: + **Job ID** – The identifier of the signing job + **Signing profile used** – The signing profile used for the job + **Version of signing profiles used** – The version of the signing profile used for the job + **Requested by** – Identity of the requester of the job + **Signing platform** – The signing platform used for the job (Lambda only) + **Signing status** – The status of the job as either **Successful** or **Failed** + **Status reason** – Explanation for the failure if the signing job failed + **Started at** – The time and date that the signing job started + **Completed at** – The time and date that the job ended The **Code assets details** displays additional information: + **Code asset source bucket** – The S3 source bucket of the code file used + **Code asset source key** – The name of the code file used for signing code + **Code asset source version** – The version of the code file **To perform a signing job (AWS CLI)** Use the following command to start a signing job: + [https://docs.aws.amazon.com/cli/latest/reference/signer/start-signing-job.html](https://docs.aws.amazon.com/cli/latest/reference/signer/start-signing-job.html) To get the status of a particular signing job, use the following command: + [https://docs.aws.amazon.com/cli/latest/reference/signer/describe-signing-job.html](https://docs.aws.amazon.com/cli/latest/reference/signer/describe-signing-job.html) For a list of all available signing jobs, including those in the Failed state, use the following command: + [https://docs.aws.amazon.com/cli/latest/reference/signer/list-signing-jobs.html](https://docs.aws.amazon.com/cli/latest/reference/signer/list-signing-jobs.html) **To perform a signing job (API)** Following API actions can be used to run and track signing jobs. + [https://docs.aws.amazon.com/signer/latest/api/API_StartSigningJob.html](https://docs.aws.amazon.com/signer/latest/api/API_StartSigningJob.html) + [https://docs.aws.amazon.com/signer/latest/api/API_DescribeSigningJob.html](https://docs.aws.amazon.com/signer/latest/api/API_DescribeSigningJob.html) + [https://docs.aws.amazon.com/signer/latest/api/API_ListSigningJobs.html](https://docs.aws.amazon.com/signer/latest/api/API_ListSigningJobs.html) For more information about configurations and parameters related to signing jobs, see [https://docs.aws.amazon.com/signer/latest/api/API_SigningJob.html](https://docs.aws.amazon.com/signer/latest/api/API_SigningJob.html) in the *AWS Signer API Reference.* # Sign container images in Signer Container images This section describes procedures for signing container images stored in an Open Container Initiative (OCI) compliant container registry. Before you begin, make sure you have completed the prerequisites listed in [Get started with AWS Signer](getting-started.md). **Note** If you're coming here from the Amazon ECR image signing documentation, be aware that you must fulfill all of the requirements related to Amazon ECR before beginning these AWS Signer procedures. For more information, see [Signing an image](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-signing.htm) in the *Amazon Elastic Container Registry User Guide*. **Topics** + [ # Prerequisites for signing container images ](image-signing-prerequisites.md) + [ # Sign an image ](image-signing-steps.md) + [ # Locally verify an image after signing ](image-verification.md) + [ # Verify an image during in Amazon EKS or Kubernetes clusters ](kubernetes-verification.md) # Prerequisites for signing container images PrerequisitesSigner open source library now available Adds a link to the Signer open source library. You now have the option of using the Signer binary or the open source library. Before you begin signing, you need to set up an environment that bridges AWS Signer with Amazon ECR. Complete the following steps. **To prepare your signing environment** 1. **Prepare the AWS CLI** Install and configure the latest version of the AWS CLI. For more information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. 1. **Prepare Amazon ECR** Have an existing container image stored in an Amazon ECR private repository to sign. For more information, see [Pushing an image](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-push.html) in the *Amazon Elastic Container Registry User Guide*. 1. **Download the container-signing tools** Two software packages need to be installed in your local environment for you to sign images: + The open source supply chain security program Notation, developed by the [Notary Project](https://notaryproject.dev/) + The AWS Signer plugin for Notation. You can either use our plugin binary, or our open source library. ------ #### [ Plugin binary ] The AWS Signer installer installs both the Notation client and the AWS Signer plugin for Notation. Separate binaries are available to install only the AWS Signer plugin. The installer includes the following. + Notation binary and third party license. + AWS Signer plugin binary and third party license. + Notation license. + Trust store set up with AWS Signer's Notation signing [root certificate](https://d2hvyiie56hcat.cloudfront.net/aws-signer-notation-root.cert). + GovCloud trust store and [root certificate](https://d2hvyiie56hcat.cloudfront.net/aws-us-gov-signer-notation-root.cert), for use in the AWS GovCloud (US) Region. + A configurable trust policy. For information about configuring the trust policy, see [Locally verify an image after signing](image-verification.md). The following table provides the installer and related files for each supported operating system and architecture. You can download our latest [CHANGELOG](https://d2hvyiie56hcat.cloudfront.net/CHANGELOG) to see the versions of the Notation CLI and plugin included in each installer release. **Notation binary and AWS Signer Plugin installer files** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/signer/latest/developerguide/image-signing-prerequisites.html) ------ #### [ Open source library ] The open source Signer plugin is available as a library for use with your toolchain to generate and verify container artifacts signatures. Access the source code and instructions to build the Signer plugin in the [Signer Notation plugin Github repository](https://github.com/aws/aws-signer-notation-plugin). ------ 1. **(Optional) Verify signed packages.** For instructions to complete this step, select the tab for your platform. ------ #### [ Linux ] 1. Download the public key. ``` $ ​wget https://d2hvyiie56hcat.cloudfront.net/linux/public.key ``` 1. Import the public key into your keyring. If you're using the unzip the AWS Signer plugin, first unzip downloaded file and then run command against the binary file within the zip file. ``` $ gpg --import public.key gpg: key A3B52DA65461CF90: public key "AWS Signer Notation" imported gpg: Total number processed: 1 gpg: imported: 1 ``` ​Make a note of the key value, as you need it in the next step. In the preceding example, the key value is `A3B52DA65461CF90`. 1. Verify the fingerprint by running the following command, replacing **key-value** with the value from the preceding step: ``` $ gpg --fingerprint key-value pub rsa3072 2023-04-24 [SC] E84A F8A2 A9B5 2F1F 4435 AE71 A3B5 2DA6 5461 CF90 uid [ unknown] AWS Signer Notation​ ``` The fingerprint string should be `E84A F8A2 A9B5 2F1F 4435 AE71 A3B5 2DA6 5461 CF90`. If the fingerprint string doesn't match, don't run the installer. Contact Amazon Web Services. After you have verified the fingerprint, you can use it to verify the signature of the AWS Signer Notation package. 1. Download the package signature file using **wget**. To determine the correct signature file, see the preceding table. ``` $ ​wget signature-file-link ``` 1. To verify the signature, run gpg --verify: ``` $ gpg --verify sig-filename downloaded-filename gpg: Signature made Mon May 22 16:16:34 2023 PDT gpg: using RSA key A3B52DA65461CF90 gpg: Good signature from "AWS Signer Notation" [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: E84A F8A2 A9B5 2F1F 4435 AE71 A3B5 2DA6 5461 CF90​ ``` If the output includes the phrase *BAD signature*, check whether you performed the procedure correctly. If you continue to get this response, contact Amazon Web Services and avoid using the downloaded file.​ Note the warning about *trust*. A key is trusted only if you or someone who you trust has signed it. This doesn't mean that the signature is invalid, only that you have not verified the public key. ------ #### [ Windows ] To verify the signature of the MSI installer or the plugin EXE file, using Windows PowerShell run the following command: ``` C:\> ​Get-AuthenticodeSignature filename ``` You can also verify the signature by right-clicking on the file in an Explorer window, choosing **Properties**, and then choosing **Digital Signatures**. ​You should see a result similar to the following:​ ``` SignerCertificate Status Path ----------------- ------ ---- [40-character hexamecimal number] Valid downloaded-file​​ ``` ------ #### [ MacOS ] 1. To verify the signature of the PKG installer, run the following command. This example uses the amd64 package, but the signature of the arm64 package can be verified similarly. ``` $ ​pkgutil --check-signature ​aws-signer-notation-cli_amd64.pkg ``` You should see a result similar to the following: ``` ​Package "aws-signer-notation-cli_amd64.pkg": Status: signed by a developer certificate issued by Apple for distribution Notarization: trusted by the Apple notary service Signed with a trusted timestamp on: 2023-05-19 15:17:15 +0000 Certificate Chain: 1. Developer ID Installer: AMZN Mobile LLC (94KV3E626L) Expires: 2027-06-28 22:57:06 +0000 SHA256 Fingerprint: 49 68 39 4A BA 83 3B F0 CC 5E 98 3B E7 C1 72 AC 85 97 65 18 B9 4C BA 34 62 BF E9 23 76 98 C5 DA ------------------------------------------------------------------------ 2. Developer ID Certification Authority Expires: 2031-09-17 00:00:00 +0000 SHA256 Fingerprint: F1 6C D3 C5 4C 7F 83 CE A4 BF 1A 3E 6A 08 19 C8 AA A8 E4 A1 52 8F D1 44 71 5F 35 06 43 D2 DF 3A ------------------------------------------------------------------------ 3. Apple Root CA Expires: 2035-02-09 21:40:36 +0000 SHA256 Fingerprint: B0 B1 73 0E CB C7 FF 45 05 14 2C 49 F1 29 5E 6E DA 6B CA ED 7E 2C 68 C5 BE 91 B5 A1 10 01 F0 24​ ``` 1. To verify the signature of the AWS Signer Notation plugin executable, run the following command. ``` $ ​codesign -dv --verbose=4 ./notation-com.amazonaws.signer.notation.plugin ``` ​You should see a result similar to the following. ``` Executable=/path/to/notation-com.amazonaws.signer.notation.plugin Identifier=notation-com.amazonaws.signer.notation.plugin_darwin_arm64 Format=Mach-O thin (arm64) CodeDirectory v=20500 size=74278 flags=0x10000(runtime) hashes=2314+2 location=embedded VersionPlatform=1 VersionMin=720896 VersionSDK=720896 Hash type=sha256 size=32 CandidateCDHash sha256=e4000dbdf4e6243be9d290b1520d95bf9027a5e4 CandidateCDHashFull sha256=e4000dbdf4e6243be9d290b1520d95bf9027a5e42b699a354fc39ac0f498477f Hash choices=sha256 CMSDigest=e4000dbdf4e6243be9d290b1520d95bf9027a5e42b699a354fc39ac0f498477f CMSDigestType=2 Executable Segment base=0 Executable Segment limit=3571712 Executable Segment flags=0x1 Page size=4096Launch Constraints:None CDHash=e4000dbdf4e6243be9d290b1520d95bf9027a5e4 Signature size=9070 Authority=Developer ID Application: AMZN Mobile LLC (94KV3E626L) Authority=Developer ID Certification Authority Authority=Apple Root CATimestamp=May 19, 2023 at 7:51:07 AM Info.plist=not bound TeamIdentifier=94KV3E626L Runtime Version=11.0.0 Sealed Resources=none Internal requirements count=1 size=220 ``` ------ 1. **Install the packages** For instructions to complete this step, select the tab for your platform. ------ #### [ Linux (RPM) ] If you downloaded an RPM package on a Linux server, change to the directory containing the package and enter the following: ``` $ ​sudo rpm -U filename ``` ------ #### [ Linux (DEB) ] If you downloaded a DEB package on a Linux server, change to the directory containing the package and enter the following: ``` $ ​sudo dpkg -i -E filename ``` ------ #### [ Windows ] Install the package with the following command. ``` C:\> msiexec /i filename ``` This command also works from within PowerShell. For more information, see [Microsoft Standard Installer command-line options ](https://learn.microsoft.com/en-us/windows/win32/msi/standard-installer-command-line-options)in the Microsoft Windows documentation. ------ #### [ MacOS ] If you downloaded a PKG package on a macOS server, change to the directory containing the package and enter the following: ``` $ ​sudo installer -pkg filename -target / ``` ------ 1. **Verify the package installation** After downloading and installing the package, to verify the installation was successful, do the following. 1. Verify that the Notation directory structure for your operating system was created. 1. Use the following command to display the Notation client version. ``` notation version ``` 1. 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 ``` ## Required AWS Identity and Access Management permissions to sign and verify a container image To sign and verify an image present in Amazon Elastic Container Registry, you need an AWS Identity and Access Management policy that allows Notation to interact with Amazon ECR and Signer. The following is an example of a user managed policy that allows Notation to interact with Amazon ECR and Signer: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ManageRepositoryContents", "Effect": "Allow", "Action": [ "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage", "ecr:CompleteLayerUpload", "ecr:DescribeRepositories", "ecr:UploadLayerPart", "ecr:InitiateLayerUpload", "ecr:BatchCheckLayerAvailability", "ecr:PutImage" ], "Resource": "arn:aws:ecr:us-east-1:111122223333:repository/my-repo" }, { "Sid": "GetAuthorizationToken", "Effect": "Allow", "Action": [ "ecr:GetAuthorizationToken" ], "Resource": "*" }, { "Sid": "SignAndRevocationCheck", "Effect": "Allow", "Action": [ "signer:PutSigningProfile", "signer:SignPayload", "signer:GetRevocationStatus" ], "Resource": "*" } ] } ``` ------ # Sign an image The procedures on this page show you how create a signing profile, install a helper program, and sign a container image. ## Step 1: Create a AWS Signer Notation signing profile Create an AWS Signer Notation signing profile. If using the AWS Command Line Interface, API, AWS CloudFormation, or AWS SDKs set the platform ID to `Notation-OCI-SHA384-ECDSA`. In the console, for **signing platform** choose **Notation for container registries**. For more information on creating a signing profile, see [Create a Signer signing profile](signing-profiles.md). ## Step 2: Install a helper program Notation requires you to include a helper program in the client's host path in order to interact with the credential store. You can use either the [Amazon Elastic Container Registry Docker credential helper](https://github.com/awslabs/amazon-ecr-credential-helper) or the [Docker credential helper](https://github.com/docker/docker-credential-helpers) to manage your credentials. We recommend using the Amazon ECR Docker credential helper, as it includes a credentials store and handles authentication for you. The Amazon ECR Docker Credential Helper not only stores and uses credentials when signing and verifying images in Amazon ECR, but also eliminates the need to use the Notation CLI notation login command or write custom logic to refresh authentication tokens and provide transparent access to your Amazon ECR repositories. ### Amazon ECR Docker credential helper Download the [Amazon Elastic Container Registry Docker credential helper](https://github.com/awslabs/amazon-ecr-credential-helper). Configure `config.json` for use with Amazon ECR. ### Docker credential helper The following procedure explains how to install and configure the Docker credential helper. **To use the Docker credential helper** 1. First set up a credentials store. Notation relies on a credentials store for secure storage and retrieval of credentials from Amazon ECR. Most operating systems come with a default credentials store, such as osxkeychain for macOS, or wincred for Windows. If you have the Docker CLI installed on the same host where Notation is installed, Notation uses the credentials store configuration that you set up for the Docker CLI. Alternatively, you can install a third-party credentials store such as [pass](https://www.passwordstore.org). You can pass these credentials to Notation as environment variables. For more information about environment variables, see [Configure environment variables to authenticate to an OCI-compliant registry](https://notaryproject.dev/docs/user-guides/how-to/registry-authentication/#configure-environment-variables-to-authenticate-to-an-oci-compliant-registry) in the Notary Project user guide. 1. Download the [Docker credential helper](https://github.com/docker/docker-credential-helpers). Set the `credsStore` option in `config.json` to the suffix of the program that you want to use. 1. Manually configure Notation client authentication. Because the Notation CLI doesn't support standard AWS authentication methods, you must manually configure Notation client authentication so that Amazon ECR knows who's requesting to sign (push signature) or verify (pull signature) an image. You can accomplish this with the Notation CLI `notation login` command, which authenticates to an Amazon ECR registry and provides an authorization token that's valid for 12 hours. Or, if you’re using the AWS Command Line Interface, you can use the `get-login-password` command which retrieves the token, decodes it, and converts into a `notation login` command for you. The following command allows Notation to get credentials for authenticating with Amazon ECR: ``` aws ecr get-login-password --region us-west-1 | notation login --username AWS --password-stdin 111122223333.dkr.ecr.us-west-1.amazonaws.com ``` ## Step 3: Sign the image using the Notation CLI Use the Notation CLI to sign the image, specifying the image using the repository name and the SHA256 digest. This creates the signature and pushes it to the same Amazon ECR private repository that the image being signed is in. **Note** You can specify the AWS Region and credentials profile that the Notation plugin uses for interactions with AWS Signer either by setting values for the `AWS_DEFAULT_REGION` and `AWS_PROFILE` environment variables or by providing the arguments **--plugin-config aws-region=\$1\$1*Region*\$1** and **--plugin-config aws-profile=\$1\$1*profile-name*\$1** In the following example, we're 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" ``` ## Step 4: Verify image After you have signed your container image, you can verify the signature locally or during an Amazon EKS deployment and further manage the signature with Amazon ECR. + [Locally verify an image after signing](image-verification.md) + [Verify an image during in Amazon EKS or Kubernetes clusters](kubernetes-verification.md) + [Manage your signature in your Amazon ECR repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-signing.html) in the *Amazon Elastic Container Registry User Guide*. # Locally verify an image after signing Locally verify an imageAdded caveat about image verification in AWS GovCloud (US) Region To verify images signed using a signing profile created in an AWS GovCloud (US) Region, you must set `signingAuthority` to `aws-us-gov-signer-ts` in your trust policy. 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 for both AWS commercial and AWS GovCloud (US) Regions was set up automatically and provisioned with a root certificate. For more information, see [Prerequisites for signing container images](image-signing-prerequisites.md). 1. Set up a trust policy that includes the trust store for your partition. The following example includes trust stores for both the AWS commercial and AWS GovCloud (US) Region. You can choose to include one or both in your trust policy depending on where you are verifying your signed images. To verify images signed in AWS commercial Regions, set `signingAuthority` to `aws-signer-ts`. To verify images signed in AWS GovCloud (US) Region, set `signingAuthority` to `aws-us-gov-signer-ts`. **Important** Signatures are isolated to AWS partitions. Calls to [GetRevocationStatus](https://docs.aws.amazon.com/signer/latest/api/API_GetRevocationStatus.html) with a cross-partition signature will return a validation exception error. ``` { "version":"1.0", "trustPolicies":[ { "name":"aws-signer-tp", "registryScopes":[ "*" ], "signatureVerification":{ "level":"strict" }, "trustStores":[ "signingAuthority:aws-signer-ts", "signingAuthority:aws-us-gov-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 ``` Output: ``` Existing trust policy configuration found, do you want to overwrite it? [y/N] y Trust policy configuration imported successfully. ``` 1. Verify the signature, specifying the signature using the repository name and the SHA digest. **Note** You can specify the AWS Region and credentials profile that the Notation plugin uses to interact with AWS Signer by assigning a value to the `AWS_PROFILE` environment variable, or by passing the **--plugin-config aws-profile=\$1\$1*profile-name*\$1** argument to the Notation **verify** command. ``` $ notation verify 111122223333.dkr.ecr.region.amazonaws.com/curl@SHA256_digest ``` Output: ``` Successfully verified signature for 111122223333.dkr.ecr.us-west-2.amazonaws.com/curl@SHA256_digest ``` # Verify an image during in Amazon EKS or Kubernetes clusters Verify an image on Amazon EKS 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. + [Deis Labs Gatekeeper and Ratify](https://ratify.dev/docs/quickstarts/ratify-on-aws) – Use Gatekeeper as the admission controller and Ratify configured with an AWS Signer plug-in as a web hook for validating signatures. + [Kyverno](https://github.com/nirmata/kyverno-notation-aws) – A Kubernetes policy engine configured with a AWS Signer plugin for validating signatures. **Note** Before verifying container-image signatures, customers must configure the Notation trust store and trust policy as required by their selected admission controller.