json-keystore.ts 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389
  1. /**
  2. * The JSON Wallet formats allow a simple way to store the private
  3. * keys needed in Ethereum along with related information and allows
  4. * for extensible forms of encryption.
  5. *
  6. * These utilities facilitate decrypting and encrypting the most common
  7. * JSON Wallet formats.
  8. *
  9. * @_subsection: api/wallet:JSON Wallets [json-wallets]
  10. */
  11. import { CTR } from "aes-js";
  12. import { getAddress } from "../address/index.js";
  13. import { keccak256, pbkdf2, randomBytes, scrypt, scryptSync } from "../crypto/index.js";
  14. import { computeAddress } from "../transaction/index.js";
  15. import {
  16. concat, getBytes, hexlify, uuidV4, assert, assertArgument
  17. } from "../utils/index.js";
  18. import { getPassword, spelunk, zpad } from "./utils.js";
  19. import type { ProgressCallback } from "../crypto/index.js";
  20. import type { BytesLike } from "../utils/index.js";
  21. import { version } from "../_version.js";
  22. const defaultPath = "m/44'/60'/0'/0/0";
  23. /**
  24. * The contents of a JSON Keystore Wallet.
  25. */
  26. export type KeystoreAccount = {
  27. address: string;
  28. privateKey: string;
  29. mnemonic?: {
  30. path?: string;
  31. locale?: string;
  32. entropy: string;
  33. }
  34. };
  35. /**
  36. * The parameters to use when encrypting a JSON Keystore Wallet.
  37. */
  38. export type EncryptOptions = {
  39. progressCallback?: ProgressCallback;
  40. iv?: BytesLike;
  41. entropy?: BytesLike;
  42. client?: string;
  43. salt?: BytesLike;
  44. uuid?: string;
  45. scrypt?: {
  46. N?: number;
  47. r?: number;
  48. p?: number;
  49. }
  50. }
  51. /**
  52. * Returns true if %%json%% is a valid JSON Keystore Wallet.
  53. */
  54. export function isKeystoreJson(json: string): boolean {
  55. try {
  56. const data = JSON.parse(json);
  57. const version = ((data.version != null) ? parseInt(data.version): 0);
  58. if (version === 3) { return true; }
  59. } catch (error) { }
  60. return false;
  61. }
  62. function decrypt(data: any, key: Uint8Array, ciphertext: Uint8Array): string {
  63. const cipher = spelunk<string>(data, "crypto.cipher:string");
  64. if (cipher === "aes-128-ctr") {
  65. const iv = spelunk<Uint8Array>(data, "crypto.cipherparams.iv:data!")
  66. const aesCtr = new CTR(key, iv);
  67. return hexlify(aesCtr.decrypt(ciphertext));
  68. }
  69. assert(false, "unsupported cipher", "UNSUPPORTED_OPERATION", {
  70. operation: "decrypt"
  71. });
  72. }
  73. function getAccount(data: any, _key: string): KeystoreAccount {
  74. const key = getBytes(_key);
  75. const ciphertext = spelunk<Uint8Array>(data, "crypto.ciphertext:data!");
  76. const computedMAC = hexlify(keccak256(concat([ key.slice(16, 32), ciphertext ]))).substring(2);
  77. assertArgument(computedMAC === spelunk<string>(data, "crypto.mac:string!").toLowerCase(),
  78. "incorrect password", "password", "[ REDACTED ]");
  79. const privateKey = decrypt(data, key.slice(0, 16), ciphertext);
  80. const address = computeAddress(privateKey);
  81. if (data.address) {
  82. let check = data.address.toLowerCase();
  83. if (!check.startsWith("0x")) { check = "0x" + check; }
  84. assertArgument(getAddress(check) === address, "keystore address/privateKey mismatch", "address", data.address);
  85. }
  86. const account: KeystoreAccount = { address, privateKey };
  87. // Version 0.1 x-ethers metadata must contain an encrypted mnemonic phrase
  88. const version = spelunk(data, "x-ethers.version:string");
  89. if (version === "0.1") {
  90. const mnemonicKey = key.slice(32, 64);
  91. const mnemonicCiphertext = spelunk<Uint8Array>(data, "x-ethers.mnemonicCiphertext:data!");
  92. const mnemonicIv = spelunk<Uint8Array>(data, "x-ethers.mnemonicCounter:data!");
  93. const mnemonicAesCtr = new CTR(mnemonicKey, mnemonicIv);
  94. account.mnemonic = {
  95. path: (spelunk<null | string>(data, "x-ethers.path:string") || defaultPath),
  96. locale: (spelunk<null | string>(data, "x-ethers.locale:string") || "en"),
  97. entropy: hexlify(getBytes(mnemonicAesCtr.decrypt(mnemonicCiphertext)))
  98. };
  99. }
  100. return account;
  101. }
  102. type ScryptParams = {
  103. name: "scrypt";
  104. salt: Uint8Array;
  105. N: number;
  106. r: number;
  107. p: number;
  108. dkLen: number;
  109. };
  110. type KdfParams = ScryptParams | {
  111. name: "pbkdf2";
  112. salt: Uint8Array;
  113. count: number;
  114. dkLen: number;
  115. algorithm: "sha256" | "sha512";
  116. };
  117. function getDecryptKdfParams<T>(data: any): KdfParams {
  118. const kdf = spelunk(data, "crypto.kdf:string");
  119. if (kdf && typeof(kdf) === "string") {
  120. if (kdf.toLowerCase() === "scrypt") {
  121. const salt = spelunk<Uint8Array>(data, "crypto.kdfparams.salt:data!");
  122. const N = spelunk<number>(data, "crypto.kdfparams.n:int!");
  123. const r = spelunk<number>(data, "crypto.kdfparams.r:int!");
  124. const p = spelunk<number>(data, "crypto.kdfparams.p:int!");
  125. // Make sure N is a power of 2
  126. assertArgument(N > 0 && (N & (N - 1)) === 0, "invalid kdf.N", "kdf.N", N);
  127. assertArgument(r > 0 && p > 0, "invalid kdf", "kdf", kdf);
  128. const dkLen = spelunk<number>(data, "crypto.kdfparams.dklen:int!");
  129. assertArgument(dkLen === 32, "invalid kdf.dklen", "kdf.dflen", dkLen);
  130. return { name: "scrypt", salt, N, r, p, dkLen: 64 };
  131. } else if (kdf.toLowerCase() === "pbkdf2") {
  132. const salt = spelunk<Uint8Array>(data, "crypto.kdfparams.salt:data!");
  133. const prf = spelunk<string>(data, "crypto.kdfparams.prf:string!");
  134. const algorithm = prf.split("-").pop();
  135. assertArgument(algorithm === "sha256" || algorithm === "sha512", "invalid kdf.pdf", "kdf.pdf", prf);
  136. const count = spelunk<number>(data, "crypto.kdfparams.c:int!");
  137. const dkLen = spelunk<number>(data, "crypto.kdfparams.dklen:int!");
  138. assertArgument(dkLen === 32, "invalid kdf.dklen", "kdf.dklen", dkLen);
  139. return { name: "pbkdf2", salt, count, dkLen, algorithm };
  140. }
  141. }
  142. assertArgument(false, "unsupported key-derivation function", "kdf", kdf);
  143. }
  144. /**
  145. * Returns the account details for the JSON Keystore Wallet %%json%%
  146. * using %%password%%.
  147. *
  148. * It is preferred to use the [async version](decryptKeystoreJson)
  149. * instead, which allows a [[ProgressCallback]] to keep the user informed
  150. * as to the decryption status.
  151. *
  152. * This method will block the event loop (freezing all UI) until decryption
  153. * is complete, which can take quite some time, depending on the wallet
  154. * paramters and platform.
  155. */
  156. export function decryptKeystoreJsonSync(json: string, _password: string | Uint8Array): KeystoreAccount {
  157. const data = JSON.parse(json);
  158. const password = getPassword(_password);
  159. const params = getDecryptKdfParams(data);
  160. if (params.name === "pbkdf2") {
  161. const { salt, count, dkLen, algorithm } = params;
  162. const key = pbkdf2(password, salt, count, dkLen, algorithm);
  163. return getAccount(data, key);
  164. }
  165. assert(params.name === "scrypt", "cannot be reached", "UNKNOWN_ERROR", { params })
  166. const { salt, N, r, p, dkLen } = params;
  167. const key = scryptSync(password, salt, N, r, p, dkLen);
  168. return getAccount(data, key);
  169. }
  170. function stall(duration: number): Promise<void> {
  171. return new Promise((resolve) => { setTimeout(() => { resolve(); }, duration); });
  172. }
  173. /**
  174. * Resolves to the decrypted JSON Keystore Wallet %%json%% using the
  175. * %%password%%.
  176. *
  177. * If provided, %%progress%% will be called periodically during the
  178. * decrpytion to provide feedback, and if the function returns
  179. * ``false`` will halt decryption.
  180. *
  181. * The %%progressCallback%% will **always** receive ``0`` before
  182. * decryption begins and ``1`` when complete.
  183. */
  184. export async function decryptKeystoreJson(json: string, _password: string | Uint8Array, progress?: ProgressCallback): Promise<KeystoreAccount> {
  185. const data = JSON.parse(json);
  186. const password = getPassword(_password);
  187. const params = getDecryptKdfParams(data);
  188. if (params.name === "pbkdf2") {
  189. if (progress) {
  190. progress(0);
  191. await stall(0);
  192. }
  193. const { salt, count, dkLen, algorithm } = params;
  194. const key = pbkdf2(password, salt, count, dkLen, algorithm);
  195. if (progress) {
  196. progress(1);
  197. await stall(0);
  198. }
  199. return getAccount(data, key);
  200. }
  201. assert(params.name === "scrypt", "cannot be reached", "UNKNOWN_ERROR", { params })
  202. const { salt, N, r, p, dkLen } = params;
  203. const key = await scrypt(password, salt, N, r, p, dkLen, progress);
  204. return getAccount(data, key);
  205. }
  206. function getEncryptKdfParams(options: EncryptOptions): ScryptParams {
  207. // Check/generate the salt
  208. const salt = (options.salt != null) ? getBytes(options.salt, "options.salt"): randomBytes(32);
  209. // Override the scrypt password-based key derivation function parameters
  210. let N = (1 << 17), r = 8, p = 1;
  211. if (options.scrypt) {
  212. if (options.scrypt.N) { N = options.scrypt.N; }
  213. if (options.scrypt.r) { r = options.scrypt.r; }
  214. if (options.scrypt.p) { p = options.scrypt.p; }
  215. }
  216. assertArgument(typeof(N) === "number" && N > 0 && Number.isSafeInteger(N) && (BigInt(N) & BigInt(N - 1)) === BigInt(0), "invalid scrypt N parameter", "options.N", N);
  217. assertArgument(typeof(r) === "number" && r > 0 && Number.isSafeInteger(r), "invalid scrypt r parameter", "options.r", r);
  218. assertArgument(typeof(p) === "number" && p > 0 && Number.isSafeInteger(p), "invalid scrypt p parameter", "options.p", p);
  219. return { name: "scrypt", dkLen: 32, salt, N, r, p };
  220. }
  221. function _encryptKeystore(key: Uint8Array, kdf: ScryptParams, account: KeystoreAccount, options: EncryptOptions): any {
  222. const privateKey = getBytes(account.privateKey, "privateKey");
  223. // Override initialization vector
  224. const iv = (options.iv != null) ? getBytes(options.iv, "options.iv"): randomBytes(16);
  225. assertArgument(iv.length === 16, "invalid options.iv length", "options.iv", options.iv);
  226. // Override the uuid
  227. const uuidRandom = (options.uuid != null) ? getBytes(options.uuid, "options.uuid"): randomBytes(16);
  228. assertArgument(uuidRandom.length === 16, "invalid options.uuid length", "options.uuid", options.iv);
  229. // This will be used to encrypt the wallet (as per Web3 secret storage)
  230. // - 32 bytes As normal for the Web3 secret storage (derivedKey, macPrefix)
  231. // - 32 bytes AES key to encrypt mnemonic with (required here to be Ethers Wallet)
  232. const derivedKey = key.slice(0, 16);
  233. const macPrefix = key.slice(16, 32);
  234. // Encrypt the private key
  235. const aesCtr = new CTR(derivedKey, iv);
  236. const ciphertext = getBytes(aesCtr.encrypt(privateKey));
  237. // Compute the message authentication code, used to check the password
  238. const mac = keccak256(concat([ macPrefix, ciphertext ]))
  239. // See: https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition
  240. const data: { [key: string]: any } = {
  241. address: account.address.substring(2).toLowerCase(),
  242. id: uuidV4(uuidRandom),
  243. version: 3,
  244. Crypto: {
  245. cipher: "aes-128-ctr",
  246. cipherparams: {
  247. iv: hexlify(iv).substring(2),
  248. },
  249. ciphertext: hexlify(ciphertext).substring(2),
  250. kdf: "scrypt",
  251. kdfparams: {
  252. salt: hexlify(kdf.salt).substring(2),
  253. n: kdf.N,
  254. dklen: 32,
  255. p: kdf.p,
  256. r: kdf.r
  257. },
  258. mac: mac.substring(2)
  259. }
  260. };
  261. // If we have a mnemonic, encrypt it into the JSON wallet
  262. if (account.mnemonic) {
  263. const client = (options.client != null) ? options.client: `ethers/${ version }`;
  264. const path = account.mnemonic.path || defaultPath;
  265. const locale = account.mnemonic.locale || "en";
  266. const mnemonicKey = key.slice(32, 64);
  267. const entropy = getBytes(account.mnemonic.entropy, "account.mnemonic.entropy");
  268. const mnemonicIv = randomBytes(16);
  269. const mnemonicAesCtr = new CTR(mnemonicKey, mnemonicIv);
  270. const mnemonicCiphertext = getBytes(mnemonicAesCtr.encrypt(entropy));
  271. const now = new Date();
  272. const timestamp = (now.getUTCFullYear() + "-" +
  273. zpad(now.getUTCMonth() + 1, 2) + "-" +
  274. zpad(now.getUTCDate(), 2) + "T" +
  275. zpad(now.getUTCHours(), 2) + "-" +
  276. zpad(now.getUTCMinutes(), 2) + "-" +
  277. zpad(now.getUTCSeconds(), 2) + ".0Z");
  278. const gethFilename = ("UTC--" + timestamp + "--" + data.address);
  279. data["x-ethers"] = {
  280. client, gethFilename, path, locale,
  281. mnemonicCounter: hexlify(mnemonicIv).substring(2),
  282. mnemonicCiphertext: hexlify(mnemonicCiphertext).substring(2),
  283. version: "0.1"
  284. };
  285. }
  286. return JSON.stringify(data);
  287. }
  288. /**
  289. * Return the JSON Keystore Wallet for %%account%% encrypted with
  290. * %%password%%.
  291. *
  292. * The %%options%% can be used to tune the password-based key
  293. * derivation function parameters, explicitly set the random values
  294. * used. Any provided [[ProgressCallback]] is ignord.
  295. */
  296. export function encryptKeystoreJsonSync(account: KeystoreAccount, password: string | Uint8Array, options?: EncryptOptions): string {
  297. if (options == null) { options = { }; }
  298. const passwordBytes = getPassword(password);
  299. const kdf = getEncryptKdfParams(options);
  300. const key = scryptSync(passwordBytes, kdf.salt, kdf.N, kdf.r, kdf.p, 64);
  301. return _encryptKeystore(getBytes(key), kdf, account, options);
  302. }
  303. /**
  304. * Resolved to the JSON Keystore Wallet for %%account%% encrypted
  305. * with %%password%%.
  306. *
  307. * The %%options%% can be used to tune the password-based key
  308. * derivation function parameters, explicitly set the random values
  309. * used and provide a [[ProgressCallback]] to receive periodic updates
  310. * on the completion status..
  311. */
  312. export async function encryptKeystoreJson(account: KeystoreAccount, password: string | Uint8Array, options?: EncryptOptions): Promise<string> {
  313. if (options == null) { options = { }; }
  314. const passwordBytes = getPassword(password);
  315. const kdf = getEncryptKdfParams(options);
  316. const key = await scrypt(passwordBytes, kdf.salt, kdf.N, kdf.r, kdf.p, 64, options.progressCallback);
  317. return _encryptKeystore(getBytes(key), kdf, account, options);
  318. }