|
| 1 | +# Sign and verify an artifact with a certificate signed by a trusted CA in Azure Key Vault |
| 2 | +> **Note** The following guide can be executed on Linux bash, macOS Zsh and Windows WSL |
| 3 | +1. [Install the Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) |
| 4 | +2. Log in to Azure with Azure CLI, set the subscription and make sure the `GetCertificate` and `Sign` permission have been granted to your role: |
| 5 | + ```sh |
| 6 | + az login |
| 7 | + az account set --subscription $subscriptionID |
| 8 | + ``` |
| 9 | +3. Create an Azure Key Vault: |
| 10 | + ```sh |
| 11 | + resourceGroup=<your-resource-group-name> |
| 12 | + keyVault=<your-key-vault-name> |
| 13 | + location=westus |
| 14 | + certName=notationLeafCert |
| 15 | + |
| 16 | + # create a resource group |
| 17 | + az group create -n $resourceGroup -l $location |
| 18 | + |
| 19 | + # create a Azure Key Vault |
| 20 | + az keyvault create -l $location -n $keyVault --resource-group $resourceGroup |
| 21 | + ``` |
| 22 | +4. Create a Certificate Signing Request (CSR): |
| 23 | + ```sh |
| 24 | + # generate certificate policy |
| 25 | + cat <<EOF > ./leafCert.json |
| 26 | + { |
| 27 | + "issuerParameters": { |
| 28 | + "certificateTransparency": null, |
| 29 | + "name": "Unknown" |
| 30 | + }, |
| 31 | + "keyProperties": { |
| 32 | + "curve": null, |
| 33 | + "exportable": false, |
| 34 | + "keySize": 2048, |
| 35 | + "keyType": "RSA", |
| 36 | + "reuseKey": true |
| 37 | + }, |
| 38 | + "secretProperties": { |
| 39 | + "contentType": "application/x-pem-file" |
| 40 | + }, |
| 41 | + "x509CertificateProperties": { |
| 42 | + "ekus": [ |
| 43 | + "1.3.6.1.5.5.7.3.3" |
| 44 | + ], |
| 45 | + "keyUsage": [ |
| 46 | + "digitalSignature" |
| 47 | + ], |
| 48 | + "subject": "CN=Test-Signer,C=US,ST=WA,O=notation", |
| 49 | + "validityInMonths": 12 |
| 50 | + } |
| 51 | + } |
| 52 | + EOF |
| 53 | +
|
| 54 | + # create the leaf certificate |
| 55 | + az keyvault certificate create -n $certName --vault-name $keyVault -p @leafCert.json |
| 56 | +
|
| 57 | + # get the CSR |
| 58 | + CSR=$(az keyvault certificate pending show --vault-name $keyVault --name $certName --query 'csr' -o tsv) |
| 59 | + CSR_PATH=${certName}.csr |
| 60 | + printf -- "-----BEGIN CERTIFICATE REQUEST-----\n%s\n-----END CERTIFICATE REQUEST-----\n" $CSR > ${CSR_PATH} |
| 61 | + ``` |
| 62 | +5. Please take `${certName}.csr` file to a trusted CA to sign and issue your certificate, or you can use `openssl` tool to sign it locally for testing. |
| 63 | +6. After you get the leaf certificate, you can merge the leaf certificate (`$leafCert`) to your Azure Key Vault: |
| 64 | + ```sh |
| 65 | + az keyvault certificate pending merge --vault-name $keyVault --name $certName --file $leafCert |
| 66 | +
|
| 67 | + # get the key identifier |
| 68 | + keyID=$(az keyvault certificate show -n $certName --vault-name $keyVault --query 'kid' -o tsv) |
| 69 | + ``` |
| 70 | +7. [Create an Azure Container Registry](https://learn.microsoft.com/azure/container-registry/container-registry-get-started-portal?tabs=azure-cli). The remaining steps use the example login server `<registry-name>.azurecr.io`, but you must substitute your own login server value. |
| 71 | +8. Log in to container registry and push an image for signing: |
| 72 | + ```sh |
| 73 | + registryName="<registry-name>" |
| 74 | + server="${registryName}.azurecr.io" |
| 75 | + |
| 76 | + az acr login --name $registryName |
| 77 | + # notation login $server # if you don't use Azure Container Registry |
| 78 | +
|
| 79 | + # push a hello-world image for signing |
| 80 | + docker pull hello-world:latest |
| 81 | + docker tag hello-world:latest $server/hello-world:v1 |
| 82 | + docker push $server/hello-world:v1 |
| 83 | + ``` |
| 84 | +9. Sign the image with an external certificate bundle (`$certBundlePath`) including the intermediate certificates and a root certificate in PEM format. You may fetch the certificate bundle from your CA official website. |
| 85 | + ```sh |
| 86 | + notation key add --plugin azure-kv --id $keyID akv-key --default |
| 87 | + notation sign $server/hello-world:v1 --plugin-config=ca_certs=$certBundlePath |
| 88 | + ``` |
| 89 | +
|
| 90 | + The following example output shows the artifact is successfully signed. |
| 91 | + ``` |
| 92 | + Warning: Always sign the artifact using digest(@sha256:...) rather than a tag(:v1) because tags are mutable and a tag reference can point to a different artifact than the one signed. |
| 93 | + Successfully signed notation.azurecr.io/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4 |
| 94 | + ``` |
| 95 | +10. Signature verification with Notation needs the root certificate of your CA in the trust store and a `trustpolicy.json` file in Notation configuration directory: |
| 96 | + ```sh |
| 97 | + # add root certificate ($rootCertPath) to notation trust store |
| 98 | + notation cert add --type ca --store trusted $rootCertPath |
| 99 | + |
| 100 | + # add notation trust policy |
| 101 | + notationConfigDir="${HOME}/.config/notation" # for Linux and WSL |
| 102 | + # notationConfigDir="${HOME}/Library/Application Support/notation" # for macOS |
| 103 | +
|
| 104 | + mkdir -p $notationConfigDir |
| 105 | + cat <<EOF > $notationConfigDir/trustpolicy.json |
| 106 | + { |
| 107 | + "version": "1.0", |
| 108 | + "trustPolicies": [ |
| 109 | + { |
| 110 | + "name": "trust-policy-example", |
| 111 | + "registryScopes": [ "*" ], |
| 112 | + "signatureVerification": { |
| 113 | + "level" : "strict" |
| 114 | + }, |
| 115 | + "trustStores": [ "ca:trusted" ], |
| 116 | + "trustedIdentities": [ |
| 117 | + "*" |
| 118 | + ] |
| 119 | + } |
| 120 | + ] |
| 121 | + } |
| 122 | + EOF |
| 123 | + chmod 600 $notationConfigDir/trustpolicy.json |
| 124 | + ``` |
| 125 | +11. Verify the signature associated with the image: |
| 126 | + ``` |
| 127 | + notation verify $server/hello-world:v1 |
| 128 | + ``` |
| 129 | + The following output shows the artifact is successfully verified. |
| 130 | + ``` |
| 131 | + Warning: Always verify the artifact using digest(@sha256:...) rather than a tag(:v1) because resolved digest may not point to the same signed artifact, as tags are mutable. |
| 132 | + Successfully verified signature for notation.azurecr.io/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4 |
| 133 | + ``` |
0 commit comments