Merge pull request #248675 from yizha1/cssc/update_experience

ttorble · web-flow · commit f348debfe358 · 2023-09-18T10:55:31.000+01:00
doc: update signing using a self-signed certificate
diff --git a/articles/container-registry/container-registry-tutorial-sign-build-push.md b/articles/container-registry/container-registry-tutorial-sign-build-push.md
@@ -1,62 +1,64 @@
 ---
-title: Build, Sign and Verify a container image using notation and certificate in Azure Key Vault
-description: In this tutorial you'll learn to create a signing certificate, build a container image, remote sign image with notation and Azure Key Vault, and then verify the container image using the Azure Container Registry.
-author: feynmanzhou
-ms.author: davete
+title: Sign container images with Notation and Azure Key Vault using a self-signed certificate (Preview)
+description: In this tutorial you'll learn to create a self-signed certificate in Azure Key Vault (AKV), build and sign a container image stored in Azure Container Registry (ACR) with notation and AKV, and then verify the container image with notation.
+author: yizha1
+ms.author: yizha1
 ms.service: container-registry
 ms.custom: devx-track-azurecli
 ms.topic: how-to
 ms.date: 4/23/2023
 ---
 
-# Build, sign, and verify container images using Notary and Azure Key Vault (Preview)
+# Sign container images with Notation and Azure Key Vault using a self-signed certificate (Preview)
 
