diff --git a/packages/keyring/src/keyring.ts b/packages/keyring/src/keyring.ts index 168e6f0e9..3aaf1d8a6 100644 --- a/packages/keyring/src/keyring.ts +++ b/packages/keyring/src/keyring.ts @@ -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); } /** diff --git a/packages/keyring/src/pair/decode.ts b/packages/keyring/src/pair/decode.ts index 20a166e1b..a0c3adbf1 100644 --- a/packages/keyring/src/pair/decode.ts +++ b/packages/keyring/src/pair/decode.ts @@ -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; diff --git a/packages/keyring/src/pair/dilithiumJson.spec.ts b/packages/keyring/src/pair/dilithiumJson.spec.ts new file mode 100644 index 000000000..d67d92145 --- /dev/null +++ b/packages/keyring/src/pair/dilithiumJson.spec.ts @@ -0,0 +1,114 @@ +// Copyright 2017-2026 @polkadot/keyring authors & contributors +// SPDX-License-Identifier: Apache-2.0 + +/// + +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); + }); +}); diff --git a/packages/keyring/src/pair/index.ts b/packages/keyring/src/pair/index.ts index 690ce459f..caeac857b 100644 --- a/packages/keyring/src/pair/index.ts +++ b/packages/keyring/src/pair/index.ts @@ -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) diff --git a/packages/keyring/src/pair/types.ts b/packages/keyring/src/pair/types.ts index 43ffb4dcd..c9dcc0fd4 100644 --- a/packages/keyring/src/pair/types.ts +++ b/packages/keyring/src/pair/types.ts @@ -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;