diff --git a/docs/ca-signed-workflow.md b/docs/ca-signed-workflow.md index df1ee80e..de9f8074 100644 --- a/docs/ca-signed-workflow.md +++ b/docs/ca-signed-workflow.md @@ -55,19 +55,37 @@ az keyvault certificate create -n $certName --vault-name $keyVault -p @leafCert.json # get the CSR - CSR=$(az keyvault certificate pending show --vault-name $keyVault --name $certName --query 'csr' -o tsv) - CSR_PATH=${certName}.csr - printf -- "-----BEGIN CERTIFICATE REQUEST-----\n%s\n-----END CERTIFICATE REQUEST-----\n" $CSR > ${CSR_PATH} + csr=$(az keyvault certificate pending show --vault-name $keyVault --name $certName --query 'csr' -o tsv) + csrPath=${certName}.csr + printf -- "-----BEGIN CERTIFICATE REQUEST-----\n%s\n-----END CERTIFICATE REQUEST-----\n" $csr > ${csrPath} ``` -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. -6. After you get the leaf certificate, you can merge the leaf certificate (`$leafCert`) to your Azure Key Vault: +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. Here is an example by using `openssl`: + Create a private key and certificate for a root CA with `openssl`: ```sh - az keyvault certificate pending merge --vault-name $keyVault --name $certName --file $leafCert + openssl req -x509 -sha256 -nodes -newkey rsa:2048 -keyout ca.key -out ca.crt -days 365 -subj "/CN=Test CA" -addext "keyUsage=critical,keyCertSign" + ``` + Create a configuration file. It will be used for `openssl` to sign the leaf certificate: + ```sh + cat < ./ext.cnf + [ v3_ca ] + keyUsage = critical,digitalSignature + extendedKeyUsage = codeSigning + EOF + ``` + Sign the certificate: + ```sh + signedCertPath=${certName}.crt + openssl x509 -CA ca.crt -CAkey ca.key -days 365 -req -in ${csrPath} -set_serial 02 -out ${signedCertPath} -extensions v3_ca -extfile ./ext.cnf + ``` + +6. After you get the leaf certificate, you can merge the signed leaf certificate (`$signedCertPath`) or certificate chain to your Azure Key Vault: + ```sh + az keyvault certificate pending merge --vault-name $keyVault --name $certName --file $signedCertPath # get the key identifier keyID=$(az keyvault certificate show -n $certName --vault-name $keyVault --query 'kid' -o tsv) ``` -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 `.azurecr.io`, but you must substitute your own login server value. +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 `.azurecr.io`, but you must substitute your own login server value. 8. Log in to container registry and push an image for signing: ```sh registryName="" @@ -81,14 +99,15 @@ docker tag hello-world:latest $server/hello-world:v1 docker push $server/hello-world:v1 ``` -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. +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 site. + > **Note** If you have generated the certificate with `openssl` according to the above steps, the certificate bundle is the root certificate `ca.crt`. ```sh notation key add --plugin azure-kv --id $keyID akv-key --default notation sign $server/hello-world:v1 --plugin-config=ca_certs=$certBundlePath ``` The following example output shows the artifact is successfully signed. - ``` + ```sh 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. Successfully signed notation.azurecr.io/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4 ``` @@ -123,11 +142,11 @@ chmod 600 $notationConfigDir/trustpolicy.json ``` 11. Verify the signature associated with the image: - ``` + ```sh notation verify $server/hello-world:v1 ``` The following output shows the artifact is successfully verified. - ``` + ```sh 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. Successfully verified signature for notation.azurecr.io/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4 ``` \ No newline at end of file