Class KeyMetadata
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Represents metadata about an encryption key without exposing key material.
public sealed record KeyMetadata : IEquatable<KeyMetadata>
- Inheritance
-
KeyMetadata
- Implements
- Inherited Members
Remarks
Key metadata includes version, status, and rotation information for audit and compliance purposes.
Properties
Algorithm
Gets the encryption algorithm this key is used with.
public required EncryptionAlgorithm Algorithm { get; init; }
Property Value
CreatedAt
Gets the instant the backend reports this key version was created, or null when it reports none.
public required DateTimeOffset? CreatedAt { get; init; }
Property Value
- DateTimeOffset?
The creation instant of the version this metadata describes, or null when the key-management backend does not supply one.
Remarks
null means NOT KNOWN, and it is never a substitute for one. A provider that cannot learn the instant reports null; it must never stamp its own clock, and must never use a sentinel such as MinValue. Both are fabrications a caller cannot tell apart from a measurement, and a fabricated "now" is worse than no value at all: it sorts the oldest material as the newest, so stale data reads as current and is never re-encrypted.
Callers treat an unknown instant as STALE, never as recent. Where this field decides whether a key is due for rotation or has exceeded a maximum age, null counts as due and as exceeded. Where it orders keys, null sorts oldest. That direction costs extra work and never costs safety, which is the only acceptable way to resolve an absence on a path like this.
It describes the version this metadata is about, not the first version of the handle. Two versions of one key may therefore report different instants, and a caller may use them to order those versions only when neither is null.
ExpiresAt
Gets the timestamp when this key expires and should no longer be used for encryption. Null if the key does not expire.
public DateTimeOffset? ExpiresAt { get; init; }
Property Value
Generation
Gets the identifier of this key's current GENERATION — the material provisioned at this handle — or null when the provider cannot identify one.
public KeyGeneration? Generation { get; init; }
Property Value
Remarks
Minted when material is provisioned, never reused, and never derived from the handle. A handle is derived from the thing it protects, so it is stable and re-occupiable: destroying a key and provisioning another at the same handle restarts Version at 1, and handle-plus-version then designates two different pieces of material at two different times. A generation identifier is what lets a reader of an older payload establish that the material it was written under is gone.
Null is a real answer and it is not benign. A provider that cannot identify a generation cannot support a crypto-shred read path, because a destroyed key and a re-provisioned one are indistinguishable through it. Callers that depend on the distinction refuse rather than assume -- and the nullability is deliberate for exactly that case: a handle provisioned outside this framework has no lineage identity we can honestly state, and inventing one on read would give material destroyed elsewhere a fresh identifier and present it as live.
A KeyGeneration rather than a string, because the ledger keys on it. A string-typed generation accepts an ordinal, a backend version identifier or a value derived from the subject, each of which can collide across subjects -- and a collision under a generation-keyed destruction ledger reports one subject's live data as erased by another's erasure. The type admits only a CSPRNG mint or a 32-hexadecimal-character parse, so that value cannot be constructed here at all.
IsFipsCompliant
Gets a value indicating whether this key can be used for FIPS 140-2 compliant operations.
public bool IsFipsCompliant { get; init; }
Property Value
KeyId
Gets the unique identifier for this key.
public required string KeyId { get; init; }
Property Value
LastRotatedAt
Gets the timestamp when this key was last rotated. Null if the key has never been rotated.
public DateTimeOffset? LastRotatedAt { get; init; }
Property Value
Purpose
Gets the purpose or scope of this key (e.g., "field-encryption", "backup").
public string? Purpose { get; init; }
Property Value
Status
Gets the current lifecycle status of the key.
public required KeyStatus Status { get; init; }
Property Value
Version
Gets the version of the key (incremented on rotation).
public required int Version { get; init; }