Merge branch 'master' into users/antoshni/encryptionGA

Directory.Build.props

@@ -5,7 +5,7 @@
 		<ClientPreviewVersion>3.26.0</ClientPreviewVersion>
 		<ClientPreviewSuffixVersion>preview</ClientPreviewSuffixVersion>
 		<DirectVersion>3.24.1</DirectVersion>
-		<EncryptionVersion>1.0.0-previewV19</EncryptionVersion>
+		<EncryptionVersion>1.0.0-previewV20</EncryptionVersion>
 		<CustomEncryptionVersion>1.0.0-preview02</CustomEncryptionVersion>
 		<HybridRowVersion>1.1.0-preview3</HybridRowVersion>
 		<LangVersion>9.0</LangVersion>

Microsoft.Azure.Cosmos.Encryption/changelog.md

@@ -3,6 +3,12 @@ Preview features are treated as a separate branch and will not be included in th
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+### <a name="1.0.0-previewV20"/> [1.0.0-previewV20](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/1.0.0-previewV20) - 2022-03-07
+
+#### Added
+- [#3066](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/3066) Adds dependency on the latest preview SDK version with Algorithm in EncryptionKeyWrapMetadata.
+- [#3050](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/3050) Adds the use of Azure.Core interfaces in public surface.
+
 ### <a name="1.0.0-previewV19"/> [1.0.0-previewV19](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/1.0.0-previewV19) - 2022-01-13
 
 #### Added

Microsoft.Azure.Cosmos.Encryption/src/EncryptionAlgorithm.cs → Microsoft.Azure.Cosmos.Encryption/src/DataEncryptionAlgorithm.cs

@@ -5,9 +5,9 @@
 namespace Microsoft.Azure.Cosmos.Encryption
 {
     /// <summary>
-    /// Represents the encryption algorithms supported for data encryption.
+    /// Encryption algorithms supported for data encryption.
     /// </summary>
-    public static class EncryptionAlgorithm
+    public static class DataEncryptionAlgorithm
     {
         /// <summary>
         /// Represents the authenticated encryption algorithm with associated data as described in

Microsoft.Azure.Cosmos.Encryption/src/EncryptionContainer.cs

@@ -719,6 +719,17 @@ public override async Task<FeedResponse<T>> ReadManyItemsAsync<T>(
             return this.ResponseFactory.CreateItemFeedResponse<T>(responseMessage);
         }
 
+        public override Task<ResponseMessage> DeleteAllItemsByPartitionKeyStreamAsync(
+               Cosmos.PartitionKey partitionKey,
+               RequestOptions requestOptions = null,
+               CancellationToken cancellationToken = default)
+        {
+            return this.container.DeleteAllItemsByPartitionKeyStreamAsync(
+                partitionKey,
+                requestOptions,
+                cancellationToken);
+        }
+
         public async Task<EncryptionSettings> GetOrUpdateEncryptionSettingsFromCacheAsync(
             EncryptionSettings obsoleteEncryptionSettings,
             CancellationToken cancellationToken)
@@ -730,16 +741,6 @@ public async Task<EncryptionSettings> GetOrUpdateEncryptionSettingsFromCacheAsyn
                 cancellationToken: cancellationToken);
         }
 
-#if SDKPROJECTREF
-        public override Task<ResponseMessage> DeleteAllItemsByPartitionKeyStreamAsync(
-               Cosmos.PartitionKey partitionKey,
-               RequestOptions requestOptions = null,
-               CancellationToken cancellationToken = default)
-        {
-            throw new NotImplementedException();
-        }
-#endif
-
         /// <summary>
         /// This function handles the scenario where a container is deleted(say from different Client) and recreated with same Id but with different client encryption policy.
         /// The idea is to have the container Rid cached and sent out as part of RequestOptions with Container Rid set in "x-ms-cosmos-intended-collection-rid" header.

Microsoft.Azure.Cosmos.Encryption/src/EncryptionContainerExtensions.cs

@@ -11,29 +11,33 @@ namespace Microsoft.Azure.Cosmos.Encryption
     using Microsoft.Azure.Cosmos.Linq;
 
     /// <summary>
-    /// This class provides extension methods for <see cref="Container"/>.
+    /// Extension methods for <see cref="Container"/> to support client-side encryption.
     /// </summary>
     public static class EncryptionContainerExtensions
     {
         /// <summary>
-        /// Initializes and Caches the Client Encryption Policy and the corresponding keys configured for the container.
-        /// All the keys configured as per the Client Encryption Policy for the container must be created before its used in the policy.
+        /// Warms up the caches for the client encryption policy and the corresponding client encryption keys configured for the container.
+        /// This may be used to help improve latencies for the initial requests on the container from the client.
+        /// If this is not explicitly invoked, the caches are built when requests needing encryption/decryption are made.
         /// </summary>
-        /// <param name="container">Encryption Container.</param>
-        /// <param name="cancellationToken"> cancellation token </param>
-        /// <returns>Container to perform operations supporting client-side encryption / decryption.</returns>
+        /// <param name="container">Container instance from client supporting encryption.</param>
+        /// <param name="cancellationToken">Token for request cancellation.</param>
+        /// <returns>Container with encryption-related caches warmed up.</returns>
         /// <example>
-        /// This example shows how to get a Container with Encryption support and Initialize it with InitializeEncryptionAsync which allows for pre-fetching the
-        /// encryption policy and the encryption keys for caching.
+        /// This example shows how to get a container with encryption support and warm up the encryption-related caches.
         ///
         /// <code language="c#">
         /// <![CDATA[
-        /// CosmosClient cosmosClient = new CosmosClient();
-        /// cosmosClient.WithEncryption(azureKeyVaultKeyWrapProvider);
-        /// containerWithEncryption = await this.cosmosDatabase.GetContainer("id").InitializeEncryptionAsync();
+        /// Azure.Core.TokenCredential tokenCredential = new Azure.Identity.DefaultAzureCredential();
+        /// Azure.Core.Cryptography.IKeyEncryptionKeyResolver keyResolver = new Azure.Security.KeyVault.Keys.Cryptography.KeyResolver(tokenCredential);
+        /// CosmosClient client = (new CosmosClient(endpoint, authKey)).WithEncryption(keyResolver, KeyEncryptionKeyResolverName.AzureKeyVault);
+        /// Container container = await client.GetDatabase("databaseId").GetContainer("containerId").InitializeEncryptionAsync();
         /// ]]>
         /// </code>
         /// </example>
+        /// <remarks>
+        /// See <see href="https://aka.ms/CosmosClientEncryption">client-side encryption documentation</see> for more details.
+        /// </remarks>
         public static async Task<Container> InitializeEncryptionAsync(
             this Container container,
             CancellationToken cancellationToken = default)
@@ -42,7 +46,7 @@ public static async Task<Container> InitializeEncryptionAsync(
 
             if (container is not EncryptionContainer encryptionContainer)
             {
-                throw new ArgumentOutOfRangeException($"{nameof(InitializeEncryptionAsync)} requires the use of an encryption - enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details. ");
+                throw new ArgumentOutOfRangeException($"{nameof(InitializeEncryptionAsync)} requires the use of an encryption-enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
             }
 
             await encryptionContainer.GetOrUpdateEncryptionSettingsFromCacheAsync(obsoleteEncryptionSettings: null, cancellationToken: cancellationToken);
@@ -51,30 +55,33 @@ public static async Task<Container> InitializeEncryptionAsync(
         }
 
         /// <summary>
-        /// This method gets the FeedIterator from LINQ IQueryable to execute query asynchronously.
-        /// This will create the fresh new FeedIterator when called which will support decryption.
+        /// Creates a FeedIterator from a LINQ IQueryable to be able to execute the query asynchronously.
+        /// This has support for decrypting results.
         /// </summary>
-        /// <typeparam name="T">the type of object to query.</typeparam>
-        /// <param name="container">the encryption container.</param>
-        /// <param name="query">the IQueryable{T} to be converted.</param>
-        /// <returns>An iterator to go through the items.</returns>
+        /// <typeparam name="T">The type of object to query.</typeparam>
+        /// <param name="container">Container instance from client supporting encryption.</param>
+        /// <param name="query">The <see cref="IQueryable{T}" /> to be converted.</param>
+        /// <returns>An iterator to go through the results.</returns>
         /// <example>
-        /// This example shows how to get FeedIterator from LINQ.
+        /// This example shows how to get a FeedIterator from an IQueryable with support to decrypt results.
         ///
         /// <code language="c#">
         /// <![CDATA[
-        /// IOrderedQueryable<ToDoActivity> linqQueryable = this.container.GetItemLinqQueryable<ToDoActivity>();
-        /// FeedIterator setIterator = this.container.ToEncryptionFeedIterator<ToDoActivity>(linqQueryable);
+        /// IOrderedQueryable<ToDoActivity> linqQueryable = container.GetItemLinqQueryable<ToDoActivity>();
+        /// FeedIterator<ToDoActivity> resultIterator = container.ToEncryptionFeedIterator<ToDoActivity>(linqQueryable);
         /// ]]>
         /// </code>
         /// </example>
+        /// <remarks>
+        /// See <see href="https://aka.ms/CosmosClientEncryption">client-side encryption documentation</see> for more details.
+        /// </remarks>
         public static FeedIterator<T> ToEncryptionFeedIterator<T>(
             this Container container,
             IQueryable<T> query)
         {
             if (container is not EncryptionContainer encryptionContainer)
             {
-                throw new ArgumentOutOfRangeException(nameof(query), $"{nameof(ToEncryptionFeedIterator)} requires the use of an encryption - enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details. ");
+                throw new ArgumentOutOfRangeException(nameof(query), $"{nameof(ToEncryptionFeedIterator)} requires the use of an encryption-enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
             }
 
             return new EncryptionFeedIterator<T>(
@@ -83,30 +90,33 @@ public static FeedIterator<T> ToEncryptionFeedIterator<T>(
         }
 
         /// <summary>
-        /// This method gets the FeedIterator from LINQ IQueryable to execute query asynchronously.
-        /// This will create the fresh new FeedIterator when called which will support decryption.
+        /// Creates a FeedIterator from a LINQ IQueryable to be able to execute the query asynchronously.
+        /// This has support for decrypting results.
         /// </summary>
-        /// <typeparam name="T">the type of object to query.</typeparam>
-        /// <param name="container">the encryption container.</param>
-        /// <param name="query">the IQueryable{T} to be converted.</param>
-        /// <returns>An iterator to go through the items.</returns>
+        /// <typeparam name="T">The type of object to query.</typeparam>
+        /// <param name="container">Container instance from client supporting encryption.</param>
+        /// <param name="query">The <see cref="IQueryable{T}" /> to be converted.</param>
+        /// <returns>An iterator to go through the results.</returns>
         /// <example>
         /// This example shows how to get FeedIterator from LINQ.
         ///
         /// <code language="c#">
         /// <![CDATA[
         /// IOrderedQueryable<ToDoActivity> linqQueryable = this.container.GetItemLinqQueryable<ToDoActivity>();
-        /// FeedIterator setIterator = this.container.ToEncryptionStreamIterator<ToDoActivity>(linqQueryable);
+        /// FeedIterator resultIterator = this.container.ToEncryptionStreamIterator<ToDoActivity>(linqQueryable);
         /// ]]>
         /// </code>
         /// </example>
+        /// <remarks>
+        /// See <see href="https://aka.ms/CosmosClientEncryption">client-side encryption documentation</see> for more details.
+        /// </remarks>
         public static FeedIterator ToEncryptionStreamIterator<T>(
             this Container container,
             IQueryable<T> query)
         {
             if (container is not EncryptionContainer encryptionContainer)
             {
-                throw new ArgumentOutOfRangeException(nameof(query), $"{nameof(ToEncryptionStreamIterator)} requires the use of an encryption - enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details. ");
+                throw new ArgumentOutOfRangeException(nameof(query), $"{nameof(ToEncryptionStreamIterator)} requires the use of an encryption-enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
             }
 
             return new EncryptionFeedIterator(
@@ -116,26 +126,31 @@ public static FeedIterator ToEncryptionStreamIterator<T>(
         }
 
         /// <summary>
-        /// Create a Microsoft.Azure.Cosmos.QueryDefinition with encryption support.
+        /// Creates an instance of <see cref="QueryDefinition" /> with support to add parameters
+        /// corresponding to encrypted properties.
         /// </summary>
-        /// <param name="container"> The encryption container.</param>
-        /// <param name="queryText"> A valid Cosmos SQL query "Select * from test t" </param>
-        /// <returns> Microsoft.Azure.Cosmos.QueryDefinition </returns>
+        /// <param name="container">Container instance from client supporting encryption.</param>
+        /// <param name="queryText">A valid Cosmos SQL query.</param>
+        /// <returns>A new instance of <see cref="QueryDefinition" /> with support to add encrypted parameters.</returns>
         /// <example>
-        /// This example shows how to get a QueryDefinition with Encryption Support.
+        /// This example shows how to create a QueryDefinition with support to add encrypted parameters.
         ///
         /// <code language="c#">
         /// <![CDATA[
-        /// containerWithEncryption = await this.cosmosDatabase.GetContainer("id").InitializeEncryptionAsync();
-        /// QueryDefinition withEncryptedParameter = containerWithEncryption.CreateQueryDefinition(
-        ///     "SELECT * FROM c where c.PropertyName = @PropertyValue");
-        /// await withEncryptedParameter.AddParameterAsync(
-        ///     "@PropertyName",
-        ///     PropertyValue,
-        ///     "/PropertyName");
+        /// QueryDefinition queryDefinitionWithEncryptedParameter = container.CreateQueryDefinition(
+        ///     "SELECT * FROM c where c.SensitiveProperty = @FirstParameter");
+        /// await queryDefinitionWithEncryptedParameter.AddParameterAsync(
+        ///     "@FirstParameter",
+        ///     "sensitive value",
+        ///     "/SensitiveProperty");
         /// ]]>
         /// </code>
         /// </example>
+        /// <remarks>
+        /// Only equality comparisons are supported in the filter condition on encrypted properties.
+        /// These also require the property being filtered upon to be encrypted using <see cref="EncryptionType.Deterministic"/> encryption.
+        /// See <see href="https://aka.ms/CosmosClientEncryption">client-side encryption documentation</see> for more details.
+        /// </remarks>
         public static QueryDefinition CreateQueryDefinition(this Container container, string queryText)
         {
             if (string.IsNullOrEmpty(queryText))
@@ -145,7 +160,7 @@ public static QueryDefinition CreateQueryDefinition(this Container container, st
 
             if (container is not EncryptionContainer)
             {
-                throw new ArgumentOutOfRangeException($"{nameof(CreateQueryDefinition)} requires the use of an encryption - enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details. ");
+                throw new ArgumentOutOfRangeException($"{nameof(CreateQueryDefinition)} requires the use of an encryption-enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
             }
 
             return new EncryptionQueryDefinition(queryText, container);

Microsoft.Azure.Cosmos.Encryption/src/EncryptionCosmosClient.cs

@@ -269,7 +269,7 @@ private async Task<ClientEncryptionKeyProperties> FetchClientEncryptionKeyProper
             {
                 if (ex.StatusCode == HttpStatusCode.NotFound)
                 {
-                    throw new InvalidOperationException($"Encryption Based Container without Client Encryption Keys. Please make sure you have created the Client Encryption Keys:{ex.Message}. Please refer to https://aka.ms/CosmosClientEncryption for more details. ");
+                    throw new InvalidOperationException($"Encryption Based Container without Client Encryption Keys. Please make sure you have created the Client Encryption Keys:{ex.Message}. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
                 }
                 else
                 {