Merge pull request #221330 from MicrosoftDocs/repo_sync_working_branch

Confirm merge from repo_sync_working_branch to main to sync with https://github.com/MicrosoftDocs/azure-docs (branch main)

Author: huypub

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
 

articles/cosmos-db/attachments.md

@@ -18,29 +18,29 @@ Azure Cosmos DB attachments are special items that contain references to an asso
 
 Azure Cosmos DB supports two types of attachments:
 
-* **Unmanaged Attachments** are a wrapper around an URI reference to a blob that is stored in an external service (for example, Azure Storage, OneDrive, etc.). This approach is similar to storing a URI property in a standard Azure Cosmos DB item.
+* **Unmanaged Attachments** are a wrapper around a URI reference to a blob that is stored in an external service (for example, Azure Storage, OneDrive, etc.). This approach is similar to storing a URI property in a standard Azure Cosmos DB item.
 * **Managed Attachments** are blobs managed and stored internally by Azure Cosmos DB and exposed via a system-generated mediaLink.
 
 
 > [!NOTE]
-> Attachment is a legacy feature. Their support is scoped to offer continued functionality if you are already using this feature.
+> Attachments are a legacy feature. Their support is scoped to offer continued functionality if you are already using this feature.
 > 
-> Instead of using attachments, we recommend you to use Azure Blob Storage as a purpose-built blob storage service to store blob data . You can continue to store metadata related to blobs, along with reference URI links, in Azure Cosmos DB as item properties. Storing this data in Azure Cosmos DB provides the ability to query metadata and links to blobs stored in Azure Blob Storage.
+> Instead of using attachments, we recommend you to use Azure Blob Storage as a purpose-built blob storage service to store blob data. You can continue to store metadata related to blobs, along with reference URI links, in Azure Cosmos DB as item properties. Storing this data in Azure Cosmos DB provides the ability to query metadata and links to blobs stored in Azure Blob Storage.
 > 
 > Microsoft is committed to provide a minimum 36-month notice prior to fully deprecating attachments – which will be announced at a further date.
 
 ## Known limitations
 
 Azure Cosmos DB’s managed attachments are distinct from its support for standard items – for which it offers unlimited scalability, global distribution, and integration with other Azure services.
 
-- Attachments aren't supported in all versions of the Azure Cosmos DB’s SDKs.
+- Attachments aren't supported in all versions of the Azure Cosmos DB SDKs.
 - Managed attachments are limited to 2 GB of storage per database account.
 - Managed attachments aren't compatible with Azure Cosmos DB’s global distribution, and they aren't replicated across regions.
 
 > [!NOTE]
-> Azure Cosmso DB for MongoDB version 3.2 utilizes managed attachments for GridFS and are subject to the same limitations.
+> Azure Cosmos DB for MongoDB version 3.2 utilizes managed attachments for GridFS and these are subject to the same limitations.
 >
-> We recommend developers using the MongoDB GridFS feature set to upgrade to Azure Cosmso DB for MongoDB version 3.6 or higher, which is decoupled from attachments and provides a better experience. Alternatively, developers using the MongoDB GridFS feature set should also consider using Azure Blob Storage - which is purpose-built for storing blob content and offers expanded functionality at lower cost compared to GridFS.
+> We recommend developers using the MongoDB GridFS feature set to upgrade to Azure Cosmos DB for MongoDB version 3.6 or higher, which is decoupled from attachments and provides a better experience. Alternatively, developers using the MongoDB GridFS feature set should also consider using Azure Blob Storage - which is purpose-built for storing blob content and offers expanded functionality at lower cost compared to GridFS.
 
 ## Migrating Attachments to Azure Blob Storage
 
@@ -51,7 +51,7 @@ We recommend migrating Azure Cosmos DB attachments to Azure Blob Storage by foll
 3. If applicable, add URI references to the blobs contained in Azure Blob Storage as string properties within your Azure Cosmos DB dataset.
 4. Refactor your application code to read and write blobs from the new Azure Blob Storage container.
 
-The following dotnet code sample shows how to copy attachments from Azure Cosmos DB to Azure Blob storage as part of a migration flow by using Azure Cosmos DB's .NET SDK v2 and Azure Blob Storage .NET SDK v12. Make sure to replace the `<placeholder values>` for the source Azure Cosmos DB account and target Azure Blob storage container.
+The following code sample shows how to copy attachments from Azure Cosmos DB to Azure Blob storage as part of a migration flow by using Azure Cosmos DB's .NET SDK v2 and Azure Blob Storage .NET SDK v12. Make sure to replace the `<placeholder values>` for the source Azure Cosmos DB account and target Azure Blob storage container.
 
 ```csharp
 
@@ -163,6 +163,6 @@ namespace attachments
 ## Next steps
 
 - Get started with [Azure Blob storage](../storage/blobs/storage-quickstart-blobs-dotnet.md)
-- Get references for using attachments via [Azure Cosmos DB’s .NET SDK v2](/dotnet/api/microsoft.azure.documents.attachment)
-- Get references for using attachments via [Azure Cosmos DB’s Java SDK v2](/java/api/com.microsoft.azure.documentdb.attachment)
-- Get references for using attachments via [Azure Cosmos DB’s REST API](/rest/api/cosmos-db/attachments)
+- Get references for using attachments via [Azure Cosmos DB's .NET SDK v2](/dotnet/api/microsoft.azure.documents.attachment)
+- Get references for using attachments via [Azure Cosmos DB's Java SDK v2](/java/api/com.microsoft.azure.documentdb.attachment)
+- Get references for using attachments via [Azure Cosmos DB's REST API](/rest/api/cosmos-db/attachments)