Skip to content

Port Dart's typed atKeys key material to at_java, with Dart-interoperable JSON #425

Description

@akafredperry

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

  1. 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.

  2. 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.

  3. 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.

  4. 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?

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions