Merge pull request #102648 from yizha1/yizha1-sign

update to latest notation cli

Author: jborsecnik

articles/container-registry/container-registry-tutorial-sign-build-push.md

@@ -5,7 +5,7 @@ author: dtzar
 ms.author: davete
 ms.service: container-registry
 ms.topic: how-to
-ms.date: 10/11/2022
+ms.date: 12/12/2022
 ---
 
 # Build, sign, and verify container images using Notary and Azure Key Vault (Preview)
@@ -24,20 +24,17 @@ In this tutorial:
 
 ## Prerequisites
 
-> * Install, create and sign in to [ORAS artifact enabled registry](./container-registry-oras-artifacts.md#create-oras-artifact-enabled-registry)
+> * Install, create and sign in to OCI artifact enabled registry ACR
 > * 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/)
 
 ## Install the notation CLI and AKV plugin
 
-> [!NOTE]
-> The tutorial uses early released versions of notation and notation plugins.  
-
-1. Install notation 0.11.0-alpha.4 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/v0.11.0-alpha.4).
+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).
 
     ```bash
     # Download, extract and install
-    curl -Lo notation.tar.gz https://github.com/notaryproject/notation/releases/download/v0.11.0-alpha.4/notation_0.11.0-alpha.4_linux_amd64.tar.gz
+    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
     tar xvzf notation.tar.gz
 
     # Copy the notation cli to the desired bin directory in your PATH
@@ -48,15 +45,15 @@ In this tutorial:
 
     > [!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/notation/blob/main/specs/notation-config.md) for more information.
+    > 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.
 
     ```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.4.0-alpha.4/notation-azure-kv_0.4.0-alpha.4_Linux_amd64.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
     
     # Extract to the plugin directory
     tar xvzf notation-azure-kv.tar.gz -C ~/.config/notation/plugins/azure-kv notation-azure-kv
@@ -80,7 +77,7 @@ In this tutorial:
     AKV_NAME=<your-unique-keyvault-name>
     # New desired key name used to sign and verify
     KEY_NAME=wabbit-networks-io
-    KEY_SUBJECT_NAME=wabbit-networks.io
+    CERT_SUBJECT="CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US"
     CERT_PATH=./${KEY_NAME}.pem
     ```
 
@@ -101,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/main/specs/signature-specification.md#certificate-requirements)
+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)
 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.
+    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.
 
     ```bash
     cat <<EOF > ./my_policy.json
@@ -121,44 +118,60 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
         "ekus": [
             "1.3.6.1.5.5.7.3.3"
         ],
-        "subject": "CN=${KEY_SUBJECT_NAME}",
+        "keyUsage": [
+            "digitalSignature"
+        ],
+        "subject": "$CERT_SUBJECT",
         "validityInMonths": 12
         }
     }
     EOF
     ```
 
-1. Create the certificate.
+2. Create the certificate.
 
     ```azure-cli
     az keyvault certificate create -n $KEY_NAME --vault-name $AKV_NAME -p @my_policy.json
     ```
 
-1. Get the Key ID for the certificate.
+3. Get the Key ID for the certificate.
 
     ```bash
     KEY_ID=$(az keyvault certificate show -n $KEY_NAME --vault-name $AKV_NAME --query 'kid' -o tsv)
     ```
+    
 4. Download public certificate.
 
     ```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
     ```
 
-5. Add the Key ID to the keys and certs.
+5. Add a signing key referencing the key id.
 
     ```bash
