fix(keyring): make account backup and restore work for ML-DSA pairs

Before this, an exported Quantus account could not be imported by anything.
decodePair located its divider by trying the two secret lengths every curve
scheme uses, 64 then 32; an ML-DSA secret is 4032 or 4896 bytes, so neither
matched and restore threw "Invalid encoding divider found in body". That is a
data-durability bug rather than a convenience one, which is why it lands before
any build lets a user create an account.

decodePair now takes an optional secretLength. The caller passes it rather than
this function searching for the divider: searching would work almost always and
fail catastrophically when it did not, since PAIR_DIV is five bytes and a
4032-byte secret contains a false match about once in 270 million keys — and the
result would be a silently wrong key rather than an error. The public key is read
as the remainder, because its length also varies and the body ends there.

The harder half is ordering. createFromJson returns a *locked* pair and callers
read pair.address off it long before any password appears. Every other scheme
manages because the address is the public key; an ML-DSA account id is a one-way
Poseidon2 hash and the public key is inside the encrypted blob. So PairInfo gains
an optional accountId, carried as data and used for the address while locked,
which decodePkcs8 clears once the real key arrives.

It also checks them against each other, and that check is not paranoia. For the
curve schemes a JSON file with an edited `address` field cannot decode at all.
Here it decodes perfectly and yields a pair reporting an address its key does not
control — a user would see someone else's address in their own wallet and believe
they held it. Pinned by a test that tampers exactly that field.

One more silent-wrong-key path closed: decodePkcs8 decided "secret key or seed?"
by length, so a 4032-byte ML-DSA secret took the seed branch and was fed to keygen
as entropy, producing a valid and entirely wrong key. The type knows the answer,
so it is asked.

