Is your feature request related to a problem? Please describe.
at_java's AtKeys models a keyfile as seven flat base64 Strings. Dart's at_auth
#2047 replaced that with a versioned keys[] document of self-describing key
material — keyId, keyPartType, keyAlgorithmType, bytes, operations,
createdAt, status. at_java cannot represent it, and the two SDKs' keyfiles are
currently mutually unreadable: at_java writes "version" as a JSON string where
Dart's parser requires an int, and Dart's "keys" array cannot bind into at_java's
Map<String,String>.
Describe the solution you'd like
Port the Dart implementation as follows...
| Dart class |
Dart field |
Dart type (known-values class) |
JSON member |
Java type |
Java field |
AtKeys |
atsign |
Atsign? |
atsign |
AtSign |
atSign |
|
_materialsByKeyId |
Map<String, Map<String, AtKeysMaterial>> |
keys |
Map<KeyId, Map<CryptographicMaterial.Role, CryptographicMaterial>> |
materials |
AtKeysMaterial |
|
|
keys[].keyParts[] |
CryptographicMaterial |
|
|
keyId |
String |
keys[].keyId |
KeyId |
keyId |
|
enrollmentId |
String? |
keys[].enrollmentId |
EnrollmentId |
enrollmentId |
|
keyPartType |
String (CryptographicKeyType) |
keyPartType |
CryptographicMaterial.Role |
role |
|
keyAlgorithmType |
String (KeyAlgorithmType) |
keyAlgorithmType |
CryptographicMaterial.Algorithm |
algorithm |
|
operations |
List<String> |
operations |
List<CryptographicMaterial.Operation> |
operations |
|
bytes |
AtBytes |
bytes |
byte[] |
bytes |
|
createdAt |
DateTime |
createdAt |
OffsetDateTime |
createdAt |
|
status |
KeyPartStatus |
status |
CryptographicMaterial.Status |
status |
Implement version specific JSON encode/decode such that atKeys JSON written by current and previous version of Dart can be loaded.
The legacy fields in AtKeys will be removed. Deprecated getters will be added to fix the current code and then ultimately be removed once CryptoProvider is ported.
Describe alternatives you've considered
Port like-for-like.
Additional context
Open questions for the team
-
CryptographicMaterial or KeyingMaterial? The latter is the actual term of
art — NIST SP 800-57 defines "keying material", RFC 5869 uses "input keying
material" (IKM). "Cryptographic material" is common informally (AWS KMS, Vault)
but isn't a standards term. This is the type everything else nests inside, so
worth settling before code.
-
Status or State? NIST SP 800-57 §7 defines a key state machine
(pre-activation, active, suspended, deactivated, compromised, destroyed) and
active is literally a NIST state. Against: our retired/dead are not NIST's
deactivated/destroyed, and the wire field is status — so State would claim
an alignment the values don't honour.
-
Do we need to support Dart's AtKeys.metadata passthrough? Dart parks every
unrecognised top-level keyfile key there and writes it back flat. at_java has
never modelled it, so the default is not to add it — but then at_java drops
those keys on save.
-
What is the known vocabulary for operations? Dart has no known-values class
for it, and the only values anywhere in its tree are sign and decrypt, both in
tests — so Operation's known set has to be agreed rather than ported. Seed it
from JWK key_ops (sign/verify/encrypt/decrypt/wrapKey/unwrapKey/
deriveKey/deriveBits), or from just those two and let it grow?
Is your feature request related to a problem? Please describe.
at_java's AtKeys models a keyfile as seven flat base64 Strings. Dart's at_auth
#2047 replaced that with a versioned keys[] document of self-describing key
material — keyId, keyPartType, keyAlgorithmType, bytes, operations,
createdAt, status. at_java cannot represent it, and the two SDKs' keyfiles are
currently mutually unreadable: at_java writes "version" as a JSON string where
Dart's parser requires an int, and Dart's "keys" array cannot bind into at_java's
Map<String,String>.
Describe the solution you'd like
Port the Dart implementation as follows...
AtKeysatsignAtsign?atsignAtSignatSign_materialsByKeyIdMap<String, Map<String, AtKeysMaterial>>keysMap<KeyId, Map<CryptographicMaterial.Role, CryptographicMaterial>>materialsAtKeysMaterialkeys[].keyParts[]CryptographicMaterialkeyIdStringkeys[].keyIdKeyIdkeyIdenrollmentIdString?keys[].enrollmentIdEnrollmentIdenrollmentIdkeyPartTypeString(CryptographicKeyType)keyPartTypeCryptographicMaterial.RolerolekeyAlgorithmTypeString(KeyAlgorithmType)keyAlgorithmTypeCryptographicMaterial.AlgorithmalgorithmoperationsList<String>operationsList<CryptographicMaterial.Operation>operationsbytesAtBytesbytesbyte[]bytescreatedAtDateTimecreatedAtOffsetDateTimecreatedAtstatusKeyPartStatusstatusCryptographicMaterial.StatusstatusImplement version specific JSON encode/decode such that atKeys JSON written by current and previous version of Dart can be loaded.
The legacy fields in AtKeys will be removed. Deprecated getters will be added to fix the current code and then ultimately be removed once CryptoProvider is ported.
Describe alternatives you've considered
Port like-for-like.
Additional context
Open questions for the team
CryptographicMaterialorKeyingMaterial? The latter is the actual term ofart — NIST SP 800-57 defines "keying material", RFC 5869 uses "input keying
material" (IKM). "Cryptographic material" is common informally (AWS KMS, Vault)
but isn't a standards term. This is the type everything else nests inside, so
worth settling before code.
StatusorState? NIST SP 800-57 §7 defines a key state machine(pre-activation, active, suspended, deactivated, compromised, destroyed) and
activeis literally a NIST state. Against: ourretired/deadare not NIST'sdeactivated/destroyed, and the wire field isstatus— soStatewould claiman alignment the values don't honour.
Do we need to support Dart's
AtKeys.metadatapassthrough? Dart parks everyunrecognised top-level keyfile key there and writes it back flat. at_java has
never modelled it, so the default is not to add it — but then at_java drops
those keys on save.
What is the known vocabulary for
operations? Dart has no known-values classfor it, and the only values anywhere in its tree are
signanddecrypt, both intests — so
Operation's known set has to be agreed rather than ported. Seed itfrom JWK
key_ops(sign/verify/encrypt/decrypt/wrapKey/unwrapKey/deriveKey/deriveBits), or from just those two and let it grow?