Table of Contents

Struct KeyGeneration

Namespace
Excalibur.Compliance
Assembly
Excalibur.Compliance.Abstractions.dll

The identifier of one provisioning LINEAGE of key material: 128 bits, minted by this framework, and the value a destruction record is keyed on.

public readonly struct KeyGeneration : IEquatable<KeyGeneration>
Implements
Inherited Members

Remarks

Why this is a type and not a string. The destruction ledger is keyed on the generation alone, so a weak generation is not a local problem: two subjects whose generations collide share one destruction record, and erasing the first reports the second's live personal data as lawfully erased. A string parameter accepts an ordinal, a backend version identifier, a key ARN, or a value derived from the subject identifier -- all of which collide or are guessable, and none of which any compiler would question. The only ways to obtain a KeyGeneration are Mint(), which uses a CSPRNG, and Parse(string), which rejects anything that is not 32 hexadecimal characters. A weak generation stops being discouraged and becomes unrepresentable.

What this type CANNOT enforce, stated plainly because it is a consumer obligation. It constrains SHAPE, not ENTROPY. A provider may hash a subject identifier into 32 hexadecimal characters and Parse(string) will accept it, because the result is indistinguishable from a mint. Such a value collides across subjects exactly as a weak one does, with the consequence above. A provider implementing IKeyManagementProvider MUST obtain its generations from Mint(), or from a CSPRNG of its own -- never derived from the handle, the subject, a counter, or a clock.

It deliberately stops short of the wire. The envelope and the encryption context carry the generation as a string, and that is not an oversight: the value is bound into the AES-GCM associated data and is persisted inside serialized envelopes, so changing its serialized form would alter what already-written payloads authenticate against and make them unreadable. This type lives at the provider, metadata and ledger boundary; ToString() produces the exact characters that travel and are stored, so the round trip is byte-identical.

Opaque: compare for equality, never for order, and do not read the characters for meaning.

Properties

HasValue

Gets a value indicating whether this instance carries an identifier.

public bool HasValue { get; }

Property Value

bool

Remarks

A default instance carries none. It exists because a struct cannot forbid default, so this type cannot make "unset" unrepresentable -- only distinguishable, which is what this reports. Prefer Nullable<T> at a boundary that genuinely has no generation, so the absence sits in the signature rather than in a flag a caller may forget to read.

Methods

Equals(KeyGeneration)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(KeyGeneration other)

Parameters

other KeyGeneration

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Remarks

Ordinal and case-sensitive. Two generations differing only in case are different records, because the ledger compares the stored characters; collapsing case here while the database does not would report a destruction against material that was never destroyed.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

Mint()

Mints a new generation for newly provisioned material.

public static KeyGeneration Mint()

Returns

KeyGeneration

A generation no other provisioning will hold.

Remarks

128 bits from RandomNumberGenerator. The identifier is not secret -- it travels in cleartext on every envelope -- but it must be unguessable and unique by construction, because it is what the destruction ledger is keyed on. A Guid or Random is forbidden here: neither is a CSPRNG, and key-adjacent material does not get the convenient option.

Parse(string)

Parses a generation that was previously minted, as read back from a backend, an envelope, or a record.

public static KeyGeneration Parse(string value)

Parameters

value string

The 32-character hexadecimal identifier.

Returns

KeyGeneration

The parsed generation.

Remarks

Throwing rather than substituting is the point. A value that is not a generation cannot be turned into one, and the alternatives -- accepting it, or quietly yielding an unset instance -- would both put a value nothing minted into the position the ledger keys on.

Exceptions

ArgumentNullException

Thrown when value is null.

ArgumentException

Thrown when value is not exactly 32 hexadecimal characters.

ToString()

Returns the characters that travel on an envelope and are stored in a destruction record.

public override string ToString()

Returns

string

The 32-character hexadecimal identifier, or an empty string for a default instance.

Remarks

Byte-identical to what Parse(string) accepted or Mint() produced. The serialized form is part of the contract: it is bound into the AES-GCM associated data, so a change to it would make already-written payloads fail to authenticate.

TryParse(string?, out KeyGeneration)

Attempts to parse a generation, without throwing.

public static bool TryParse(string? value, out KeyGeneration generation)

Parameters

value string

The candidate identifier; may be null.

generation KeyGeneration

The parsed generation, or default when parsing failed.

Returns

bool

true when value is a well-formed generation.

Remarks

For a provider reading a generation back from a backend that may not carry one. A false means the material has no identity this framework can state, which a caller reports as absent -- never as a value it invented.

Operators

operator ==(KeyGeneration, KeyGeneration)

Reports whether two generations name the same material.

public static bool operator ==(KeyGeneration left, KeyGeneration right)

Parameters

left KeyGeneration

The first generation.

right KeyGeneration

The second generation.

Returns

bool

true when both name the same material.

operator !=(KeyGeneration, KeyGeneration)

Reports whether two generations name different material.

public static bool operator !=(KeyGeneration left, KeyGeneration right)

Parameters

left KeyGeneration

The first generation.

right KeyGeneration

The second generation.

Returns

bool

true when they name different material.