Merge pull request #235470 from FeynmanZhou/main

Court72 · web-flow · commit cf87b2f7ef02 · 2023-04-27T12:04:23.000-06:00
Update container-registry-tutorial-sign-build-push.md
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,19 +1,19 @@
 ---
 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: dtzar
+author: feynmanzhou
 ms.author: davete
 ms.service: container-registry
 ms.custom: devx-track-azurecli
 ms.topic: how-to
-ms.date: 12/12/2022
+ms.date: 4/23/2023
 ---
 
 # Build, sign, and verify container images using Notary and Azure Key Vault (Preview)
 
-The Azure Key Vault (AKV) is used to store a signing key that can be utilized 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 these signatures using the **az** or **oras** CLI commands.
+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 containers enable 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.
+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.
 
 
 In this tutorial:
@@ -31,11 +31,11 @@ In this tutorial:
 
 ## Install the notation CLI and AKV plugin
 
-1. Install notation v1.0.0-rc.1 with plugin support on a Linux environment. You can also download the package for other environments from the [release page](https://github.com/notaryproject/notation/releases/tag/v1.0.0-rc.1).
+1. Install notation v1.0.0-rc.4 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/).
 
     ```bash
     # Download, extract and install
-    curl -Lo notation.tar.gz https://github.com/notaryproject/notation/releases/download/v1.0.0-rc.1/notation_1.0.0-rc.1_linux_amd64.tar.gz
+    curl -Lo notation.tar.gz https://github.com/notaryproject/notation/releases/download/v1.0.0-rc.4/notation_1.0.0-rc.4_linux_amd64.tar.gz
     tar xvzf notation.tar.gz
             
     # Copy the notation cli to the desired bin directory in your PATH
@@ -45,22 +45,21 @@ In this tutorial:
 2. Install the notation Azure Key Vault plugin for remote signing and verification.
 
     > [!NOTE]
-    > The plugin directory varies depending upon the operating system being used.  The directory path below assumes Ubuntu.
-    > Please read the [notation config article](https://github.com/notaryproject/notaryproject.dev/blob/main/content/en/docs/how-to/directory-structure.md) 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/concepts/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/v0.5.0-rc.1/notation-azure-kv_0.5.0-rc.1_Linux_amd64.tar.gz
+        https://github.com/Azure/notation-azure-kv/releases/download/v0.6.0/notation-azure-kv_0.6.0_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
     ```
 
-3. List the available plugins and verify that the plugin is available.
+3. List the available plugins.
 
     ```bash
     notation plugin ls
@@ -99,14 +98,14 @@ In this tutorial:
 
 ## Store the signing certificate in AKV
 
-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/notaryproject/notaryproject/blob/v1.0.0-rc.1/specs/signature-specification.md)
+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.
 
 ### Create a self-signed certificate (Azure CLI)
 
 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 tursts during verification.
+    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.
 
     ```bash
     cat <<EOF > ./my_policy.json
@@ -148,7 +147,7 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
     az keyvault certificate download --file $CERT_PATH --id $CERT_ID --encoding PEM
     ```
 
-5. Add a signing key referencing the key id.
+5. Add a signing key referencing the key ID.
 
     ```bash
     notation key add $KEY_NAME --plugin azure-kv --id $KEY_ID
@@ -159,7 +158,7 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
    ```bash
    notation key ls
    ```
-    
+
 7. Add the downloaded public certificate to named trust store for signature verification.
 
    ```bash
@@ -168,7 +167,7 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
    notation cert add --type $STORE_TYPE --store $STORE_NAME $CERT_PATH
    ```
     
-8. List the certificate to confirm
+8. List the certificate to confirm.
 
    ```bash
    notation cert ls
@@ -182,14 +181,17 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
     az acr build -r $ACR_NAME -t $IMAGE $IMAGE_SOURCE
     ```
 
-2. Authenticate with your individual Azure AD identity to use an ACR token.
+2. Authenticate with your individual Azure AD identity to use an ACR token. 
 
     ```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
     ```
 
+> [!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/).
+
 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
@@ -202,54 +204,16 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
    notation ls $IMAGE
    ```
 
-## View the graph of artifacts with the ORAS CLI (optional)
-
-ACR support for OCI artifacts enables a linked graph of supply chain artifacts that can be viewed through the ORAS CLI or the Azure CLI.
-
-1. Signed images can be view with the ORAS CLI.
-
-    ```bash
-    oras login -u $USER_NAME -p $PASSWORD $REGISTRY
-    oras discover -o tree $IMAGE
-    ```
-
-## View the graph of artifacts with the Azure CLI (optional)
-
-1. List the manifest details for the container image.
-
-    ```azure-cli
-    az acr manifest show-metadata $IMAGE -o jsonc
-    ```
-
-2. Generates a result, showing the `digest` representing the notary v2 signature.
-
-    ```json
-    {
-      "changeableAttributes": {
-        "deleteEnabled": true,
-        "listEnabled": true,
-        "readEnabled": true,
-        "writeEnabled": true
-      },
-      "createdTime": "2022-05-13T23:15:54.3478293Z",
-      "digest": "sha256:effba96d9b7092a0de4fa6710f6e73bf8c838e4fbd536e95de94915777b18613",
-      "lastUpdateTime": "2022-05-13T23:15:54.3478293Z",
-      "name": "v1",
-      "quarantineState": "Passed",
-      "signed": false
-    }
-    ```
-
 ## 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 for this tutorial. 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://notaryproject.dev/docs/concepts/trust-store-trust-policy-specification/) for details.
+   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://notaryproject.dev/docs/concepts/trust-store-trust-policy-specification/) for details.
 
     ```bash
-    cat <<EOF > $HOME/.config/notation/trustpolicy.json
+    cat <<EOF > ./trustpolicy.json
     {
         "version": "1.0",
         "trustPolicies": [
@@ -268,14 +232,21 @@ ACR support for OCI artifacts enables a linked graph of supply chain artifacts t
     }
     EOF
     ```
+
+3. 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
+    ```
     
-2. 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.
+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.
 
     ```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 messages.
+   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 [Enforce policy to only deploy signed container images to Azure Kubernetes Service (AKS) utilizing **ratify** and **gatekeeper**.](https://github.com/Azure/notation-azure-kv/blob/main/docs/nv2-sign-verify-aks.md)
+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/examples/ratify-verify-azure-cmd.md).