Refs quantus/common#3

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012uDUodEcRbBwNRi3UCmw8f
This commit is contained in:
rob thijssen
2026-09-15 08:50:56 +03:00
co-authored by Claude Opus 5
parent 2bffbc62bc
commit 506b77351c
5 changed files with 217 additions and 11 deletions
+16 -4
View File
@@ -5,7 +5,7 @@ import type { EncryptedJsonEncoding, Keypair, KeypairType } from '@polkadot/util
import type { KeyringInstance, KeyringOptions, KeyringPair, KeyringPair$Json, KeyringPair$Meta } from './types.js';
import { hexToU8a, isHex, stringToU8a } from '@polkadot/util';
import { base64Decode, decodeAddress, dilithiumPairFromSeed, ed25519PairFromSeed as ed25519FromSeed, encodeAddress, ethereumEncode, hdEthereum, keyExtractSuri, keyFromPath, mnemonicToLegacySeed, mnemonicToMiniSecret, secp256k1PairFromSeed as secp256k1FromSeed, sr25519PairFromSeed as sr25519FromSeed } from '@polkadot/util-crypto';
import { base64Decode, decodeAddress, dilithiumPairFromSeed, ed25519PairFromSeed as ed25519FromSeed, encodeAddress, ethereumEncode, hdEthereum, isDilithium, keyExtractSuri, keyFromPath, mnemonicToLegacySeed, mnemonicToMiniSecret, secp256k1PairFromSeed as secp256k1FromSeed, sr25519PairFromSeed as sr25519FromSeed } from '@polkadot/util-crypto';
import { createPair } from './pair/index.js';
import { DEV_PHRASE } from './defaults.js';
@@ -198,15 +198,27 @@ export class Keyring implements KeyringInstance {
throw new Error(`Unknown crypto type ${cryptoType}`);
}
// Here the address and publicKey are 32 bytes and isomorphic. This is why the address field needs to be the public key for ethereum type pairs
const publicKey = isHex(address)
// For the curve schemes the address and publicKey are 32 bytes and
// isomorphic, which is why the address field holds the public key for
// ethereum pairs and why this works at all.
const raw = isHex(address)
? hexToU8a(address)
: this.decodeAddress(address, ignoreChecksum);
const decoded = isHex(encoded)
? hexToU8a(encoded)
: base64Decode(encoded);
return createPair({ toSS58: this.encodeAddress, type: cryptoType as KeypairType }, { publicKey, secretKey: new Uint8Array() }, meta, decoded, encType);
// ML-DSA breaks the isomorphism: the account id is a one-way Poseidon2 hash
// and the 1952/2592-byte public key is inside `decoded`, which is encrypted
// and stays that way until someone supplies a password. So pass the account
// id as an account id rather than pretending it is a key — createPair uses
// it for the address while locked, and checks it against the real public key
// the moment `decodePkcs8` produces one.
const info = isDilithium(cryptoType as KeypairType)
? { accountId: raw, publicKey: new Uint8Array(), secretKey: new Uint8Array() }
: { publicKey: raw, secretKey: new Uint8Array() };
return createPair({ toSS58: this.encodeAddress, type: cryptoType as KeypairType }, info, meta, decoded, encType);
}
/**
+30 -1
View File
@@ -16,8 +16,20 @@ const SEED_OFFSET = PAIR_HDR.length;
* For divisor/headers, don't rely on the magic being static. These will
* change between generations, aka with the long-awaited 4th generation
* of the format. The external decode interface is the only way to use and decode these.
*
* `secretLength` exists for keys that are not 32 or 64 bytes. The body is
* `HDR ‖ secretKey ‖ DIV ‖ publicKey`, and upstream located the divider by
* trying the two lengths every curve scheme uses. An ML-DSA secret is 4032 or
* 4896 bytes, so neither offset matches and the decode throws "Invalid encoding
* divider found in body" — a stored account that cannot be read back.
*
* The caller passes the length rather than this function searching for the
* divider. Searching would work almost always and fail catastrophically when it
* did not: PAIR_DIV is five bytes, so a 4032-byte secret contains a false match
* about once in 270 million keys, and the result would be a silently wrong key
* rather than an error. The caller knows the type, so it knows the length.
**/
export function decodePair (passphrase?: string, encrypted?: Uint8Array | null, _encType?: EncryptedJsonEncoding | EncryptedJsonEncoding[]): { publicKey: Uint8Array; secretKey: Uint8Array } {
export function decodePair (passphrase?: string, encrypted?: Uint8Array | null, _encType?: EncryptedJsonEncoding | EncryptedJsonEncoding[], secretLength?: number): { publicKey: Uint8Array; secretKey: Uint8Array } {
const encType = Array.isArray(_encType) || _encType === undefined
? _encType
: [_encType];
@@ -29,6 +41,23 @@ export function decodePair (passphrase?: string, encrypted?: Uint8Array | null,
throw new Error('Invalid encoding header found in body');
}
// an explicitly-sized secret (ML-DSA); there is one offset and it either
// matches or the blob is not what the caller said it was
if (secretLength) {
const divOffset = SEED_OFFSET + secretLength;
if (!u8aEq(decrypted.subarray(divOffset, divOffset + PAIR_DIV.length), PAIR_DIV)) {
throw new Error('Invalid encoding divider found in body');
}
return {
// the public key is the remainder: its length varies by scheme and the
// body ends here, so there is nothing to read past it
publicKey: decrypted.subarray(divOffset + PAIR_DIV.length),
secretKey: decrypted.subarray(SEED_OFFSET, divOffset)
};
}
// setup for generation 3 format
let secretKey = decrypted.subarray(SEED_OFFSET, SEED_OFFSET + SEC_LENGTH);
let divOffset = SEED_OFFSET + SEC_LENGTH;
@@ -0,0 +1,114 @@
// Copyright 2017-2026 @polkadot/keyring authors & contributors
// SPDX-License-Identifier: Apache-2.0
/// <reference types="@polkadot/dev-test/globals.d.ts" />
import { contextForSpec } from '@quantus/crypto';
import { dilithiumVerify } from '@polkadot/util-crypto';
import { Keyring } from '../keyring.js';
// The address `quantus developer create-test-wallets` prints for crystal_alice.
const ALICE_ADDRESS = 'qzk1Nxai3dZD9Cn5kwGcgL6mKxsfxwqdis7kDQJ52aJS2vSn7';
const PASSWORD = 'not a good password';
const MESSAGE = new Uint8Array([0x6a, 0x73, 0x6f, 0x6e]);
describe('dilithium account JSON', (): void => {
const keyring = new Keyring({ ss58Format: 189, type: 'dilithium87' });
const context = contextForSpec(148);
const backup = (type: 'dilithium65' | 'dilithium87', fill = 0) => {
const pair = keyring.addFromSeed(new Uint8Array(32).fill(fill), { name: 'backed up' }, type);
return { json: pair.toJson(PASSWORD), original: pair };
};
// The whole point. Before this worked, an exported Quantus account could not be
// imported by anything — decodePair looked for its divider at one of two fixed
// offsets and an ML-DSA secret is at neither, so restore threw "Invalid
// encoding divider found in body". That is a data-durability bug, not a
// convenience one: it had to land before any build let a user create an account.
it('round-trips an ML-DSA-87 account', (): void => {
const { json, original } = backup('dilithium87');
const restored = keyring.createFromJson(json);
restored.decodePkcs8(PASSWORD);
expect(restored.address).toEqual(original.address);
expect(restored.publicKey).toEqual(original.publicKey);
expect(restored.isLocked).toEqual(false);
});
it('round-trips an ML-DSA-65 account', (): void => {
const { json, original } = backup('dilithium65', 5);
const restored = keyring.createFromJson(json);
restored.decodePkcs8(PASSWORD);
expect(restored.address).toEqual(original.address);
expect(restored.publicKey).toEqual(original.publicKey);
});
// A restored pair is locked, and callers read `pair.address` off it long before
// any password appears. For every other scheme that works because the address
// *is* the public key; here the key is still encrypted, so the account id has
// to be carried as data until decodePkcs8 supplies the real one.
it('reports the same address before and after unlock', (): void => {
const { json } = backup('dilithium87');
const restored = keyring.createFromJson(json);
expect(restored.isLocked).toEqual(true);
expect(restored.address).toEqual(ALICE_ADDRESS);
restored.decodePkcs8(PASSWORD);
expect(restored.address).toEqual(ALICE_ADDRESS);
});
it('restores a pair that can still sign', (): void => {
const { json, original } = backup('dilithium87');
const restored = keyring.createFromJson(json);
restored.decodePkcs8(PASSWORD);
const signature = restored.sign(MESSAGE, { context });
expect(dilithiumVerify(MESSAGE, signature, original.addressRaw, 'dilithium87', context)).toEqual(true);
});
it('fails cleanly on a wrong password', (): void => {
const { json } = backup('dilithium87');
const restored = keyring.createFromJson(json);
expect(() => restored.decodePkcs8('wrong')).toThrow();
// and must not have half-applied anything
expect(restored.isLocked).toEqual(true);
expect(restored.address).toEqual(ALICE_ADDRESS);
});
// For every other scheme a tampered `address` field cannot decode at all,
// because the address is the public key. Here it decodes perfectly and yields a
// pair reporting an address its key does not control — a user would see someone
// else's address in their own wallet and believe they held it.
it('rejects JSON whose address does not match its key', (): void => {
const { json } = backup('dilithium87');
const other = keyring.addFromSeed(new Uint8Array(32).fill(2), {}, 'dilithium87');
const tampered = { ...json, address: other.address };
const restored = keyring.createFromJson(tampered);
expect(restored.address).toEqual(other.address);
expect(() => restored.decodePkcs8(PASSWORD)).toThrow(/does not match the address/);
});
it('leaves sr25519 JSON round-tripping unchanged', (): void => {
const sr = new Keyring({ type: 'sr25519' });
const pair = sr.addFromUri('//Alice');
const restored = sr.createFromJson(pair.toJson(PASSWORD));
restored.decodePkcs8(PASSWORD);
expect(restored.address).toEqual(pair.address);
expect(restored.publicKey).toEqual(pair.publicKey);
});
});
+42 -6
View File
@@ -6,7 +6,7 @@ import type { KeyringPair, KeyringPair$Json, KeyringPair$Meta, SignOptions } fro
import type { PairInfo } from './types.js';
import { objectSpread, u8aConcat, u8aEmpty, u8aEq, u8aToHex, u8aToU8a } from '@polkadot/util';
import { blake2AsU8a, dilithiumAccountFromPublic, dilithiumPairFromSeed, dilithiumSign, ed25519PairFromSeed as ed25519FromSeed, ed25519Sign, ethereumEncode, isDilithium, keccakAsU8a, keyExtractPath, keyFromPath, secp256k1Compress, secp256k1Expand, secp256k1PairFromSeed as secp256k1FromSeed, secp256k1Sign, signatureVerify, sr25519PairFromSeed as sr25519FromSeed, sr25519Sign, sr25519VrfSign, sr25519VrfVerify } from '@polkadot/util-crypto';
import { blake2AsU8a, dilithiumAccountFromPublic, dilithiumPairFromSeed, dilithiumSign, dilithiumSizes, ed25519PairFromSeed as ed25519FromSeed, ed25519Sign, ethereumEncode, isDilithium, keccakAsU8a, keyExtractPath, keyFromPath, secp256k1Compress, secp256k1Expand, secp256k1PairFromSeed as secp256k1FromSeed, secp256k1Sign, signatureVerify, sr25519PairFromSeed as sr25519FromSeed, sr25519Sign, sr25519VrfSign, sr25519VrfVerify } from '@polkadot/util-crypto';
import { decodePair } from './decode.js';
import { encodePair } from './encode.js';
@@ -129,11 +129,21 @@ function vrfHash (proof: Uint8Array, context?: string | Uint8Array, extra?: stri
* an `encoded` property that is assigned with the encoded public key in hex format, and an `encoding`
* property that indicates whether the public key value of the `encoded` property is encoded or not.
*/
export function createPair ({ toSS58, type }: Setup, { publicKey, secretKey }: PairInfo, meta: KeyringPair$Meta = {}, encoded: Uint8Array | null = null, encTypes?: EncryptedJsonEncoding[]): KeyringPair {
export function createPair ({ toSS58, type }: Setup, { accountId, publicKey, secretKey }: PairInfo, meta: KeyringPair$Meta = {}, encoded: Uint8Array | null = null, encTypes?: EncryptedJsonEncoding[]): KeyringPair {
const decodePkcs8 = (passphrase?: string, userEncoded?: Uint8Array | null): void => {
const decoded = decodePair(passphrase, userEncoded || encoded, encTypes);
// ML-DSA secrets are 4032/4896 bytes, which is neither of the two lengths
// decodePair would otherwise try. It has to be told.
const decoded = decodePair(passphrase, userEncoded || encoded, encTypes, isDilithium(type)
? dilithiumSizes(type).secretKey
: undefined
);
if (decoded.secretKey.length === 64) {
// Upstream decides "is this a secret key or a seed?" by length, because for
// the curve schemes a 64-byte blob is a secret and a 32-byte one is a seed.
// An ML-DSA secret is neither, and would take the seed branch and be fed to
// keygen as entropy — producing a valid, wrong key in silence. The type
// knows the answer, so ask it.
if (isDilithium(type) || decoded.secretKey.length === 64) {
publicKey = decoded.publicKey;
secretKey = decoded.secretKey;
} else {
@@ -142,6 +152,25 @@ export function createPair ({ toSS58, type }: Setup, { publicKey, secretKey }: P
publicKey = pair.publicKey;
secretKey = pair.secretKey;
}
// The public key has only now arrived. If the pair was constructed from JSON
// it has been reporting an address carried as data since then, so check the
// two agree.
//
// This is not a paranoid check. For every other scheme the address *is* the
// public key, so a JSON file whose `address` field has been edited cannot
// decode at all. Here it decodes perfectly and yields a pair that reports an
// address its key does not control — a user would see the attacker's address
// in their own wallet and believe they held it.
if (accountId) {
const derived = TYPE_ADDRESS[type](publicKey);
if (!u8aEq(derived, accountId)) {
throw new Error('Decoded public key does not match the address in the account JSON');
}
accountId = undefined;
}
};
const recode = (passphrase?: string): Uint8Array => {
@@ -153,8 +182,15 @@ export function createPair ({ toSS58, type }: Setup, { publicKey, secretKey }: P
return encoded;
};
// While an ML-DSA pair restored from JSON is locked, its public key is still
// inside the encrypted blob and the account id cannot be computed — so use the
// one carried alongside. `decodePkcs8` clears it once the real key arrives and
// has been checked against it.
const addressRawOf = (): Uint8Array =>
accountId ?? TYPE_ADDRESS[type](publicKey);
const encodeAddress = (): string => {
const raw = TYPE_ADDRESS[type](publicKey);
const raw = addressRawOf();
return type === 'ethereum'
? ethereumEncode(raw)
@@ -166,7 +202,7 @@ export function createPair ({ toSS58, type }: Setup, { publicKey, secretKey }: P
return encodeAddress();
},
get addressRaw (): Uint8Array {
const raw = TYPE_ADDRESS[type](publicKey);
const raw = addressRawOf();
return type === 'ethereum'
? raw.slice(-20)
+15
View File
@@ -2,6 +2,21 @@
// SPDX-License-Identifier: Apache-2.0
export interface PairInfo {
/**
* The 32-byte account id, when it cannot be derived from `publicKey`.
*
* Only ML-DSA pairs need this, and only while locked. Everywhere else the
* address is a cheap function of the public key, so a pair restored from JSON
* can report its address before anyone supplies a password. A Quantus account
* id is a one-way Poseidon2 hash, and the public key lives inside the
* encrypted blob — so between `createFromJson` and `decodePkcs8` there is
* nothing to compute it from, and callers read `pair.address` in exactly that
* window.
*
* Carried as data rather than derived, and checked against the real public key
* once that arrives.
*/
accountId?: Uint8Array | undefined;
publicKey: Uint8Array;
secretKey?: Uint8Array | undefined;
seed?: Uint8Array | null;