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
Merged

Introduce Async API counterparts for AE base class #3673

Show file tree
Hide file tree
Changes from all 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
273 changes: 250 additions & 23 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 @@ -11,51 +11,159 @@
</summary>
</ctor>
<DecryptColumnEncryptionKey>
<summary>
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>
<param name="masterKeyPath">
The master key path.
The column master key path. The path format is specific to the key
store provider implementation (e.g. a thumbprint for the certificate
store, or a key identifier URL for Azure Key Vault).
</param>
<param name="encryptionAlgorithm">
The encryption algorithm.
The encryption algorithm name. For example,
<c>RSA_OAEP</c>.
</param>
<param name="encryptedColumnEncryptionKey">
The encrypted column encryption key.
</param>
<returns>
Returns a <see cref="T:System.Byte[]" /> representing the decrypted
column encryption key.
</returns>
</DecryptColumnEncryptionKey>
<DecryptColumnEncryptionKeyAsync>
<summary>
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.
Asynchronously 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>
<param name="masterKeyPath">
The column master key path. The path format is specific to the key
store provider implementation (e.g. a thumbprint for the certificate
store, or a key identifier URL for Azure Key Vault).
</param>
<param name="encryptionAlgorithm">
The encryption algorithm name. For example,
<c>RSA_OAEP</c>.
</param>
<param name="encryptedColumnEncryptionKey">
The encrypted column encryption key.
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</param>
<returns>
Returns <see cref="T:System.Byte" />. The decrypted column encryption key.
A task that returns a <see cref="T:System.Byte[]" /> representing
the decrypted column encryption key on completion.
</returns>
</DecryptColumnEncryptionKey>
<remarks>
<para>
The default implementation first checks the
<paramref name="cancellationToken" /> and returns a canceled task
if cancellation has been requested. Otherwise, it calls the
synchronous
<see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.DecryptColumnEncryptionKey(System.String,System.String,System.Byte[])" />
method and wraps the result in a completed task. If the synchronous
method throws, the exception is caught and a faulted task is
returned rather than throwing synchronously.
</para>
<para>
Derived classes that perform I/O (such as calls to Azure Key Vault)
should override this method with a truly asynchronous
implementation that honors the cancellation token.
</para>
</remarks>
</DecryptColumnEncryptionKeyAsync>
Comment thread
cheenamalhotra marked this conversation as resolved.
<EncryptColumnEncryptionKey>
<summary>
Encrypts a column encryption key using the column master key with
the specified key path and using the specified algorithm.
</summary>
<param name="masterKeyPath">
The master key path.
The column master key path. The path format is specific to the key
store provider implementation (e.g. a thumbprint for the certificate
store, or a key identifier URL for Azure Key Vault).
</param>
<param name="encryptionAlgorithm">
The encryption algorithm.
The encryption algorithm name. For example,
<c>RSA_OAEP</c>.
</param>
<param name="columnEncryptionKey">
The plaintext column encryption key.
The column encryption key to encrypt.
</param>
<returns>
Returns a <see cref="T:System.Byte[]" /> representing the encrypted
column encryption key.
</returns>
</EncryptColumnEncryptionKey>
<EncryptColumnEncryptionKeyAsync>
Comment thread
paulmedynski marked this conversation as resolved.
<summary>
Encrypts a column encryption key using the column master key with the specified key path and using the specified algorithm.
Asynchronously encrypts a column encryption key using the column
master key with the specified key path and using the specified
algorithm.
</summary>
<param name="masterKeyPath">
The column master key path. The path format is specific to the key
store provider implementation (e.g. a thumbprint for the certificate
store, or a key identifier URL for Azure Key Vault).
</param>
<param name="encryptionAlgorithm">
The encryption algorithm name. For example,
<c>RSA_OAEP</c>.
</param>
<param name="columnEncryptionKey">
The column encryption key to encrypt.
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</param>
<returns>
Returns <see cref="T:System.Byte" />. The encrypted column encryption key.
A task that returns a <see cref="T:System.Byte[]" /> representing
the encrypted column encryption key on completion.
</returns>
</EncryptColumnEncryptionKey>
<remarks>
<para>
The default implementation first checks the
<paramref name="cancellationToken" /> and returns a canceled task
if cancellation has been requested. Otherwise, it calls the
synchronous
<see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.EncryptColumnEncryptionKey(System.String,System.String,System.Byte[])" />
method and wraps the result in a completed task. If the synchronous
method throws, the exception is caught and a faulted task is
returned rather than throwing synchronously.
</para>
<para>
Derived classes that perform I/O (such as calls to Azure Key Vault)
should override this method with a truly asynchronous
implementation that honors the cancellation token.
</para>
</remarks>
</EncryptColumnEncryptionKeyAsync>
<SignColumnMasterKeyMetadata>
<summary>
When implemented in a derived class, signs the column master key
metadata with the column master key referenced by the
<paramref name="masterKeyPath" /> parameter.
</summary>
<param name="masterKeyPath">
The column master key path.
The column master key path. The path format is specific to the key
store provider implementation (e.g. a thumbprint for the certificate
store, or a key identifier URL for Azure Key Vault).
</param>
<param name="allowEnclaveComputations">
<see langword="true" /> to indicate that the column master key supports enclave computations; otherwise, <see langword="false" />.
<see langword="true" /> to indicate that the column master key
supports enclave computations; otherwise,
<see langword="false" />. When <see langword="true" />, the
generated signature covers the enclave-enabled property so that
the metadata can later be verified for enclave use.
</param>
<summary>
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. The format
is provider-specific.
</returns>
<remarks>
<para>
Expand All @@ -69,23 +177,142 @@
In all cases.
</exception>
</SignColumnMasterKeyMetadata>
<SignColumnMasterKeyMetadataAsync>
<summary>
When implemented in a derived class, asynchronously signs the column
master key metadata with the column master key referenced by the
<paramref name="masterKeyPath" /> parameter.
</summary>
<param name="masterKeyPath">
The column master key path. The path format is specific to the key
store provider implementation (e.g. a thumbprint for the certificate
store, or a key identifier URL for Azure Key Vault).
</param>
<param name="allowEnclaveComputations">
<see langword="true" /> to indicate that the column master key
supports enclave computations; otherwise,
<see langword="false" />. When <see langword="true" />, the
generated signature covers the enclave-enabled property so that
the metadata can later be verified for enclave use.
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</param>
<returns>
A task that, when completed, returns a <see cref="T:System.Byte[]" />
representing the signature of the column master key metadata. The
signature format is provider-specific.
</returns>
<remarks>
<para>
The default implementation first checks the
<paramref name="cancellationToken" /> and returns a canceled task
if cancellation has been requested. Otherwise, it 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" /> rather than
throwing synchronously.
</para>
<para>
Comment thread
cheenamalhotra marked this conversation as resolved.
Derived classes that perform I/O should override this method with
a truly asynchronous implementation that honors the cancellation
token.
</para>
<para>
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>
<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. The
default implementation throws
<see cref="T:System.NotImplementedException" />.
</summary>
<param name="masterKeyPath">
The column master key path.
The column master key path. The path format is specific to the key
store provider implementation (e.g. a thumbprint for the certificate
store, or a key identifier URL for Azure Key Vault).
</param>
<param name="allowEnclaveComputations">
Indicates whether the column master key supports enclave computations.
Indicates whether the column master key supports enclave
computations. This value must match what was passed to
<see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" />
when the signature was generated.
</param>
<param name="signature">
The signature of the column master key metadata.
The signature to verify, as previously returned by
<see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" />.
The format is provider-specific.
</param>
<returns>
When implemented in a derived class, the method is expected to
return <see langword="true" /> if the specified signature is valid,
or <see langword="false" /> if the specified signature is not valid.
The default implementation throws
<see cref="T:System.NotImplementedException" />.
</returns>
</VerifyColumnMasterKeyMetadata>
<VerifyColumnMasterKeyMetadataAsync>
<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. The default implementation throws `NotImplementedException`.
When implemented in a derived class, asynchronously verifies the
specified signature is valid for the column master key with the
specified key path and the specified enclave behavior. The default
implementation returns a faulted task with
<see cref="T:System.NotImplementedException" />.
</summary>
<param name="masterKeyPath">
The column master key path. The path format is specific to the key
store provider implementation (e.g. a thumbprint for the certificate
store, or a key identifier URL for Azure Key Vault).
</param>
<param name="allowEnclaveComputations">
Indicates whether the column master key supports enclave
computations. This value must match what was passed to
<see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" />
when the signature was generated.
</param>
<param name="signature">
The signature to verify, as previously returned by
<see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.SignColumnMasterKeyMetadata(System.String,System.Boolean)" />.
The format is provider-specific.
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</param>
<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`.
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>
</VerifyColumnMasterKeyMetadata>
<remarks>
<para>
The default implementation first checks the
<paramref name="cancellationToken" /> and returns a canceled task
if cancellation has been requested. Otherwise, it calls the
synchronous
<see cref="M:Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider.VerifyColumnMasterKeyMetadata(System.String,System.Boolean,System.Byte[])" />
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" /> rather than
throwing synchronously.
</para>
<para>
Derived classes that perform I/O should override this method with
a truly asynchronous implementation that honors the cancellation
token.
</para>
</remarks>
</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