mirror of
https://github.com/bitcoinbook/bitcoinbook
synced 2024-11-23 00:28:14 +00:00
162 lines
5.4 KiB
Plaintext
162 lines
5.4 KiB
Plaintext
----------------------------------------------------------
|
||
BIP: BIP-0039
|
||
Title: Mnemonic code for generating deterministic keys
|
||
Authors: Marek Palatinus <slush@satoshilabs.com>
|
||
Pavol Rusnak <stick@satoshilabs.com>
|
||
ThomasV <thomasv@bitcointalk.org>
|
||
Aaron Voisine <voisine@gmail.com>
|
||
Sean Bowe <ewillbefull@gmail.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Created: 2013-09-10
|
||
----------------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP describes the implementation of a mnemonic code or mnemonic
|
||
sentence -- a group of easy to remember words -- for the generation of
|
||
deterministic wallets.
|
||
|
||
It consists of two parts: generating the mnenomic, and converting it
|
||
into a binary seed. This seed can be later used to generate
|
||
deterministic wallets using BIP-0032 or similar methods.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
A mnenomic code or sentence is superior for human interaction compared
|
||
to the handling of raw binary or hexidecimal representations of a wallet
|
||
seed. The sentence could be written on paper or spoken over the
|
||
telephone.
|
||
|
||
This guide meant to be as a way to transport computer-generated
|
||
randomnes over human readable transcription. It's not a way how to
|
||
process user-created sentences (also known as brainwallet) to wallet
|
||
seed.
|
||
|
||
[[generating-the-mnemonic]]
|
||
Generating the mnemonic
|
||
~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The mnemonic must encode entropy in any multiple of 32 bits. With larger
|
||
entropy security is improved but the sentence length increases. We can
|
||
refer to the initial entropy length as ENT. The recommended size of ENT
|
||
is 128-256 bits.
|
||
|
||
First, an initial entropy of ENT bits is generated. A checksum is
|
||
generated by taking the first
|
||
|
||
--------
|
||
ENT / 32
|
||
--------
|
||
|
||
bits of its SHA256 hash. This checksum is appended to the end of the
|
||
initial entropy. Next, these concatenated bits are are split into groups
|
||
of 11 bits, each encoding a number from 0-2047, serving as an index to a
|
||
wordlist. Later, we will convert these numbers into words and use the
|
||
joined words as a mnemonic sentence.
|
||
|
||
The following table describes the relation between the initial entropy
|
||
length (ENT), the checksum length (CS) and length of the generated
|
||
mnemonic sentence (MS) in words.
|
||
|
||
------------------------------
|
||
CS = ENT / 32
|
||
MS = (ENT + CS) / 11
|
||
|
||
| ENT | CS | ENT+CS | MS |
|
||
+-------+----+--------+------+
|
||
| 128 | 4 | 132 | 12 |
|
||
| 160 | 5 | 165 | 15 |
|
||
| 192 | 6 | 198 | 18 |
|
||
| 224 | 7 | 231 | 21 |
|
||
| 256 | 8 | 264 | 24 |
|
||
------------------------------
|
||
|
||
[[wordlist]]
|
||
Wordlist
|
||
~~~~~~~~
|
||
|
||
An ideal wordlist has the following characteristics:
|
||
|
||
\a) smart selection of words
|
||
|
||
` - wordlist is created in such way that it's enough to type the first four` +
|
||
` letters to unambiguously identify the word`
|
||
|
||
\b) similar words avoided
|
||
|
||
` - word pairs like "build" and "built", "woman" and "women", or "quick" and "quickly"` +
|
||
` not only make remembering the sentence difficult, but are also more error` +
|
||
` prone and more difficult to guess`
|
||
|
||
\c) sorted wordlists
|
||
|
||
` - wordlist is sorted which allows for more efficient lookup of the code words` +
|
||
` (i.e. implementation can use binary search instead of linear search)` +
|
||
` - this also allows trie (prefix tree) to be used, e.g. for better compression`
|
||
|
||
The wordlist can contain native characters, but they have to be encoded
|
||
in UTF-8 using Normalization Form Compatibility Decomposition (NFKD).
|
||
|
||
[[from-mnemonic-to-seed]]
|
||
From mnemonic to seed
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
A user may decide to protect their mnemonic by passphrase. If a
|
||
passphrase is not present, an empty string "" is used instead.
|
||
|
||
To create a binary seed from the mnemonic, we use PBKDF2 function with a
|
||
mnemonic sentence (in UTF-8 NFKD) used as a password and string
|
||
"mnemonic" + passphrase (again in UTF-8 NFKD) used as a salt. Iteration
|
||
count is set to 2048 and HMAC-SHA512 is used as a pseudo-random
|
||
function. Desired length of the derived key is 512 bits (= 64 bytes).
|
||
|
||
This seed can be later used to generate deterministic wallets using
|
||
BIP-0032 or similar methods.
|
||
|
||
The conversion of the mnemonic sentence to binary seed is completely
|
||
independent from generating the sentence. This results in rather simple
|
||
code; there are no constraints on sentence structure and clients are
|
||
free to implement their own wordlists or even whole sentence generators,
|
||
allowing for flexibility in wordlists for typo detection or other
|
||
purposes.
|
||
|
||
Although using mnemonic not generated by algorithm described in
|
||
"Generating the mnemonic" section is possible, this is not advised and
|
||
software must compute checksum of the mnemonic sentence using wordlist
|
||
and issue a warning if it is invalid.
|
||
|
||
Described method also provides plausible deniability, because every
|
||
passphrase generates a valid seed (and thus deterministic wallet) but
|
||
only the correct one will make the desired wallet available.
|
||
|
||
[[wordlists]]
|
||
Wordlists
|
||
~~~~~~~~~
|
||
|
||
* link:bip-0039/english.txt[English]
|
||
|
||
[[test-vectors]]
|
||
Test vectors
|
||
~~~~~~~~~~~~
|
||
|
||
See https://github.com/trezor/python-mnemonic/blob/master/vectors.json
|
||
|
||
[[reference-implementation]]
|
||
Reference Implementation
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Reference implementation including wordlists is available from
|
||
|
||
http://github.com/trezor/python-mnemonic
|
||
|
||
[[other-implementations]]
|
||
Other Implementations
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Objective-C - https://github.com/nybex/NYMnemonic
|