Skip to content

Introduce Async API counterparts for AE base class #3673

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+96 −3
Open

Introduce Async API counterparts for AE base class #3673

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
91dea29
Introduce Async API counterparts for AE base class
cheenamalhotra Oct 8, 2025
73018a8
updates
cheenamalhotra Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 79 additions & 3 deletions doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,26 @@
Decrypts the specified encrypted value of a column encryption key. The encrypted value is expected to be encrypted using the column master key with the specified key path and using the specified algorithm.
</summary>
<returns>
Returns <see cref="T:System.Byte" />. The decrypted column encryption key.
Returns <see cref="T:System.Byte[]" /> array representing the decrypted column encryption key.
</returns>
</DecryptColumnEncryptionKey>
<DecryptColumnEncryptionKeyAsync>
<param name="masterKeyPath">
The master key path.
</param>
<param name="encryptionAlgorithm">
The encryption algorithm.
</param>
<param name="encryptedColumnEncryptionKey">
The encrypted column encryption key.
</param>
<summary>
Decrypts the specified encrypted value of a column encryption key asynchronously. The encrypted value is expected to be encrypted using the column master key with the specified key path and using the specified algorithm.
</summary>
<returns>
Returns a task that returns <see cref="T:System.Byte[]" /> array representing the decrypted column encryption key on completion.
</returns>
</DecryptColumnEncryptionKeyAsync>
<EncryptColumnEncryptionKey>
<param name="masterKeyPath">
The master key path.
Expand All @@ -41,9 +58,26 @@
Encrypts a column encryption key using the column master key with the specified key path and using the specified algorithm.
</summary>
<returns>
Returns <see cref="T:System.Byte" />. The encrypted column encryption key.
Returns <see cref="T:System.Byte[]" /> array representing the encrypted column encryption key.
</returns>
</EncryptColumnEncryptionKey>
<EncryptColumnEncryptionKeyAsync>
<param name="masterKeyPath">
The master key path.
</param>
<param name="encryptionAlgorithm">
The encryption algorithm.
</param>
<param name="columnEncryptionKey">
The plaintext column encryption key.
</param>
<summary>
Encrypts a column encryption key asynchronously using the column master key with the specified key path and using the specified algorithm.
</summary>
<returns>
Returns a task that returns <see cref="T:System.Byte[]" /> array representing the encrypted column encryption key on completion.
</returns>
</EncryptColumnEncryptionKeyAsync>
<SignColumnMasterKeyMetadata>
<param name="masterKeyPath">
The column master key path.
Expand All @@ -55,7 +89,7 @@
When implemented in a derived class, digitally signs the column master key metadata with the column master key referenced by the <paramref name="masterKeyPath" /> parameter. The input values used to generate the signature should be the specified values of the <paramref name="masterKeyPath" /> and <paramref name="allowEnclaveComputations" /> parameters.
</summary>
<returns>
The signature of the column master key metadata.
Returns the signature of the column master key metadata.
</returns>
<remarks>
<para>
Expand All @@ -69,6 +103,31 @@
In all cases.
</exception>
</SignColumnMasterKeyMetadata>
<SignColumnMasterKeyMetadataAsync>
<param name="masterKeyPath">
The column master key path.
</param>
<param name="allowEnclaveComputations">
<see langword="true" /> to indicate that the column master key supports enclave computations; otherwise, <see langword="false" />.
</param>
<summary>
When implemented in a derived class, asynchronously digitally signs the column master key metadata with the column master key referenced by the <paramref name="masterKeyPath" /> parameter. The input values used to generate the signature should be the specified values of the <paramref name="masterKeyPath" /> and <paramref name="allowEnclaveComputations" /> parameters.
</summary>
<returns>
Returns a task that returns the signature of the column master key metadata on completion.
</returns>
<remarks>
<para>
To ensure that the <see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" /> method doesn't break applications that rely on an old API, it throws a <see cref="T:System.NotImplementedException" /> exception by default.
</para>
<para>
The <see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" /> method will be used by client tools that generate Column Master Keys (CMK) for customers. <see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" /> must be implemented by the corresponding key store providers that wish to use enclaves with <see href="https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted</see>.
</para>
</remarks>
<exception cref="T:System.NotImplementedException">
In all cases.
</exception>
</SignColumnMasterKeyMetadataAsync>
<VerifyColumnMasterKeyMetadata>
<param name="masterKeyPath">
The column master key path.
Expand All @@ -86,6 +145,23 @@
When implemented in a derived class, the method is expected to return true if the specified signature is valid, or false if the specified signature is not valid. The default implementation throws `NotImplementedException`.
</returns>
</VerifyColumnMasterKeyMetadata>
<VerifyColumnMasterKeyMetadataAsync>
<param name="masterKeyPath">
The column master key path.
</param>
<param name="allowEnclaveComputations">
Indicates whether the column master key supports enclave computations.
</param>
<param name="signature">
The signature of the column master key metadata.
</param>
<summary>
When implemented in a derived class, this method is expected to verify the specified signature is valid for the column master key with the specified key path and the specified enclave behavior asynchronously. The default implementation throws `NotImplementedException`.
</summary>
<returns>
When implemented in a derived class, the method is expected to return true if the specified signature is valid, or false if the specified signature is not valid. The default implementation throws `NotImplementedException`.
</returns>
</VerifyColumnMasterKeyMetadataAsync>
<ColumnEncryptionKeyCacheTtl>
<summary>
Gets or sets the lifespan of the decrypted column encryption key in the cache. Once the timespan has elapsed, the decrypted column encryption key is discarded and must be revalidated.
Expand Down
17 changes: 17 additions & 0 deletions ...rosoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlColumnEncryptionKeyStoreProvider.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
// See the LICENSE file in the project root for more information.

