@ethereumjs/wallet
Version:
Utilities for handling Ethereum keys
429 lines • 16.7 kB
JavaScript
import { bytesToHex, bytesToUnprefixedHex, concatBytes, equalsBytes, importPublic, isValidPrivate, isValidPublic, privateToAddress, privateToPublic, publicToAddress, randomBytes, toChecksumAddress, unprefixedHexToBytes, utf8ToBytes, } from '@ethereumjs/util';
import { base58check } from '@scure/base';
import * as aes from 'ethereum-cryptography/aes.js';
import { keccak256 } from 'ethereum-cryptography/keccak.js';
import { pbkdf2 } from 'ethereum-cryptography/pbkdf2.js';
import { scrypt } from 'ethereum-cryptography/scrypt.js';
import { sha256 } from 'ethereum-cryptography/sha256.js';
import { v4 as uuidv4 } from 'uuid';
const bs58check = base58check(sha256);
function scryptV1(password, salt, kdfparams) {
const { N, P, R, DkLen } = kdfparams;
return scrypt(password, salt, N, P, R, DkLen);
}
function scryptV3(password, kdfparams) {
const { salt, n, p, r, dklen } = kdfparams;
return scrypt(utf8ToBytes(password), salt, n, p, r, dklen);
}
function scryptV3Out(password, kdfparams) {
const { salt, n, p, r, dklen } = kdfparams;
return scrypt(utf8ToBytes(password), unprefixedHexToBytes(salt), n, p, r, dklen);
}
function validateHexString(paramName, str, length) {
if (str.toLowerCase().startsWith('0x')) {
str = str.slice(2);
}
if (!str && length === undefined) {
return str;
}
if (length % 2) {
throw new Error(`Invalid length argument, must be an even number`);
}
if (typeof length === 'number' && str.length !== length) {
throw new Error(`Invalid ${paramName}, string must be ${length} hex characters`);
}
if (!/^([0-9a-f]{2})+$/i.test(str)) {
const howMany = typeof length === 'number' ? length : 'empty or a non-zero even number of';
throw new Error(`Invalid ${paramName}, string must be ${howMany} hex characters`);
}
return str;
}
function validateBytes(paramName, bytes, length) {
if (!(bytes instanceof Uint8Array)) {
const howManyHex = typeof length === 'number' ? `${length * 2}` : 'empty or a non-zero even number of';
const howManyBytes = typeof length === 'number' ? ` (${length} bytes)` : '';
throw new Error(`Invalid ${paramName}, must be a string (${howManyHex} hex characters) or Uint8Array${howManyBytes}`);
}
if (typeof length === 'number' && bytes.length !== length) {
throw new Error(`Invalid ${paramName}, Uint8Array must be ${length} bytes`);
}
return bytes;
}
function mergeToV3ParamsWithDefaults(params) {
const v3Defaults = {
cipher: 'aes-128-ctr',
kdf: 'scrypt',
salt: randomBytes(32),
iv: randomBytes(16),
uuid: randomBytes(16),
dklen: 32,
c: 262144,
n: 262144,
r: 8,
p: 1,
};
if (!params) {
return v3Defaults;
}
if (typeof params.salt === 'string') {
params.salt = unprefixedHexToBytes(validateHexString('salt', params.salt));
}
if (typeof params.iv === 'string') {
params.iv = unprefixedHexToBytes(validateHexString('iv', params.iv, 32));
}
if (typeof params.uuid === 'string') {
params.uuid = unprefixedHexToBytes(validateHexString('uuid', params.uuid, 32));
}
if (params.salt) {
validateBytes('salt', params.salt);
}
if (params.iv) {
validateBytes('iv', params.iv, 16);
}
if (params.uuid) {
validateBytes('uuid', params.uuid, 16);
}
return {
...v3Defaults,
...params,
};
}
function kdfParamsForPBKDF(opts) {
return {
dklen: opts.dklen,
salt: opts.salt,
c: opts.c,
prf: 'hmac-sha256',
};
}
function kdfParamsForScrypt(opts) {
return {
dklen: opts.dklen,
salt: opts.salt,
n: opts.n,
p: opts.p,
r: opts.r,
};
}
// wallet implementation
export class Wallet {
constructor(privateKey, publicKey = undefined) {
this.privateKey = privateKey;
this.publicKey = publicKey;
if (privateKey && publicKey) {
throw new Error('Cannot supply both a private and a public key to the constructor');
}
if (privateKey && !isValidPrivate(privateKey)) {
throw new Error('Private key does not satisfy the curve requirements (ie. it is invalid)');
}
if (publicKey && !isValidPublic(publicKey)) {
throw new Error('Invalid public key');
}
}
// static methods
/**
* Create an instance based on a new random key.
*
* @param icapDirect setting this to `true` will generate an address suitable for the `ICAP Direct mode`
*/
static generate(icapDirect = false) {
if (icapDirect) {
const max = BigInt('0x088f924eeceeda7fe92e1f5b0fffffffffffffff');
for (;;) {
const privateKey = randomBytes(32);
const hex = bytesToUnprefixedHex(privateToAddress(privateKey));
if (BigInt('0x' + hex) <= max) {
return new Wallet(privateKey);
}
}
}
else {
return new Wallet(randomBytes(32));
}
}
/**
* Create an instance where the address is valid against the supplied pattern (**this will be very slow**)
*/
static generateVanityAddress(pattern) {
if (!(pattern instanceof RegExp)) {
pattern = new RegExp(pattern);
}
for (;;) {
const privateKey = randomBytes(32);
const address = privateToAddress(privateKey);
if (pattern.test(bytesToUnprefixedHex(address))) {
return new Wallet(privateKey);
}
}
}
/**
* Create an instance based on a public key (certain methods will not be available)
*
* This method only accepts uncompressed Ethereum-style public keys, unless
* the `nonStrict` flag is set to true.
*/
static fromPublicKey(publicKey, nonStrict = false) {
if (nonStrict) {
publicKey = importPublic(publicKey);
}
return new Wallet(undefined, publicKey);
}
/**
* Create an instance based on a BIP32 extended public key (xpub)
*/
static fromExtendedPublicKey(extendedPublicKey) {
if (extendedPublicKey.slice(0, 4) !== 'xpub') {
throw new Error('Not an extended public key');
}
const publicKey = bs58check.decode(extendedPublicKey).subarray(45);
// Convert to an Ethereum public key
return Wallet.fromPublicKey(publicKey, true);
}
/**
* Create an instance based on a raw private key
*/
static fromPrivateKey(privateKey) {
return new Wallet(privateKey);
}
/**
* Create an instance based on a BIP32 extended private key (xprv)
*/
static fromExtendedPrivateKey(extendedPrivateKey) {
if (extendedPrivateKey.slice(0, 4) !== 'xprv') {
throw new Error('Not an extended private key');
}
const tmp = bs58check.decode(extendedPrivateKey);
if (tmp[45] !== 0) {
throw new Error('Invalid extended private key');
}
return Wallet.fromPrivateKey(tmp.subarray(46));
}
/**
* Import a wallet (Version 1 of the Ethereum wallet format).
*
* @param input A JSON serialized string, or an object representing V1 Keystore.
* @param password The keystore password.
*/
static async fromV1(input, password) {
const json = typeof input === 'object' ? input : JSON.parse(input);
if (json.Version !== '1') {
throw new Error('Not a V1 Wallet');
}
if (json.Crypto.KeyHeader.Kdf !== 'scrypt') {
throw new Error('Unsupported key derivation scheme');
}
const kdfparams = json.Crypto.KeyHeader.KdfParams;
const salt = unprefixedHexToBytes(json.Crypto.Salt);
const derivedKey = await scryptV1(utf8ToBytes(password), salt, kdfparams);
const ciphertext = unprefixedHexToBytes(json.Crypto.CipherText);
const mac = keccak256(concatBytes(derivedKey.subarray(16, 32), ciphertext));
if (bytesToUnprefixedHex(mac) !== json.Crypto.MAC) {
throw new Error('Key derivation failed - possibly wrong passphrase');
}
const seed = await aes.decrypt(ciphertext, keccak256(derivedKey.subarray(0, 16)).subarray(0, 16), unprefixedHexToBytes(json.Crypto.IV), 'aes-128-cbc');
return new Wallet(seed);
}
/**
* Import a wallet (Version 3 of the Ethereum wallet format). Set `nonStrict` true to accept files with mixed-caps.
*
* @param input A JSON serialized string, or an object representing V3 Keystore.
* @param password The keystore password.
*/
static async fromV3(input, password, nonStrict = false) {
const json = typeof input === 'object' ? input : JSON.parse(nonStrict ? input.toLowerCase() : input);
if (json.version !== 3) {
throw new Error('Not a V3 wallet');
}
let derivedKey, kdfparams;
if (json.crypto.kdf === 'scrypt') {
kdfparams = json.crypto.kdfparams;
// FIXME: support progress reporting callback
derivedKey = await scryptV3Out(password, kdfparams);
}
else if (json.crypto.kdf === 'pbkdf2') {
kdfparams = json.crypto.kdfparams;
if (kdfparams.prf !== 'hmac-sha256') {
throw new Error('Unsupported parameters to PBKDF2');
}
derivedKey = await pbkdf2(utf8ToBytes(password), unprefixedHexToBytes(kdfparams.salt), kdfparams.c, kdfparams.dklen, 'sha256');
}
else {
throw new Error('Unsupported key derivation scheme');
}
const ciphertext = unprefixedHexToBytes(json.crypto.ciphertext);
const mac = keccak256(concatBytes(derivedKey.subarray(16, 32), ciphertext));
if (bytesToUnprefixedHex(mac) !== json.crypto.mac) {
throw new Error('Key derivation failed - possibly wrong passphrase');
}
const seed = await aes.decrypt(ciphertext, derivedKey.subarray(0, 16), unprefixedHexToBytes(json.crypto.cipherparams.iv), json.crypto.cipher);
return new Wallet(seed);
}
/*
* Import an Ethereum Pre Sale wallet.
* Based on https://github.com/ethereum/pyethsaletool/blob/master/pyethsaletool.py
* JSON fields: encseed, ethaddr, btcaddr, email
*
* @param input A JSON serialized string, or an object representing EthSale Keystore.
* @param password The keystore password.
*/
static async fromEthSale(input, password) {
const json = typeof input === 'object' ? input : JSON.parse(input);
const encseed = unprefixedHexToBytes(json.encseed);
// key derivation
const pass = utf8ToBytes(password);
const derivedKey = (await pbkdf2(pass, pass, 2000, 32, 'sha256')).subarray(0, 16);
// seed decoding (IV is first 16 bytes)
// NOTE: crypto (derived from openssl) when used with aes-*-cbc will handle PKCS#7 padding internally
// see also http://stackoverflow.com/a/31614770/4964819
const seed = await aes.decrypt(encseed.subarray(16), derivedKey, encseed.subarray(0, 16), 'aes-128-cbc', true);
const wallet = new Wallet(keccak256(seed));
if (bytesToUnprefixedHex(wallet.getAddress()) !== json.ethaddr) {
throw new Error('Decoded key mismatch - possibly wrong passphrase');
}
return wallet;
}
// private getters
/**
* Returns the wallet's public key.
*/
get pubKey() {
if (this.publicKey === undefined || this.publicKey === null) {
this.publicKey = privateToPublic(this.privateKey);
}
return this.publicKey;
}
/**
* Returns the wallet's private key.
*/
get privKey() {
if (this.privateKey === undefined || this.privateKey === null) {
throw new Error('This is a public key only wallet');
}
return this.privateKey;
}
// public instance methods
/**
* Returns the wallet's private key.
*
*/
getPrivateKey() {
return this.privKey;
}
getPrivateKeyString() {
return bytesToHex(this.privKey);
}
/**
* Returns the wallet's public key.
*/
getPublicKey() {
return this.pubKey;
}
/**
* Returns the wallet's public key as a "0x" prefixed hex string
*/
getPublicKeyString() {
return bytesToHex(this.getPublicKey());
}
/**
* Returns the wallet's address.
*/
getAddress() {
return publicToAddress(this.pubKey);
}
/**
* Returns the wallet's address as a "0x" prefixed hex string
*/
getAddressString() {
return bytesToHex(this.getAddress());
}
/**
* Returns the wallet's private key as a "0x" prefixed hex string checksummed
* according to [EIP 55](https://github.com/ethereum/EIPs/issues/55).
*/
getChecksumAddressString() {
return toChecksumAddress(this.getAddressString());
}
/**
* Returns an Etherem Version 3 Keystore Format object representing the wallet
*
* @param password The password used to encrypt the Keystore.
* @param opts The options for the keystore. See [its spec](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) for more info.
*/
async toV3(password, opts) {
if (this.privateKey === undefined || this.privateKey === null) {
throw new Error('This is a public key only wallet');
}
const v3Params = mergeToV3ParamsWithDefaults(opts);
let kdfParams;
let derivedKey;
switch (v3Params.kdf) {
case "pbkdf2" /* KDFFunctions.PBKDF */:
kdfParams = kdfParamsForPBKDF(v3Params);
derivedKey = await pbkdf2(utf8ToBytes(password), kdfParams.salt, kdfParams.c, kdfParams.dklen, 'sha256');
break;
case "scrypt" /* KDFFunctions.Scrypt */:
kdfParams = kdfParamsForScrypt(v3Params);
// FIXME: support progress reporting callback
derivedKey = await scryptV3(password, kdfParams);
break;
default:
throw new Error('Unsupported kdf');
}
const ciphertext = await aes.encrypt(this.privKey, derivedKey.subarray(0, 16), v3Params.iv, v3Params.cipher, false);
const mac = keccak256(concatBytes(derivedKey.subarray(16, 32), ciphertext));
return {
version: 3,
id: uuidv4({ random: v3Params.uuid }),
// @ts-ignore - the official V3 keystore spec omits the address key
address: bytesToUnprefixedHex(this.getAddress()),
crypto: {
ciphertext: bytesToUnprefixedHex(ciphertext),
cipherparams: { iv: bytesToUnprefixedHex(v3Params.iv) },
cipher: v3Params.cipher,
kdf: v3Params.kdf,
kdfparams: {
...kdfParams,
salt: bytesToUnprefixedHex(kdfParams.salt),
},
mac: bytesToUnprefixedHex(mac),
},
};
}
/**
* Return the suggested filename for V3 keystores.
*/
getV3Filename(timestamp) {
/*
* We want a timestamp like 2016-03-15T17-11-33.007598288Z. Date formatting
* is a pain in Javascript, everbody knows that. We could use moment.js,
* but decide to do it manually in order to save space.
*
* toJSON() returns a pretty close version, so let's use it. It is not UTC though,
* but does it really matter?
*
* Alternative manual way with padding and Date fields: http://stackoverflow.com/a/7244288/4964819
*
*/
const ts = timestamp !== undefined ? new Date(timestamp) : new Date();
return [
'UTC--',
ts.toJSON().replace(/:/g, '-'),
'--',
bytesToUnprefixedHex(this.getAddress()),
].join('');
}
async toV3String(password, opts) {
return JSON.stringify(await this.toV3(password, opts));
}
/**
* Verify the publicKey, privateKey pair
*
* @param publicKey the public key to verify against the private key of the wallet
*/
verifyPublicKey(publicKey) {
if (this.privateKey === undefined)
return false;
return equalsBytes(privateToPublic(this.privateKey), publicKey);
}
}
//# sourceMappingURL=wallet.js.map