Implement async APIs in Always Encrypted Azure Key Vault provider

[cheenamalhotra]

Description

Implements the four asynchronous key store provider APIs on
SqlColumnEncryptionAzureKeyVaultProvider, overriding the base class virtuals
added in #3673. Phase 2A of specs/002-async-always-encrypted/spec.md.

New

• EncryptColumnEncryptionKeyAsync, DecryptColumnEncryptionKeyAsync,
  SignColumnMasterKeyMetadataAsync, VerifyColumnMasterKeyMetadataAsync.
  These call the Azure SDK's own async methods and flow the cancellation token
  to them, rather than completing sync work on a returned task.
• LocalCache.GetOrCreateAsync, plus a KeyedAsyncLock<TKey> helper that gates
  concurrent misses per key so a burst of callers makes one Key Vault request.
• Shared parse and build helpers extracted from the sync methods rather than
  duplicated.

Behavior considerations

• The CEK and signature caches are shared with the sync path, so a key decrypted
  by one is visible to the other.
• Gating is per key and only ever awaited, so no thread blocks and misses for
  different keys stay parallel. Cancellation applies to the requesting caller
  only; if the gate owner is cancelled or fails, the next waiter retries with
  its own token and failures are not cached.
• AddKeyAsync deliberately does not share _keyDictionarySemaphore with sync
  AddKey. A sync caller blocking on a gate held across an awaited network call
  would tie up a thread pool thread for that call's duration. Consequence: a
  sync and an async caller may both fetch the same key, yielding the same result.
• Cancellation is checked before argument validation, matching
  SqlColumnEncryptionKeyStoreProvider.
• Validation failures surface through the returned task, not thrown
  synchronously, matching FR-003.
• With caching disabled (ColumnEncryptionKeyCacheTtl of zero) gating is
  bypassed, since there is no entry for a waiter to observe. Callers reach Key
  Vault in parallel where the sync path serialized them.
• VerifyColumnMasterKeyMetadata and VerifyColumnMasterKeyMetadataAsync now
  both reject a null or empty signature with ArgumentNullException /
  ArgumentException. Previously it reached the Azure SDK and failed there. This
  is a deliberate behavior change to the existing sync API, kept in both
  overloads for parity; in-product callers are unaffected because
  SqlSecurityUtility.VerifyColumnMasterKeySignature already rejects it upstream.
  Worth a release note callout.
• Requires Microsoft.Data.SqlClient 7.1 or later at runtime. The NuGet floor
  covers restore, but a runtime downgrade below 7.1 produces a
  TypeLoadException because assembly versions unify at major.0.0.0. Worth a
  release note callout.

Incidental fixes in code the refactor touched

• LocalCache.GetOrCreate compacts on Count >= maxSize rather than ==; the
  equality test could be stepped past under concurrency, permanently disabling
  compaction on the 2000 entry signature cache.
• GetCryptographyClient used TryGetValue then TryAdd, so concurrent
  callers could each use a different CryptographyClient for one key. Now
  GetOrAdd.
• Dropped an unreachable null check on a buffer allocated by new byte[] on the
  preceding line.

No public API removed or changed.

Issues

Addresses #3672 (Step 2)

Testing

AKVUnitTests: async encrypt/decrypt and sign/verify round trips; sync and
async keys interchangeable; caching during async decryption and sharing with the
sync path; caching disabled at TTL zero; signature verification caching; 32
concurrent decryptions collapsing to one cache entry; cancelled decryptions not
accumulating gates; cancellation honoured and taking precedence over validation;
master key path validation.

ExceptionTestAKVStore: argument validation for all four members, plus invalid
algorithm version, invalid signature and invalid cipher text length.

These need a live vault and are gated on DataTestUtility.IsAKVSetupAvailable,
so they run in the pipeline. LocalCache and KeyedAsyncLock concurrency was
additionally verified locally against the built assembly with a standalone
harness covering deduplication, parallelism across keys, cancelled waiters,
owner failure and retry, gate cleanup and compaction.

Sync behavior preservation was checked by comparing every statement of the
original sync encrypt and decrypt methods against the current file. All are
preserved except the unreachable null check above and a dead store to a
position variable never read after its final update.

[Copilot]

Pull request overview

This PR adds truly asynchronous Always Encrypted key store operations to the Azure Key Vault provider, wiring the provider’s async overrides to Azure SDK async calls and extending local caching with async entry creation + per-key deduplication gates to avoid bursty duplicate Key Vault requests.

Changes:

• Implemented async overrides in SqlColumnEncryptionAzureKeyVaultProvider for encrypt/decrypt and CMK metadata sign/verify, flowing CancellationToken to Azure SDK async APIs.
• Added async-capable LocalCache.GetOrCreateAsync plus a per-key KeyedAsyncLock<TKey> to deduplicate concurrent cache misses without blocking threads.
• Expanded AKV manual tests to cover async round-trips, cache sharing between sync/async, cancellation, and concurrency semantics.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider/src/SqlColumnEncryptionAzureKeyVaultProvider.cs	Adds async overrides for AE AKV provider and extracts shared parsing/message helpers for CEK/signature handling.
src/Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider/src/LocalCache.cs	Introduces async cache entry creation with per-key gating and fixes compaction threshold under concurrency.
src/Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider/src/KeyedAsyncLock.cs	New helper providing per-key async mutual exclusion with gate cleanup.
src/Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider/src/AzureSqlKeyCryptographer.cs	Adds async key fetch/sign/verify/wrap/unwrap APIs and deduplicates concurrent key fetches per key.
src/Microsoft.Data.SqlClient/tests/ManualTests/AlwaysEncrypted/AKVUnitTests.cs	Adds manual tests for async API behavior, caching/deduplication, and cancellation semantics.
src/Microsoft.Data.SqlClient/tests/ManualTests/AlwaysEncrypted/ExceptionTestAKVStore.cs	Adds manual tests for async encrypt/decrypt argument validation and decrypt failure modes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/Microsoft.Data.SqlClient/tests/ManualTests/AlwaysEncrypted/ExceptionTestAKVStore.cs:84

• These assertions use Assert.Matches with a plain message string that includes regex metacharacters (e.g., the trailing '.' in the null-path case). That makes the check less precise than intended and can produce false positives. Since the goal is substring matching (prefix may vary), Assert.Contains is a better fit here.

            string expectedMessage = masterKeyPath == null
                ? "Azure Key Vault key path cannot be null."
                : "Invalid Azure Key Vault key path specified";

            Assert.Matches(expectedMessage, signException.Message);
            Assert.Matches(expectedMessage, verifyException.Message);

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.08%. Comparing base (ee529d4) to head (37f9373).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4540      +/-   ##
==========================================
- Coverage   64.78%   63.08%   -1.70%     
==========================================
  Files         288      283       -5     
  Lines       44418    67609   +23191     
==========================================
+ Hits        28774    42654   +13880     
- Misses      15644    24955    +9311     

Flag	Coverage Δ
CI-SqlClient	?
PR-SqlClient-Project	63.08% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[priyankatiwari08]

Overall looks good, just few small comments need to be addressed.