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
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
otherKeyGenerationAn object to compare with this object.
Returns
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
objobjectThe object to compare with the current instance.
Returns
- bool
true if
objand 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
valuestringThe 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
valueis null.- ArgumentException
Thrown when
valueis 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
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
valuestringThe candidate identifier; may be null.
generationKeyGenerationThe parsed generation, or default when parsing failed.
Returns
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
leftKeyGenerationThe first generation.
rightKeyGenerationThe second generation.
Returns
operator !=(KeyGeneration, KeyGeneration)
Reports whether two generations name different material.
public static bool operator !=(KeyGeneration left, KeyGeneration right)
Parameters
leftKeyGenerationThe first generation.
rightKeyGenerationThe second generation.