Add example using AWS Key Management Service (KMS) (#1564)

Signed-off-by: Davi Garcia <davcgar@amazon.com>

EXAMPLES.md

@@ -24,6 +24,7 @@ $ gcloud kms keys versions get-public-key 1 --key=foo --keyring=foo --location=u
 # Verify in openssl
 $ openssl dgst -sha256 -verify pubkey.pem -signature gcpkms.sig payload
 ```
+
 ## Sign With OpenSSL, Verify With Cosign
 
 ```shell
@@ -45,4 +46,47 @@ The following checks were performed on each of these signatures:
   - The signatures were verified against the specified public key
   - Any certificates were verified against the Fulcio roots.
 {"critical":{"identity":{"docker-reference":"us.gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155"},"type":"cosign container image signature"},"optional":null}
+```
+
+## AWS KMS with `aws`
+
+Use `aws` (CLI version 2) to create a CMK for sign and verification (just need this once):
+
+```shell
+$ export AWS_CMK_ID=$(aws kms create-key --customer-master-key-spec RSA_4096 \
+                                   --key-usage SIGN_VERIFY \
+                                   --description "Cosign Signature Key Pair" \
+                                   --query KeyMetadata.KeyId --output text)
+```
+
+Use `cosign` to generate the payload, sign it with `aws kms`, then use `cosign` to upload it.
+
+```shell
+$ cosign generate docker.io/davivcgarcia/hello-world:latest > payload.json
+
+$ aws kms sign  --key-id $AWS_CMK_ID \
+              --message file://payload.json \
+              --message-type RAW \
+              --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
+              --output text \
+              --query Signature > payload.sig
+
+$ cosign attach signature docker.io/davivcgarcia/hello-world:latest --signature $(< payload.sig)
+```
+
+Now (on another machine) use the `cosign` to download signature bundle, extract payload and signature value, and verify it with `aws kms`!
+
+```shell
+$ cosign download signature docker.io/davivcgarcia/hello-world:latest > signatures.json
+
+$ cat signatures.json | tail -1 | jq -r .Base64Signature | base64 -D > remote_payload.sig
+$ cat signatures.json | tail -1 | jq -r .Payload | base64 -D > remote_payload.json
+
+$ aws kms verify --key-id $AWS_CMK_ID \
+               --message file://remote_payload.json \
+               --message-type RAW \
+               --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
+               --signature fileb://remote_payload.sig \
+               --output text \
+               --query SignatureValid
 ```

KMS.md

@@ -95,6 +95,19 @@ The following URIs are valid:
 - Alias ARN: `awskms:///arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias`
 - Alias ARN with endpoint: `awskms://localhost:4566/arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias`
 
+Example:
+
+```shell
+$ export AWS_REGION=us-east-1
+$ export AWS_CMK_ID=$(aws kms create-key --customer-master-key-spec RSA_4096 \
+                                         --key-usage SIGN_VERIFY \
+                                         --description "Cosign Signature Key Pair" \
+                                         --query KeyMetadata.KeyId --output text)
+
+$ cosign sign --key awskms:///${AWS_CMK_ID} docker.io/davivcgarcia/hello-world:latest
+$ cosign verify --key awskms:///${AWS_CMK_ID} docker.io/davivcgarcia/hello-world:latest | jq .
+```
+
 ### GCP
 
 GCP KMS keys can be used in `cosign` for signing and verification.