Interface IKeyWrappingProvider
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Wraps and unwraps a locally-generated data encryption key (DEK) under a key the provider holds, without that key ever leaving the provider.
public interface IKeyWrappingProvider
Remarks
This is the production key path for encryption providers. A key management service — a cloud KMS or an HSM — deliberately does not export key bytes; that non-export property is the reason to use one. An encryption provider therefore cannot obtain raw master-key material from such a service, and a provider that demands raw material can only ever be satisfied by an in-process key holder whose keys do not survive a restart.
Envelope encryption resolves this. The caller generates a single-use DEK from a cryptographic random
source, encrypts the payload with it locally, and asks the key service to wrap the DEK. Only
the wrapped DEK is persisted. To decrypt, the caller asks the key service to unwrap it. The service
performs the wrap and unwrap internally and never discloses the wrapping key, so the guarantee the
service exists to provide is preserved rather than defeated. This is the construction used by
Microsoft.AspNetCore.DataProtection key ring encryption, Azure Key Vault
WrapKey/UnwrapKey, and AWS KMS GenerateDataKey.
This is an optional capability. A provider advertises it by answering for it from GetService(Type); consumers query for it rather than casting, so the capability remains discoverable through decorators. A provider may supply this capability, raw key material, both, or neither.
Implementations MUST NOT log, cache, or otherwise retain the plaintext DEK, and MUST fail closed: an unwrap that cannot be completed, or whose integrity check fails, throws rather than returning a substituted or empty key.
Methods
UnwrapDataKeyAsync(string, int, WrappedDataKey, CancellationToken)
Unwraps a data encryption key previously produced by WrapDataKeyAsync(string, int, byte[], CancellationToken).
Task<byte[]> UnwrapDataKeyAsync(string keyId, int version, WrappedDataKey wrappedKey, CancellationToken cancellationToken)
Parameters
keyIdstringThe identifier of the wrapping key held by this provider.
versionintThe version of the wrapping key that produced
wrappedKey.wrappedKeyWrappedDataKeyThe wrapped key to unwrap.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<byte[]>
The plaintext data encryption key. The caller owns the returned array and SHOULD clear it with ZeroMemory(Span<byte>) once finished.
Exceptions
- ArgumentNullException
Thrown when
keyIdorwrappedKeyis null.- EncryptionException
Thrown when the wrapped key cannot be unwrapped — the wrapping key is unavailable, destroyed, or does not match. Implementations MUST fail rather than return a key that did not round-trip.
WrapDataKeyAsync(string, int, byte[], CancellationToken)
Wraps a data encryption key under the specified key version.
Task<WrappedDataKey> WrapDataKeyAsync(string keyId, int version, byte[] dataKey, CancellationToken cancellationToken)
Parameters
keyIdstringThe identifier of the wrapping key held by this provider.
versionintThe version of the wrapping key to use.
dataKeybyte[]The plaintext data encryption key to wrap. The caller retains ownership and is responsible for clearing it; implementations MUST NOT retain a reference beyond the call.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<WrappedDataKey>
The wrapped key, suitable for persistence alongside the ciphertext it protects.
Exceptions
- ArgumentNullException
Thrown when
keyIdordataKeyis null.- ArgumentException
Thrown when
keyIdis empty ordataKeyis empty.- EncryptionException
Thrown when the provider cannot complete the wrap.