-    notation key add --name $KEY_NAME --plugin azure-kv --id $KEY_ID
-    notation cert add --name $KEY_NAME $CERT_PATH
+    notation key add $KEY_NAME --plugin azure-kv --id $KEY_ID
     ```
 
-6. List the keys and certs to confirm.
+6. List the keys to confirm.
 
-    ```bash
-    notation key ls
-    notation cert ls
-    ```
+   ```bash
+   notation key ls
+   ```
+    
+7. Add the downloaded public certificate to named trust store for signature verification.
+
+   ```bash
+   STORE_TYPE="ca"
+   STORE_NAME="wabbit-networks.io"
+   notation cert add --type $STORE_TYPE --store $STORE_NAME $CERT_PATH
+   ```
+    
+8. List the certificate to confirm
+
+   ```bash
+   notation cert ls
+   ```
 
 ## Build and sign a container image
 
@@ -173,26 +186,24 @@ Otherwise create an x509 self-signed certificate storing it in AKV for remote si
     ```azure-cli
     export USER_NAME="00000000-0000-0000-0000-000000000000"
     export PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
-    export NOTATION_PASSWORD=$PASSWORD
+    notation login -u $USER_NAME -p $PASSWORD $REGISTRY
     ```
 
-3. Choose [COSE](https://datatracker.ietf.org/doc/html/rfc8152) or JWS signature envelope to sign the container image.
-
-   - Sign the container image with the COSE signature envelope:
+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 --envelope-type cose --key $KEY_NAME $IMAGE
-    ```
-    
-   - Sign the container image with the default JWS signature envelope:
-   
-    ```bash
-    notation sign --key $KEY_NAME $IMAGE
+    notation sign --signature-format cose --key $KEY_NAME $IMAGE
     ```
     
-## View the graph of artifacts with the ORAS CLI
+4. View the graph of signed images and associated signatures.
+
+   ```bash
+   notation ls $IMAGE
+   ```
 
-ACR support for ORAS artifacts enables a linked graph of supply chain artifacts that can be viewed through the ORAS CLI or the Azure CLI.
+## [Option] View the graph of artifacts with the ORAS CLI
+
+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.
 
@@ -201,15 +212,15 @@ ACR support for ORAS artifacts enables a linked graph of supply chain artifacts
     oras discover -o tree $IMAGE
     ```
 
-## View the graph of artifacts with the Azure CLI
+## [Option] View the graph of artifacts with the Azure CLI
 
 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.
+2. Generates a result, showing the `digest` representing the notary v2 signature.
 
     ```json
     {
@@ -230,29 +241,39 @@ ACR support for ORAS artifacts enables a linked graph of supply chain artifacts
 
 ## Verify the container image
 
-1. 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
-sha256:effba96d9b7092a0de4fa6710f6e73bf8c838e4fbd536e95de94915777b18613
-```
-The sha256 result is a successful verification of the image using the trusted certificate.
+1. Configure trust policy before verification.
 
-2. We can add a different local signing certificate to show how multiple certificates and verification failures work.
-
-```bash
-notation cert generate-test -n localcert --trust true
-notation verify $IMAGE
-sha256:effba96d9b7092a0de4fa6710f6e73bf8c838e4fbd536e95de94915777b18613
-```
+   The trust policy is a JSON document named `trustpolicy.jsoin`, which is stored under notation configuration directory. Users who verify signed artifact from a registry use the trust policy to specify trusted identities which sign the artifacts, and 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 under repository `$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`.
 
-We can see that verification still passes because `notation verify` will implicitly pass with _any_ certificate in its trust store.  To get a verification failure, we'll remove the certificate utilized to sign the image.
+    ```bash
+    cat <<EOF > $HOME/.config/notation/trustpolicy.json
+    {
+        "version": "1.0",
+        "trustPolicies": [
+            {
+                "name": "wabbit-networks-images",
+                "registryScopes": [ "$REGISTRY/$REPO" ],
+                "signatureVerification": {
+                    "level" : "strict" 
+                },
+                "trustStores": [ "$STORE_TYPE:$STORE_NAME" ],
+                "trustedIdentities": [
+                    "x509.subject: $CERT_SUBJECT"
+                ]
+            }
+        ]
+    }
+    EOF
+    ```
+    
+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.
 
-```azure-cli
-notation cert rm $KEY_NAME
-notation verify $IMAGE
-2022/06/10 11:24:30 verification failure: x509: certificate signed by unknown authority
-```
+    ```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.
 
 ## Next steps