-The Azure Key Vault (AKV) is used to store a signing key that can be utilized by [notation](http://notaryproject.dev/) with the notation AKV plugin (azure-kv) to sign and verify container images and other artifacts. The Azure Container Registry (ACR) allows you to attach these signatures using the **az** or **oras** CLI commands.
-
-The signed image enables users to assure deployments are built from a trusted entity and verify artifact hasn't been tampered with since their creation. The signed artifact ensures integrity and authenticity before the user pulls an artifact into any environment and avoid attacks.
+Signing container images is a process that ensures their authenticity and integrity. This is achieved by adding a digital signature to the container image, which can be validated during deployment. The signature helps to verify that the image is from a trusted publisher and has not been modified. [Notation](https://github.com/notaryproject/notation) is an open source supply chain tool developed by the [Notary Project](https://notaryproject.dev/), which supports signing and verifying container images and other artifacts. The Azure Key Vault (AKV) is used to store certificates with signing keys that can be used by Notation with the Notation AKV plugin (azure-kv) to sign and verify container images and other artifacts. The Azure Container Registry (ACR) allows you to attach signatures to container images and other artifacts as well as view those signatures.
 
+> [!IMPORTANT]
+> This feature is currently in preview. Previews are made available to you on the condition that you agree to the [supplemental terms of use][terms-of-use]. Some aspects of this feature may change prior to general availability (GA).
 
 In this tutorial:
 
 > [!div class="checklist"]
-> * Store a signing certificate in Azure Key Vault
-> * Sign a container image with notation
-> * Verify a container image signature with notation
+> * Install Notation CLI and AKV plugin
+> * Create a self-signed certificate in AKV
+> * Build and push a container image with [ACR Tasks](container-registry-tasks-overview.md)
+> * Sign a container image with Notation CLI and AKV plugin
+> * Validate a container image against the signature with Notation CLI
 
 ## Prerequisites
 
-> * Create and sign in ACR with OCI artifact enabled
-> * Create or use an [Azure Key Vault](../key-vault/general/quick-create-cli.md)
->*  This tutorial can be run in the [Azure Cloud Shell](https://portal.azure.com/#cloudshell/)
+* Create or use an [Azure Container Registry](../container-registry/container-registry-get-started-azure-cli.md) for storing container images and signatures
+* Create or use an [Azure Key Vault](../key-vault/general/quick-create-cli.md) for managing certificates
+* Install and configure the latest [Azure CLI](/cli/azure/install-azure-cli), or Run commands in the [Azure Cloud Shell](https://portal.azure.com/#cloudshell/)
 
-## Install the notation CLI and AKV plugin
+## Install Notation CLI and AKV plugin
 
-1. Install notation v1.0.0-rc.7 on a Linux environment. You can also download the package for other environments by following the [Notation installation guide](https://notaryproject.dev/docs/installation/cli/).
+1. Install Notation v1.0.0 on a Linux amd64 environment. You can also download the package for other environments by following the [Notation installation guide](https://notaryproject.dev/docs/user-guides/installation/).
 
     ```bash
     # Download, extract and install
-    curl -Lo notation.tar.gz https://github.com/notaryproject/notation/releases/download/v1.0.0-rc.7/notation_1.0.0-rc.7_linux_amd64.tar.gz
+    curl -Lo notation.tar.gz https://github.com/notaryproject/notation/releases/download/v1.0.0/notation_1.0.0_linux_amd64.tar.gz
     tar xvzf notation.tar.gz
             
-    # Copy the notation cli to the desired bin directory in your PATH
+    # Copy the Notation binary to the desired bin directory in your $PATH, for example
     cp ./notation /usr/local/bin
     ```
 
-2. Install the notation Azure Key Vault plugin on a Linux environment for remote signing and verification. You can also download the package for other environments by following the [Notation AKV plugin installation guide](https://github.com/Azure/notation-azure-kv#installation-the-akv-plugin).
+2. Install the Notation Azure Key Vault plugin on a Linux amd64 environment. You can also download the package for other environments by following the [Notation AKV plugin installation guide](https://github.com/Azure/notation-azure-kv#installation-the-akv-plugin).
 
     > [!NOTE]
-    > The plugin directory varies depending upon the operating system being used. The directory path below assumes Ubuntu. Please read the [Notation directory structure for system configuration](https://notaryproject.dev/docs/concepts/directory-structure/) for more information.
+    > The plugin directory varies depending upon the operating system being used. The directory path below assumes Ubuntu. Please read the [Notation directory structure for system configuration](https://notaryproject.dev/docs/user-guides/how-to/directory-structure/) for more information.
     
     ```bash
     # Create a directory for the plugin
     mkdir -p ~/.config/notation/plugins/azure-kv
     
     # Download the plugin
     curl -Lo notation-azure-kv.tar.gz \
-        https://github.com/Azure/notation-azure-kv/releases/download/v1.0.0-rc.2/notation-azure-kv_1.0.0-rc.2_linux_amd64.tar.gz 
+        https://github.com/Azure/notation-azure-kv/releases/download/v1.0.1/notation-azure-kv_1.0.1_linux_amd64.tar.gz 
     
     # Extract to the plugin directory
-    tar xvzf notation-azure-kv.tar.gz -C ~/.config/notation/plugins/azure-kv notation-azure-kv
+    tar xvzf notation-azure-kv.tar.gz -C ~/.config/notation/plugins/azure-kv
     ```
 
 3. List the available plugins.
@@ -73,12 +75,12 @@ In this tutorial:
 1. Configure AKV resource names.
 
     ```bash
-    # Name of the existing Azure Key Vault used to store the signing keys
-    AKV_NAME=<your-unique-keyvault-name>
-    # New desired key name used to sign and verify
-    KEY_NAME=wabbit-networks-io
-    CERT_SUBJECT="CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US"
-    CERT_PATH=./${KEY_NAME}.pem
+    # Name of the existing AKV used to store the signing keys
+    AKV_NAME=myakv
+    # Name of the certificate created in AKV
+    CERT_NAME=wabbit-networks-io
+    CERT_SUBJECT="CN=wabbit-networks.io,O=Notation,L=Seattle,ST=WA,C=US"
+    CERT_PATH=./${CERT_NAME}.pem
     ```
 
 2. Configure ACR and image resource names.
@@ -96,16 +98,47 @@ In this tutorial:
     IMAGE_SOURCE=https://github.com/wabbit-networks/net-monitor.git#main
     ```
 
-## Store the signing certificate in AKV
+## Sign in with Azure CLI
+
+```bash
+az login
+```
+
+To learn more about Azure CLI and how to sign in with it, see [Sign in with Azure CLI](/cli/azure/authenticate-azure-cli).
+
+## Assign access policy in AKV (Azure CLI)
+
+A user principal with the correct access policy permissions is needed to create a self-signed certificate and sign artifacts. This principal can be a user principal, service principal, or managed identity. At a minimum, this principal needs the following permissions:
+
+- `Create` permissions for certificates
+- `Get` permissions for certificates
+- `Sign` permissions for keys
+
+In this tutorial, the access policy is assigned to a signed-in Azure user. To learn more about assigning policy to a principal, see [Assign Access Policy](/azure/key-vault/general/assign-access-policy).
 
-If you have an existing certificate, upload it to AKV. For more information on how to use your own signing key, see the [signing certificate requirements.](https://github.com/Azure/notation-azure-kv/blob/release-0.6/docs/ca-signed-workflow.md)
-Otherwise create an x509 self-signed certificate storing it in AKV for remote signing using the steps below.
+### Set the subscription that contains the AKV resource
 
-### Create a self-signed certificate (Azure CLI)
+```bash
+az account set --subscription <your_subscription_id>
+```
+
+### Set the access policy in AKV
+
+```bash
+USER_ID=$(az ad signed-in-user show --query id -o tsv)
+az keyvault set-policy -n $AKV_NAME --certificate-permissions create get --key-permissions sign --object-id $USER_ID
+```
+
+> [!IMPORTANT]
+> This example shows the minimum permissions needed for creating a certificate and signing a container image. Depending on your requirements, you may need to grant additional permissions.
+
+## Create a self-signed certificate in AKV (Azure CLI)
+
+The following steps show how to create a self-signed certificate for testing purpose.
 
 1. Create a certificate policy file.
 
-    Once the certificate policy file is executed as below, it creates a valid signing certificate compatible with **notation** in AKV. The EKU listed is for code-signing, but isn't required for notation to sign artifacts. The subject is used later as trust identity that user trust during verification.
+    Once the certificate policy file is executed as below, it creates a valid certificate compatible with [Notary Project certificate requirement](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/signature-specification.md#certificate-requirements) in AKV. The value for `ekus` is for code-signing, but isn't required for notation to sign artifacts. The subject is used later as trust identity that user trust during verification.
 
     ```bash
     cat <<EOF > ./my_policy.json
@@ -114,6 +147,12 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
         "certificateTransparency": null,
         "name": "Self"
         },
+        "keyProperties": {
+          "exportable": false,
+          "keySize": 2048,
+          "keyType": "RSA",
+          "reuseKey": true
+        },
         "x509CertificateProperties": {
         "ekus": [
             "1.3.6.1.5.5.7.3.3"
@@ -130,87 +169,79 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
 
 2. Create the certificate.
 
-    ```azure-cli
-    az keyvault certificate create -n $KEY_NAME --vault-name $AKV_NAME -p @my_policy.json
+    ```bash
+    az keyvault certificate create -n $CERT_NAME --vault-name $AKV_NAME -p @my_policy.json
     ```
 
-3. Get the Key ID for the certificate.
+## Sign a container image with Notation CLI and AKV plugin
+
+1. Authenticate to your ACR by using your individual Azure identity.
 
     ```bash
-    KEY_ID=$(az keyvault certificate show -n $KEY_NAME --vault-name $AKV_NAME --query 'kid' -o tsv)
+    az acr login --name $ACR_NAME
     ```
-    
-4. Download public certificate.
+
+> [!IMPORTANT]
+> If you have Docker installed on your system and used `az acr login` or `docker login` to authenticate to your ACR, your credentials are already stored and available to notation. In this case, you don’t need to run `notation login` again to authenticate to your ACR. To learn more about authentication options for notation, see [Authenticate with OCI-compliant registries](https://notaryproject.dev/docs/user-guides/how-to/registry-authentication/).
+
+2. Build and push a new image with ACR Tasks. Always use the digest value to identify the image for signing since tags are mutable and can be overwritten.
 
     ```bash
-    CERT_ID=$(az keyvault certificate show -n $KEY_NAME --vault-name $AKV_NAME --query 'id' -o tsv)
-    az keyvault certificate download --file $CERT_PATH --id $CERT_ID --encoding PEM
+    DIGEST=$(az acr build -r $ACR_NAME -t $REGISTRY/${REPO}:$TAG $IMAGE_SOURCE --no-logs --query "outputImages[0].digest" -o tsv)
+    IMAGE=$REGISTRY/${REPO}@$DIGEST
     ```
 
-5. Add a signing key referencing the key ID.
+    In this tutorial, if the image has already been built and is stored in the registry, the tag serves as an identifier for that image for convenience.
 
     ```bash
-    notation key add $KEY_NAME --plugin azure-kv --id $KEY_ID
+    IMAGE=$REGISTRY/${REPO}@$TAG
     ```
 
-6. List the keys to confirm.
+3. Get the Key ID of the signing key. A certificate in AKV can have multiple versions, the following command gets the Key ID of the latest version.
 
-   ```bash
-   notation key ls
-   ```
+    ```bash
+    KEY_ID=$(az keyvault certificate show -n $CERT_NAME --vault-name $AKV_NAME --query 'kid' -o tsv)
+    ```
 
-7. Add the downloaded public certificate to named trust store for signature verification.
+4. Sign the container image with the [COSE](https://datatracker.ietf.org/doc/html/rfc9052) signature format using the signing key ID. To sign with a self-signed certificate, you need to set the plugin configuration value `self_signed=true`.
 
-   ```bash
-   STORE_TYPE="ca"
-   STORE_NAME="wabbit-networks.io"
-   notation cert add --type $STORE_TYPE --store $STORE_NAME $CERT_PATH
-   ```
+    ```bash
+    notation sign --signature-format cose --id $KEY_ID --plugin azure-kv --plugin-config self_signed=true $IMAGE
+    ```
     
-8. List the certificate to confirm.
+5. View the graph of signed images and associated signatures.
 
    ```bash
-   notation cert ls
+   notation ls $IMAGE
    ```
 
-## Build and sign a container image
-
-1. Build and push a new image with ACR Tasks.
+## Verify a container image with Notation CLI
 
-    ```azure-cli
-    az acr build -r $ACR_NAME -t $IMAGE $IMAGE_SOURCE
-    ```
+To verify the container image, add the root certificate that signs the leaf certificate to the trust store and create trust policies for verification. For the self-signed certificate used in this tutorial, the root certificate is the self-signed certificate itself.
 
-2. Authenticate with your individual Azure AD identity to use an ACR token. 
+1. Download public certificate.
 
-    ```azure-cli
-    export USER_NAME="00000000-0000-0000-0000-000000000000"
-    export PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
-    notation login -u $USER_NAME -p $PASSWORD $REGISTRY
+    ```bash
+    az keyvault certificate download --name $CERT_NAME --vault-name $AKV_NAME --file $CERT_PATH
     ```
 
-> [!NOTE]
-> Currently, `notation` relies on [Docker Credential Store](https://docs.docker.com/engine/reference/commandline/login/#credentials-store) for authentication. Notation requires additional configuration on Linux. If `notation login` is failing, you can configure the Docker Credential Store or Notation environment variables by following the guide [Authenticate with OCI-compliant registries](https://notaryproject.dev/docs/how-to/registry-authentication/).
+2. Add the downloaded public certificate to named trust store for signature verification.
 
-3. Sign the container image with the [COSE](https://datatracker.ietf.org/doc/html/rfc8152) signature format using the signing key added in previous step.
- 
-    ```bash
-    notation sign --signature-format cose --key $KEY_NAME $IMAGE
-    ```
+   ```bash
+   STORE_TYPE="ca"
+   STORE_NAME="wabbit-networks.io"
+   notation cert add --type $STORE_TYPE --store $STORE_NAME $CERT_PATH
+   ```
     
-4. View the graph of signed images and associated signatures.
+3. List the certificate to confirm.
 
    ```bash
-   notation ls $IMAGE
+   notation cert ls
    ```
+ 
+4. Configure trust policy before verification.
 
-## Verify the container image
-
-1. Configure trust policy before verification.
-
-   The trust policy is a JSON document named `trustpolicy.json`, which is stored under the notation configuration directory. Users who verify signed artifacts from a registry use the trust policy to specify trusted identities that sign the artifacts, and the level of signature verification to use.
-
-   Use the following command to configure trust policy. Upon successful execution of the command, one trust policy named `wabbit-networks-images` is created. This trust policy applies to all the artifacts stored in repositories defined in `$REGISTRY/$REPO`. The trust identity that user trusts has the x509 subject `$CERT_SUBJECT` from previous step, and stored under trust store named `$STORE_NAME` of type `$STORE_TYPE`. See [Trust store and trust policy specification](https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md) for details.
+   Trust policies allow users to specify fine-tuned verification policies. The following example configures a trust policy named `wabbit-networks-images`, which applies to all artifacts in `$REGISTRY/$REPO` and uses the named trust store `$STORE_NAME` of type `$STORE_TYPE`. It also assumes that the user trusts a specific identity with the X.509 subject `$CERT_SUBJECT`. For more details, see [Trust store and trust policy specification](https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/trust-store-trust-policy.md).
 
     ```bash
     cat <<EOF > ./trustpolicy.json
@@ -233,20 +264,23 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
     EOF
     ```
 
-3. Use `notation policy` to import the trust policy configuration from a JSON file that we created previously. 
+5. Use `notation policy` to import the trust policy configuration from a JSON file that we created previously. 
 
     ```bash
     notation policy import ./trustpolicy.json
     notation policy show
     ```
     
-4. The notation command can also help to ensure the container image hasn't been tampered with since build time by comparing the `sha` with what is in the registry.
+6. Use `notation verify` to verify the container image hasn't been altered since build time.
 
     ```bash
     notation verify $IMAGE
     ```
+
    Upon successful verification of the image using the trust policy, the sha256 digest of the verified image is returned in a successful output message.
 
 ## Next steps
 
 See [Ratify on Azure: Allow only signed images to be deployed on AKS with Notation and Ratify](https://github.com/deislabs/ratify/blob/main/docs/quickstarts/ratify-on-azure.md).
+
+[terms-of-use]: https://azure.microsoft.com/support/legal/preview-supplemental-terms/
