AtKeys class
The in-memory model of an atsign's cryptographic keys.
An AtKeys instance always holds plaintext key material — every
at-rest concern (the passphrase envelope, self-encryption of the legacy
fields) lives in FileAtKeysIo, not here.
Typed key material (CryptographicMaterial) sits in one of two containers, and which one is a statement about who the material belongs to:
- an enrollment's keys — its authentication keypair, its signing keys, its key package — reached with getKey / keysForKeyId / keysForEnrollment and retired with retireKey, all of which take the enrollment beside the keyId;
- the atSign's own keys — the signing root, an nskey private — reached with getAtSignKey / atSignKeysForKeyId and retired with retireAtSignKey.
⚠️ Identity is (enrollment, keyId), not keyId alone. Two enrollments
may each hold auth:mldsa65:1. That is why the lookups are split rather
than defaulted: a caller reaching for atSign-scope material with a bare
keyId would otherwise compile while searching an enrollment, and find
nothing.
addKey is not split, because a material states its own owner: its
enrollmentId routes it, and a null one means the atSign's container.
Constructors
-
AtKeys({Atsign? atsign, List<
CryptographicMaterial> keysList = const []}) -
AtKeys.fromJson(Map<
String, dynamic> json) -
Decodes the typed-keys document shape (
version,atsign,atsignKeys,enrollments, plus legacy fields flat at the top level). Json without aversionfield is accepted as the legacy flat shape (delegates to_fromLegacyJson); aversionother than supportedVersion throws AtKeysUnsupportedVersionException. Each container's entries are parsed and validated by parseAtKeysDocument, which returns the flattened CryptographicMaterials that are actually stored.factory - AtKeys.legacy({String? apkamPublicKey, String? apkamPrivateKey, String? apkamSymmetricKey, String? encryptionPublicKey, String? encryptionPrivateKey, String? selfEncryptionKey, String? enrollmentId})
-
A legacy-shaped document holding what fileLegacyMaterial files and
nothing typed: the shape of every keyfile written before the typed
section existed, and of a demo atSign's credentials.
factory
Properties
- apkamPrivateKey ↔ AtBytes?
-
getter/setter pair
- apkamPublicKey ↔ AtBytes?
-
getter/setter pair
- apkamSymmetricKey ↔ AtBytes?
-
getter/setter pair
- atsign ↔ Atsign?
-
getter/setter pair
-
atSignKeys
→ Iterable<
CryptographicMaterial> -
The atSign's own materials — the signing root, nskey privates — with no
enrollment between them and the document.
no setter
-
authenticatableEnrollmentIds
→ Iterable<
String> -
Every enrollment holding active authentication material — the ones this
keyfile could authenticate as.
no setter
- defaultEncryptionPrivateKey ↔ AtBytes?
-
getter/setter pair
- defaultEncryptionPublicKey ↔ AtBytes?
-
getter/setter pair
- defaultSelfEncryptionKey ↔ AtBytes?
-
getter/setter pair
- encryptionKeyPair → RsaKeyPair?
-
The atSign's RSA encryption keypair: the key a legacy shared key is
wrapped to, and whose private half signs public data.
no setter
- enrollmentId ↔ String?
-
getter/setter pair
-
enrollmentIds
→ Iterable<
String> -
Every enrollment this keyfile holds. Writers emit one; the reader
tolerates several so that emitting a second never has to break a build
that predates it.
no setter
- enrollmentSymmetricKey → AESKey?
-
The APKAM symmetric key of the enrollment the flat fields carry, which
unwraps what an approval released to it; null for a keyfile that
predates enrollments or holds none.
no setter
- hashCode → int
-
The hash code for this object.
no setteroverride
- holdsAuthenticationMaterial → bool
-
Whether this document holds any authentication material: typed, or the
flat APKAM keypair. A document holding none authenticates as nothing,
whatever its flat enrollmentId says.
no setter
-
keys
→ Iterable<
CryptographicMaterial> -
Every typed material in the document, both containers, in no particular
order.
no setter
-
metadata
↔ Map<
String, dynamic> -
A legacy keyfile's entries outside the flat key schema: the atSign under
atsignorname, and the self-encryption key stored under the atSign itself. The typed document has no equivalent, so a read and write cycle preserves them only here.getter/setter pair -
pendingEnrollmentIds
→ Iterable<
String> -
Every enrollment whose material is filed as
CryptographicMaterialStatus.pending: submitted, and not yet approved.
The ones activatePending or discardEnrollment will settle.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- selfEncryptionKey → AESKey?
-
The atSign's self-encryption key, which opens the records it wrote for
itself.
no setter
- storedEnrollmentId → String?
-
The enrollment id the flat fields carry, exactly as stored: null for a
keyfile from before enrollments, where enrollmentToAuthenticateAs
answers
primary, and never a typed enrollment's id.no setter
Methods
-
activatePending(
String enrollmentId) → void -
Moves every CryptographicMaterialStatus.pending material of
enrollmentIdto active: the approval of an enrollment whose keypair was filed at submission. -
addKey(
CryptographicMaterial material) → void -
Files
materialin the container its ownenrollmentIdnames — that enrollment's when it has one, the atSign's when it is null. -
adoptMaterials(
Iterable< CryptographicMaterial> materials, {required String enrollmentId}) → void -
Adopts
materials— what an enrollment request's metadataBuilder filed into the construction keys it was handed — tagged with the enrollment id they now belong to. -
atSignKeysForKeyId(
String keyId) → Iterable< CryptographicMaterial> -
Every atSign-scope material sharing
keyId. -
authenticationAlgorithmFor(
String? enrollmentId) → SigningAlgoType? -
The algorithm authenticationKeyPairFor signs
enrollmentId's PKAM with, without its keypair. -
authenticationKeyPairFor(
String? enrollmentId) → ({SigningAlgoType algorithm, String privateKey, String publicKey})? -
The authentication keypair
enrollmentIdproves possession of, and the algorithm that signs with it: the one place either half of an APKAM keypair is resolved. Both halves are base64 of the raw key bytes. -
discardEnrollment(
String enrollmentId) → void -
Removes
enrollmentIdfrom the keyfile: its snapshot and every material filed under it. -
enrollmentInfo(
String enrollmentId) → AtKeysEnrollment? -
What this keyfile records about
enrollmentIdbesides its keys, or null when it holds no such enrollment. -
enrollmentToAuthenticateAs(
) → String -
The enrollment this keyfile authenticates as: the one holding active
typed authentication material, else the flat stored enrollmentId, else
EnrollmentConstants.primaryEnrollmentIdfor a keyfile that predates enrollments. -
fileApkamMaterial(
{required String enrollmentId, required CryptographicMaterialAlgorithm algorithm, required String publicKey, required String privateKey}) → void -
Files a freshly minted APKAM keypair as an enrollment's
authentication material, under the keyId
auth:<algorithm>:<generation>. -
fileLegacyMaterial(
{String? apkamPublicKey, String? apkamPrivateKey, String? apkamSymmetricKey, String? encryptionPublicKey, String? encryptionPrivateKey, String? selfEncryptionKey, String? enrollmentId}) → void - Files what a LEGACY keyfile carries flat: the atSign's RSA encryption keypair and self-encryption key, and the APKAM keypair, symmetric key and id of the one enrollment such a document holds. A null argument leaves its field as it was.
-
fileSigningMaterial(
{required String enrollmentId, required CryptographicMaterialAlgorithm algorithm, required String publicKey, required String privateKey}) → void -
Files a signing keypair for
enrollmentIdundersign:<algorithm>:<generation>. -
getAtSignKey(
String keyId, CryptographicMaterialRole type) → CryptographicMaterial? -
Looks up one of the atSign's own materials by
(keyId, role). -
getKey(
String enrollmentId, String keyId, CryptographicMaterialRole type) → CryptographicMaterial? -
Looks up one of
enrollmentId's materials by(keyId, role)—typeis a CryptographicMaterialRole token. -
keysForEnrollment(
String enrollmentId) → Iterable< CryptographicMaterial> -
Returns every material tagged with
enrollmentId. -
keysForKeyId(
String enrollmentId, String keyId) → Iterable< CryptographicMaterial> -
Every material of
enrollmentIdsharingkeyId— e.g. the public+private halves of one keypair. -
nextAtSignGeneration(
String role, CryptographicMaterialAlgorithm algorithm) → int -
The generation an atSign-scope keypair of
roleandalgorithmshould be filed under next — one past the highest already there, or 1. -
nextAuthenticationGeneration(
String enrollmentId, CryptographicMaterialAlgorithm algorithm) → int -
The generation number fileApkamMaterial will use next for
enrollmentId'salgorithm— one past the highest already filed, or 1. -
nextSigningGeneration(
String enrollmentId, CryptographicMaterialAlgorithm algorithm) → int -
The generation fileSigningMaterial will use next for
enrollmentId'salgorithm— one past the highest already filed, or 1. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
recordEnrollmentSnapshot(
String enrollmentId, {Map< String, String> ? namespaces, String? appName, String? deviceName}) → void -
Records the enrollment record's
namespaces/appName/deviceNameagainstenrollmentId, creating the enrollment slot if this is the first thing filed for it. -
replaceKey(
String enrollmentId, String keyId, Iterable< CryptographicMaterial> replacements, {CryptographicMaterialStatus to = CryptographicMaterialStatus.retired}) → void -
Retires
keyIdand filesreplacementsin one call — a key rotation, as a single operation rather than two the caller has to sequence. -
resolveAuthenticatingEnrollment(
) → String? - The one enrollment this keyfile authenticates as, for a caller that has no id of its own to supply — a cold start holding nothing but the file.
-
retireAtSignKey(
String keyId, {CryptographicMaterialStatus to = CryptographicMaterialStatus.retired}) → void - retireKey for the atSign's own material — the signing root, an nskey private.
-
retireKey(
String enrollmentId, String keyId, {CryptographicMaterialStatus to = CryptographicMaterialStatus.retired}) → void -
Marks every material of
enrollmentId'skeyIdasto(CryptographicMaterialStatus.retired by default). Key material is never removed — retired/dead bytes are still needed to decrypt data they protected — so this is the delete operation. Status only moves forward (pending → active → retired → dead): a same-status call is a no-op and a backward transition throws, as does an unknownkeyIdorto: CryptographicMaterialStatus.active, which is activatePending's move alone. -
retireSigningKeys(
String enrollmentId, CryptographicMaterialAlgorithm algorithm, {CryptographicMaterialStatus to = CryptographicMaterialStatus.retired}) → List< String> -
Retires every active signing keypair
enrollmentIdholds foralgorithm, returning the keyIds it moved — empty when it holds none, which is the ordinary case on a client whose in-use set has not changed. -
signingAlgorithmForEnrollment(
String enrollmentId) → SigningAlgoType? -
The algorithm of
enrollmentId's active authentication material — what PKAM must sign with — or null when the enrollment has no typed authentication material this build recognises (a legacy flat-fields enrollment reports null: its RSA keypair lives in the flat fields, not the typed section). -
signingKeysFor(
String enrollmentId) → List< ({SigningAlgoType algorithm, String privateKey, String publicKey})> -
Every active signing keypair
enrollmentIdholds, strongest algorithm first — one entry per algorithm, which is what a multi-signature writer iterates and what a_apskarray is composed from. -
toJson(
) → Map< String, dynamic> -
Encodes this AtKeys to the typed-keys document shape. Legacy fields
merge flatly into the top level alongside
version/atsign/atsignKeys/enrollments— upgrading a legacy file is additive, not a format swap. Falls back to the legacy flat shape (see_toLegacyJson) when there's no atsign and no typed key material. -
toString(
) → String -
A string representation of this object.
inherited
-
unfileLegacyEnrollment(
String enrollmentId) → void -
Undoes what fileLegacyMaterial filed for
enrollmentId, once that enrollment is gone: the flat enrollment id when it namesenrollmentId, and then the flat APKAM symmetric key too if the document holds no enrollment and no authentication material. What another enrollment filed is left as it is. -
withdrawnSigningKeysFor(
String enrollmentId) → List< ({SigningAlgoType algorithm, String publicKey, CryptographicMaterialStatus status})> -
The public half of every signing keypair
enrollmentIdhas withdrawn from signing, strongest algorithm first, each with the status the keyfile gives it — the entries an_apskadvertisement carries alongside the active ones, so that envelopes signed before a key was withdrawn still verify.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
override
Static Methods
-
isRoleKeyId(
String keyId, String role) → bool -
Whether
keyIdnames a keypair ofrole—<role>:<algo>:<generation>exactly, the shape keyIdPrefix composes and every generation parse reads. -
keyIdPrefix(
String role, CryptographicMaterialAlgorithm algorithm) → String -
The keyId prefix a
role/algorithmpair is filed under —<role>:<algorithm>:, completed by a generation number.
Constants
- supportedVersion → const int