Table of Contents

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

EncryptionAlgorithm

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

DateTimeOffset?

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

KeyGeneration?

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

bool

KeyId

Gets the unique identifier for this key.

public required string KeyId { get; init; }

Property Value

string

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

DateTimeOffset?

Purpose

Gets the purpose or scope of this key (e.g., "field-encryption", "backup").

public string? Purpose { get; init; }

Property Value

string

Status

Gets the current lifecycle status of the key.

public required KeyStatus Status { get; init; }

Property Value

KeyStatus

Version

Gets the version of the key (incremented on rotation).

public required int Version { get; init; }

Property Value

int