using System;
using System.Threading.Tasks;

namespace Microsoft.Data.SqlClient
{
Expand All @@ -16,19 +17,35 @@ public abstract class SqlColumnEncryptionKeyStoreProvider
/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionKeyStoreProvider"]/DecryptColumnEncryptionKey/*'/>
public abstract byte[] DecryptColumnEncryptionKey(string masterKeyPath, string encryptionAlgorithm, byte[] encryptedColumnEncryptionKey);

/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionKeyStoreProvider"]/DecryptColumnEncryptionKeyAsync/*'/>
public virtual Task<byte[]> DecryptColumnEncryptionKeyAsync(string masterKeyPath, string encryptionAlgorithm, byte[] encryptedColumnEncryptionKey)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cryptographic tasks will normally complete synchronously; Azure Key Vault is the exception here. What about returning ValueTask<byte[]>, to remove an allocation in the synchronous case?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since these 4 new async methods are all implemented by calling their synchronous counterparts, I would agree that the operations will definitely complete synchronously.

Do we plan to re-implement these in terms of some other underlying async methods later?

Copy link
Member Author

@cheenamalhotra cheenamalhotra Oct 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, these implementations will be re-implemented in all Key Vault providers, as issue #3672 covers. Both sync and async will be made truly sync and truly async flows - with external calls separated.

Also, in the codebase, we want to make sure we call sync v/s async APIs of AE that are separated based on caller.

This, here, is a fallback for any consumer of AE implementation without async implementation.

=> Task.FromResult(DecryptColumnEncryptionKey(masterKeyPath, encryptionAlgorithm, encryptedColumnEncryptionKey));

/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionKeyStoreProvider"]/EncryptColumnEncryptionKey/*'/>
public abstract byte[] EncryptColumnEncryptionKey(string masterKeyPath, string encryptionAlgorithm, byte[] columnEncryptionKey);

/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionKeyStoreProvider"]/EncryptColumnEncryptionKeyAsync/*'/>
public virtual Task<byte[]> EncryptColumnEncryptionKeyAsync(string masterKeyPath, string encryptionAlgorithm, byte[] columnEncryptionKey)
=> Task.FromResult(EncryptColumnEncryptionKey(masterKeyPath, encryptionAlgorithm, columnEncryptionKey));

/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionKeyStoreProvider"]/SignColumnMasterKeyMetadata/*'/>
public virtual byte[] SignColumnMasterKeyMetadata(string masterKeyPath, bool allowEnclaveComputations)
{
throw new NotImplementedException();
}

/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionKeyStoreProvider"]/SignColumnMasterKeyMetadataAsync/*'/>
public virtual Task<byte[]> SignColumnMasterKeyMetadataAsync(string masterKeyPath, bool allowEnclaveComputations)
=> Task.FromResult(SignColumnMasterKeyMetadata(masterKeyPath, allowEnclaveComputations));

/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionKeyStoreProvider"]/VerifyColumnMasterKeyMetadata/*'/>
public virtual bool VerifyColumnMasterKeyMetadata(string masterKeyPath, bool allowEnclaveComputations, byte[] signature)
{
throw new NotImplementedException();
}

/// <include file='../../../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionKeyStoreProvider"]/VerifyColumnMasterKeyMetadataAsync/*'/>
public virtual Task<bool> VerifyColumnMasterKeyMetadataAsync(string masterKeyPath, bool allowEnclaveComputations, byte[] signature)
=> Task.FromResult(VerifyColumnMasterKeyMetadata(masterKeyPath, allowEnclaveComputations, signature));
}
}
Loading