EASYSEED(1) General Commands Manual EASYSEED(1) NAME easyseed – Bitcoin BIP 39 mnemonic seed phrase generator SYNOPSIS easyseed -b bits [-l lang] [-k keyfile] [-p | -j passfile] [-A] List languages: easyseed -L Print wordlist: easyseed -P [-l lang] Full, verbose self-tests: easyseed -T DESCRIPTION easyseed is a BIP 39 Bitcoin seed phrase generator which is intended to be portable and auditable, with minimal dependencies and easy-to-read source code. The intended use case is seed phrase generation on an airgap machine. To protect safety of user funds, a battery of standard test vectors is run on every use. A seed is read off the system random device; and corresponding seed words are printed to standard output. In general usage, the options are as follows: -A Output all basic information for creation and use of a BIP 39 mnemonic backup to a BIP 32 Hierarchical Deterministic (HD) wallet. Information is provided in a freeform text format which is designed to be reasonably easy to parse in scripts; however, the format should not yet be considered stable. The information provided: • The input entropy, as a hexadecimal string. • The mnemonic phrase corresponding to that entropy. • The output seed value created through PBKDF2 (with optional passphrase) as specified by BIP 39, as a hexadecimal string. • The BIP 32 “xprv” extended master private key, generated from the seed value as specified in BIP 32. See the CAVEATS section before using with popular light clients. -b bits Required. Generate a mnemonic phrase representing a seed with bits bits. Valid values for bits and the word length they produce are as follows: Bits Words 128 12 160 15 192 18 224 21 256 24 -j passfile Read the optional passphrase from the specified passfile. Use - to specify standard input. Exclusive of the -p option. -k keyfile Read key material (entropy) in the form of binary octets from the specified keyfile. The actual length of keymat provided must match the specified number of bits. Use - to specify standard input. If this option is not given, then easyseed obtains entropy from the random(4) device. -l lang Produce a mnemonic in the language or writing system lang. The language may be specified via various identifiers as listed by the -L option. In alphabetical order, currently supported languages and writing systems are Chinese (Simplified), Chinese (Traditional), English, French, Italian, Japanese, Korean, and Spanish. The default language is English. -p Use an optional passphrase, obtained from the terminal. This is an interactive option; the user will be prompted to enter the passphrase, then re- enter it for confirmation. easyseed will refuse to proceed if standard input is not a tty(4). Exclusive of the -j option. The following modes do not produce a mnemonic phrase: -L List languages and writing systems which may be used with the -l lang option, then exit. Any of the listed strings may be used as an identifier. -P Print the wordlist to stdout in the source format used at build time, and print the SHA-256 hash of the wordlist to stderr; then exit. -T Run a full battery of self-tests with verbose results printed to stdout, then exit. An abbreviated self- test is run each and every time the easyseed utility is used. EXIT STATUS The easyseed utility exits 0 on success, and >0 if an error occurs. EXAMPLES Generate a 24-word mnemonic representing a 256-bit random seed: umask 077 easyseed -b 256 > myseed.txt Generate an 18-word mnemonic in the Japanese language, representing a 192-bit random seed: easyseed -b 192 -l japanese Use bits from a keyfile: dd if=/dev/random of=secret.key bs=32 count=1 easyseed -b 256 -k secret.key > myseed.txt or easyseed -b 256 -k - < secret.key > myseed.txt STANDARDS The easyseed utility implements all functionality specified by Bitcoin BIP 39: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki. It also implements some functionality from utility implements all functionality specified by Bitcoin BIP 32: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki. Nonstandard behaviour may be offered by currently undocumented options. AUTHORS By nullius . PGP: 0xC2E91CD74A4C57A105F6C21B5A00591B2F307E0C Tips: 3NULL3ZCUXr7RDLxXeLPDMZDZYxuaYkCnG: bitcoin:3NULL3ZCUXr7RDLxXeLPDMZDZYxuaYkCnG. CAVEATS The BIP 32 “xprv” output encodes the extended master private key with a depth of 0. This behaviour is correct and consistent with the BIP 39 and BIP 32 standards. However, at least one known client, Electrum, will misinterpret this as a depth 3 extended child key, and produce a wallet full of incorrect addresses which do not match the addresses derived from the mnemonic. This could result in user funds loss. See Electrum Issue #3671: https://github.com/spesmilo/electrum/issues/3671. Most users are apparently still generating airgap seed phrases with Javascript-based seed phrase generators. Adequate random number generation is impossible from within Javascript. Users should use the easyseed utility instead. BUGS Language support is necessarily finite. The easyseed utility supports all languages which have official BIP 39 wordlists in the Bitcoin BIP repository. To add your language to the easyseed utility, add a wordlist for your language to the BIP 39 wordlist set. The author monkey-pasted language names from a popular wiki site. If the -L option shows an incorrect name for your language, in your language, then please file a bug or contact the author. The short identifiers for the two distinct Chinese writing systems are suboptimal, and inconsistent with reality. Better suggestions would be appreciated. SECURITY CONSIDERATIONS For secure seed phrase generation, it is imperative to use an adequate CSPRNG as a source of randomness. The easyseed utility draws randomness off the system's random(4) device. To avoid blocking on Linux, easyseed reads off /dev/urandom. The author deems this to be adequate. On other reasonable systems, such as FreeBSD, /dev/urandom is a symlink to /dev/random; thus, this is a non-issue. easyseed performs basic sanitization to zeroize and remove keymat (key material) from memory. It also takes special measures to avoid or clean up any userland buffering in printf(3). However, this does nothing to prevent secret bits from being left in the memory areas used by the kernel for file or pipe buffers. In proper use on a dedicated airgap machine, this should be of lesser concern than on a multiuser and/or networked system. easyseed will leave far less data remanence than most other software which deals with secret keys. Also, easyseed is far superior to utilities written in Javascript and similar, which have absolutely no control of garbage collection and memory release. Bitcoin January 9, 2018 Bitcoin