Class EncryptedData
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Represents encrypted data with associated metadata required for decryption.
public sealed record EncryptedData : IEquatable<EncryptedData>
- Inheritance
-
EncryptedData
- Implements
- Inherited Members
Remarks
Encrypted data includes key identification and algorithm info to support key rotation and future algorithm migration.
Fields
CurrentFormatVersion
The envelope layout this version of the framework writes.
public const int CurrentFormatVersion = 2
Field Value
Remarks
Raised to 2 when the key generation became part of the envelope and of the authenticated associated data. A payload written before that carries no generation, so the material behind it cannot be identified and a destroyed subject cannot be distinguished from a live one — which is why such a payload is refused rather than read.
Properties
Algorithm
Gets the encryption algorithm used.
public required EncryptionAlgorithm Algorithm { get; init; }
Property Value
AuthTag
Gets the authentication tag for authenticated encryption modes (GCM, Poly1305). Null for non-authenticated modes.
public byte[]? AuthTag { get; init; }
Property Value
- byte[]
Ciphertext
Gets the encrypted ciphertext bytes.
public required byte[] Ciphertext { get; init; }
Property Value
- byte[]
EncryptedAt
Gets the timestamp when this data was encrypted.
public DateTimeOffset EncryptedAt { get; init; }
Property Value
FormatVersion
Gets the envelope layout this payload was written with.
public int FormatVersion { get; init; }
Property Value
Remarks
Declared rather than inferred, so a payload written by an unsupported layout is REFUSED by name instead of being attempted and failing its authentication tag — which a reader would reasonably mistake for corrupted data. A reader that does not recognise this value must refuse the payload rather than guess at its shape.
Iv
Gets the initialization vector (IV) or nonce used for encryption.
public required byte[] Iv { get; init; }
Property Value
- byte[]
KeyGeneration
Gets the identifier of the key GENERATION that produced this payload.
public string? KeyGeneration { get; init; }
Property Value
Remarks
This is the durable identity of the material, and it is what makes an erased subject stay erased. A key handle is derived from the data subject, so it is stable and therefore RE-OCCUPIABLE: destroy a subject's key and the next ordinary write for that subject provisions a new one at the same handle, with the version ordinal starting again at 1. The handle and the ordinal together then designate both the destroyed material and the live material, so a reader of an older payload cannot tell that the key it names is gone — it resolves the live generation instead, and the decryption fails its authentication tag as though the payload were corrupt.
A generation identifier is minted when the material is provisioned and never reused, so the question "is the material behind this payload destroyed?" has one answer that cannot be changed by anything provisioned afterwards. It is bound into the authenticated associated data, so a payload cannot be re-attributed to a different generation without failing to authenticate.
Not secret, and not an ordering. It is an opaque identity: compare it for equality and nothing else.
KeyId
Gets the identifier of the key used for encryption.
public required string KeyId { get; init; }
Property Value
KeyVersion
Gets the version of the key used for encryption.
public required int KeyVersion { get; init; }
Property Value
Remarks
Ordering and display, never identity. A version number orders the generations of a key and names one for a human; it does not designate key material. KeyGeneration does that, because an ordinal restarts at 1 when a handle is re-provisioned and therefore designates two different pieces of material at different times.
MagicBytes
Magic bytes that identify data as encrypted by this framework.
public static ReadOnlySpan<byte> MagicBytes { get; }
Property Value
Remarks
Encrypted fields are identified by these magic bytes at the start of the serialized data. Format: 0x45 0x58 0x43 0x52 ("EXCR" for Excalibur Encrypted)
TenantId
Gets the optional tenant identifier for multi-tenant isolation.
public string? TenantId { get; init; }
Property Value
WrappedKey
Gets the data encryption key for this payload, wrapped by the key service identified by KeyId and KeyVersion. Null when the payload was encrypted directly with key material rather than under an envelope.
public WrappedDataKey? WrappedKey { get; init; }
Property Value
- WrappedDataKey
The wrapped data encryption key, or null when Ciphertext was encrypted directly under the identified key.
Remarks
Envelope encryption is the path a cloud KMS or HSM can actually serve, because it never requires the key service to export key bytes. The payload is encrypted locally with a single-use data encryption key, and only that key is handed to the key service to be wrapped.
This property records which of the two schemes produced the payload, so a reader selects the correct one from the data itself rather than from how it happens to be configured at read time. Data written under either scheme therefore remains readable after the configuration changes.
Methods
IsFieldEncrypted(byte[]?)
Checks if the provided byte array appears to be encrypted by this framework.
public static bool IsFieldEncrypted(byte[]? data)
Parameters
databyte[]The data to check.
Returns
IsFieldEncrypted(ReadOnlySpan<byte>)
Checks if the provided data appears to be encrypted by this framework.
public static bool IsFieldEncrypted(ReadOnlySpan<byte> data)
Parameters
dataReadOnlySpan<byte>The data to check.
Returns
Remarks
This method uses magic byte detection to determine if data is encrypted. This is a heuristic check - false positives are possible if unencrypted data happens to start with the same bytes.
For performance, this method uses Span<T> to avoid allocations.
TryParse(ReadOnlySpan<byte>, out EncryptedData?)
Reads a stored envelope back into an EncryptedData, without decrypting it.
public static bool TryParse(ReadOnlySpan<byte> framed, out EncryptedData? envelope)
Parameters
framedReadOnlySpan<byte>The stored envelope bytes: the MagicBytes-prefixed form that TryReadEnvelope(PropertyInfo, object, out byte[]?) yields for an annotated property.
envelopeEncryptedDataThe parsed envelope when this method returns true.
Returns
Remarks
This is what makes the crypto-shredding guarantee checkable from outside the framework. That guarantee is stated in terms of KeyGeneration -- a destruction ledger holds a row for the generation a field's envelope names -- so a reader that cannot recover the generation from the stored bytes cannot verify, audit or report an erasure except by attempting a decrypt and inferring the answer from whether it succeeded. Parsing needs no key, no tenant and no configuration, so the question can be asked of stored data alone, which is the form an audit takes.
No exception on any input, following TryParse(string, out int). Bytes that do
not carry MagicBytes, that are truncated, or whose body is not a complete envelope all
return false and leave envelope null. A stored
value is read from a column the caller does not necessarily control, so malformed data is an expected
condition rather than a fault.
Parsing is not validation of the ciphertext. A true result says the envelope's metadata was readable. Whether the payload still decrypts depends on whether the generation it names survives, which is the question a destruction ledger answers -- and answering it is the reason to parse.