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
cheenamalhotra wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Introduce Async API counterparts for AE base class #3673

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 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
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
118 changes: 115 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,37 @@
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.
Copy link
Copy Markdown
Contributor

@mdaigle mdaigle May 18, 2026

Choose a reason for hiding this comment

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

Suggested change
Returns <see cref="T:System.Byte[]" /> array representing the decrypted column encryption key.
Returns a <see cref="T:System.Byte[]" /> representing the decrypted column encryption key.

</returns>
</DecryptColumnEncryptionKey>
<DecryptColumnEncryptionKeyAsync>
<param name="masterKeyPath">
The master key path.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

What kind of path is this expected to be? Local filesystem, UNC, URL ... ?

For example:

The local filesystem path to the master key file.  This will be used by <.NET API>; see [here] for further information.

Copy link
Copy Markdown
Contributor

@edwardneal edwardneal May 15, 2026

Choose a reason for hiding this comment

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

From SQL Server's perspective, masterKeyPath is an opaque provider-specific string. It's designed to uniquely identify the key material for a specific cryptographic key within the provider. For AKV, it'll be a URI; for certificates, it'll be [Store Location]/[Store Name]/[Thumbprint]. The rest of SqlClient doesn't know about its format.

</param>
<param name="encryptionAlgorithm">
The encryption algorithm.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

What kind of values are expected/accepted here? Is it an opaque string to us? Examples and where they are documented would help.

Copy link
Copy Markdown
Contributor

@edwardneal edwardneal May 15, 2026

Choose a reason for hiding this comment

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

It's a technically-opaque string returned by SQL Server - for the moment, it's always RSA_OAEP. This is documented here, in the algorithm_name argument.

</param>
<param name="encryptedColumnEncryptionKey">
The encrypted column encryption key.
</param>
<param name="cancellationToken">
A token to cancel the asynchronous operation.
</param>
<summary>
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

Seems weird to put the summary after the arguments.

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.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

IMO we should wrap long lines to our standard 100 chars.

</summary>
<returns>
Returns a task that returns <see cref="T:System.Byte[]" /> array representing the decrypted column encryption key on completion.
Copy link
Copy Markdown
Contributor

@mdaigle mdaigle May 18, 2026

Choose a reason for hiding this comment

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

Suggested change
Returns a task that returns <see cref="T:System.Byte[]" /> array representing the decrypted column encryption key on completion.
Returns a task that returns a <see cref="T:System.Byte[]" /> representing the decrypted column encryption key on completion.

</returns>
<remarks>
<para>
The default implementation 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>
The <paramref name="cancellationToken" /> parameter is not observed by the default implementation. 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>
<param name="masterKeyPath">
The master key path.
Expand All @@ -41,9 +69,37 @@
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.
Copy link
Copy Markdown
Contributor

@mdaigle mdaigle May 18, 2026

Choose a reason for hiding this comment

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

Suggested change
Returns <see cref="T:System.Byte[]" /> array representing the encrypted column encryption key.
Returns a <see cref="T:System.Byte[]" /> representing the encrypted column encryption key.

</returns>
</EncryptColumnEncryptionKey>
<EncryptColumnEncryptionKeyAsync>
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

Same comments regarding arguments here as with Decrypt above.

<param name="masterKeyPath">
The master key path.
</param>
<param name="encryptionAlgorithm">
The encryption algorithm.
</param>
<param name="columnEncryptionKey">
The plaintext column encryption key.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

It's a byte array, so it isn't text, per se. I would suggest: The column encryption key to encrypt

</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.
Copy link
Copy Markdown
Contributor

@mdaigle mdaigle May 18, 2026

Choose a reason for hiding this comment

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

Suggested change
Returns a task that returns <see cref="T:System.Byte[]" /> array representing the encrypted column encryption key on completion.
Returns a task that returns a <see cref="T:System.Byte[]" /> representing the encrypted column encryption key on completion.

</returns>
<remarks>
<para>
The default implementation 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>
The <paramref name="cancellationToken" /> parameter is not observed by the default implementation. 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>
<param name="masterKeyPath">
The column master key path.
Expand All @@ -55,7 +111,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 +125,34 @@
In all cases.
</exception>
</SignColumnMasterKeyMetadata>
<SignColumnMasterKeyMetadataAsync>
<param name="masterKeyPath">
The column master key path.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

Same comment regarding paths.

</param>
<param name="allowEnclaveComputations">
<see langword="true" /> to indicate that the column master key supports enclave computations; otherwise, <see langword="false" />.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

But what actually happens when I specify true vs false?

Copy link
Copy Markdown
Contributor

@edwardneal edwardneal May 15, 2026

Choose a reason for hiding this comment

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

This is handled within SQL Server. It's only used during enclave-enabled Always Encrypted, and the flag indicates that the key can be passed into the secure enclave. From the view of this part of SqlClient, it's an opaque flag which is designed to be signed.

The idea here is that SQL Server's record of the column master key is little more than metadata. This method locates the key material identified by the key path, then signs the metadata that SQL Server holds. SQL Server keeps a record of that signature, and passes it to the client for validation. It forms a trust anchor for cases where SQL Server itself is compromised, but the enclave can't be tampered with: if someone modifies the CMK's key path (to try and force the client to encrypt data with an attacker-specified key) then this validation fails. The attacker can't just recalculate the correct signature because SQL Server doesn't have access to the key material - just its metadata.

</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.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

digitally isn't necessary.

I'm not sure what the second sentence is trying to say. It sounds like "We will use the method arguments to do the work", which is obvious.

</summary>
<returns>
Returns a task that returns the signature of the column master key metadata on completion.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

What is the format/encoding of the signature? Is it HMAC, SHA256, etc?

Copy link
Copy Markdown
Contributor

@edwardneal edwardneal May 15, 2026

Choose a reason for hiding this comment

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

Strictly speaking, it's opaque. For the builtin providers' purposes, it's an RSA signature of the SHA256 hash of [Provider Name] + [Master Key Path] + [Enclave Computations Enabled]. The only real API requirement that is that an untampered signature verifies successfully, and a tampered signature does not.

</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" /> rather than throwing synchronously.
</para>
<para>
Comment thread
cheenamalhotra marked this conversation as resolved.
The <paramref name="cancellationToken" /> parameter is not observed by the default implementation. 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>
<param name="masterKeyPath">
The column master key path.
Expand All @@ -86,6 +170,34 @@
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.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

Same path and enclave comments.

</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.
Copy link
Copy Markdown
Contributor

@paulmedynski paulmedynski May 15, 2026

Choose a reason for hiding this comment

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

Is this expected to be a byte array returned by Sign() ? Would this accept any format/encoding signature type?

</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>
<remarks>
<para>
The default implementation 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>
The <paramref name="cancellationToken" /> parameter is not observed by the default implementation. 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