Table of Contents

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

keyId string

The identifier of the wrapping key held by this provider.

version int

The version of the wrapping key that produced wrappedKey.

wrappedKey WrappedDataKey

The wrapped key to unwrap.

cancellationToken CancellationToken

A 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 keyId or wrappedKey is 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

keyId string

The identifier of the wrapping key held by this provider.

version int

The version of the wrapping key to use.

dataKey byte[]

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.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<WrappedDataKey>

The wrapped key, suitable for persistence alongside the ciphertext it protects.

Exceptions

ArgumentNullException

Thrown when keyId or dataKey is null.

ArgumentException

Thrown when keyId is empty or dataKey is empty.

EncryptionException

Thrown when the provider cannot complete the wrap.