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

Merged
cheenamalhotra merged 13 commits into from
Jul 14, 2026
+914 −23
Merged

Introduce Async API counterparts for AE base class #3673

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
a290bae
Introduce Async API counterparts for AE base class
cheenamalhotra Oct 8, 2025
5af579f
updates
cheenamalhotra Oct 8, 2025
a7be2f4
Updates to async APIs - addressed feedback
cheenamalhotra May 13, 2026
fd7bad0
Address docs
cheenamalhotra May 13, 2026
87f1f08
Address review feedback: improve XML docs and add nullable annotations
cheenamalhotra Jul 9, 2026
84f40c5
Address mdaigle review: two overloads, cancellation check, move tests
cheenamalhotra Jul 9, 2026
ec0af7b
Address remaining review comments: docs and test improvements
cheenamalhotra Jul 10, 2026
c29a5a2
Fix ref build: remove #nullable directives causing CS8597
cheenamalhotra Jul 10, 2026
b3d361b
Simplify spec: use GetOrCreateAsync, remove redundancy
cheenamalhotra Jul 10, 2026
f95b00f
Add XML summary docs to async test class
cheenamalhotra Jul 10, 2026
064429b
Add XML docs to all test methods, add Sign/Verify convenience overloa…
cheenamalhotra Jul 10, 2026
8755405
Simplify to single overload with CancellationToken = default
cheenamalhotra Jul 10, 2026
bd9cae5
Use IsCatchableExceptionType filter in async catch blocks
cheenamalhotra Jul 10, 2026
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
91 changes: 88 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,29 @@
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.
Comment thread
cheenamalhotra marked this conversation as resolved.
Outdated
</returns>
</DecryptColumnEncryptionKey>
<DecryptColumnEncryptionKeyAsync>
<param name="masterKeyPath">
The master key path.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</param>
<param name="encryptionAlgorithm">
The encryption algorithm.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</param>
<param name="encryptedColumnEncryptionKey">
The encrypted column encryption key.
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</param>
<summary>
Comment thread
mdaigle marked this conversation as resolved.
Outdated
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.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</summary>
<returns>
Returns a task that returns <see cref="T:System.Byte[]" /> array representing the decrypted column encryption key on completion.
Comment thread
cheenamalhotra marked this conversation as resolved.
Outdated
</returns>
</DecryptColumnEncryptionKeyAsync>
Comment thread
cheenamalhotra marked this conversation as resolved.
<EncryptColumnEncryptionKey>
<param name="masterKeyPath">
The master key path.
Expand All @@ -41,9 +61,29 @@
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.
Comment thread
cheenamalhotra marked this conversation as resolved.
Outdated
</returns>
</EncryptColumnEncryptionKey>
<EncryptColumnEncryptionKeyAsync>
Comment thread
paulmedynski marked this conversation as resolved.
<param name="masterKeyPath">
The master key path.
</param>
<param name="encryptionAlgorithm">
The encryption algorithm.
</param>
<param name="columnEncryptionKey">
The plaintext column encryption key.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</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.
Comment thread
cheenamalhotra marked this conversation as resolved.
Outdated
</returns>
</EncryptColumnEncryptionKeyAsync>
<SignColumnMasterKeyMetadata>
<param name="masterKeyPath">
The column master key path.
Expand All @@ -55,7 +95,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 +109,31 @@
In all cases.
</exception>
</SignColumnMasterKeyMetadata>
<SignColumnMasterKeyMetadataAsync>
<param name="masterKeyPath">
The column master key path.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</param>
<param name="allowEnclaveComputations">
<see langword="true" /> to indicate that the column master key supports enclave computations; otherwise, <see langword="false" />.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</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.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</summary>
<returns>
Returns a task that returns the signature of the column master key metadata on completion.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</returns>
<remarks>
<para>
The default implementation calls the synchronous <see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" /> method, which throws a <see cref="T:System.NotImplementedException" /> by default. In this case, the returned task will be faulted with <see cref="T:System.NotImplementedException" />.
</para>
<para>
Comment thread
cheenamalhotra marked this conversation as resolved.
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> should override this method with a truly asynchronous implementation when the signing operation involves I/O.
</para>
</remarks>
</SignColumnMasterKeyMetadataAsync>
<VerifyColumnMasterKeyMetadata>
<param name="masterKeyPath">
The column master key path.
Expand All @@ -86,6 +151,26 @@
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.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</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.
Comment thread
mdaigle marked this conversation as resolved.
Outdated
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</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 returns a faulted task with <see cref="T:System.NotImplementedException" />.
</summary>
<returns>
A task that, when completed, returns <see langword="true" /> if the specified signature is valid, or <see langword="false" /> if it is not valid.
</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
Loading
Loading