Merge pull request #17 from trezor/master

BIP39 changes

bip-0039.mediawiki

@@ -5,6 +5,7 @@
            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: 10-09-2013
@@ -12,35 +13,39 @@
 
 ==Abstract==
 
-This BIP describes an usage of mnemonic code or mnemonic sentence - a group of
-easy to remember words - to generate deterministic wallets.
+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 mnemonic and converting it into
-a binary seed. This seed can be later used to generate deterministic wallets
-using BIP-0032 or similar methods.
+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==
 
-Such mnemonic code or mnemonic sentence is much easier to work with than working
-with the binary data directly (or its hexadecimal interpretation). The sentence
-could be writen down on paper (e.g. for storing in a secure location such as
-safe), told over telephone or other voice communication method, or memorized
-in ones memory (this method is called brainwallet).
+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==
 
-First, we decide how much entropy we want mnemonic to encode. Recommended size
-is 128-256 bits, but basically any multiple of 32 bits will do. More bits
-mean more security, but also longer word sentence.
+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.
 
-We take initial entropy of ENT bits and compute its checksum by taking first
-ENT / 32 bits of its SHA256 hash. We append these bits to the end of the initial
-entropy. Next we take these concatenated bits and split them into groups of 11
-bits. Each group encodes number from 0-2047 which is a position in a wordlist.
-We convert numbers into words and use joined words as mnemonic sentence.
+First, an initial entropy of ENT bits is generated. A checksum is generated by
+taking the first <pre>ENT / 32</pre> 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 initial entropy length (ENT),
-checksum length (CS) and length of the generated mnemonic sentence (MS) in words.
+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.
 
 <pre>
 CS = ENT / 32
@@ -57,49 +62,57 @@ MS = (ENT + CS) / 11
 
 ==Wordlist==
 
-In previous section we described how to pick words from a wordlist. Now we
-describe how does a good wordlist look like.
+An ideal wordlist has the following characteristics:
 
 a) smart selection of words
-   - wordlist is created in such way that it's enough to type just first four
+   - 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
-   - words as "build" and "built", "woman" and "women" or "quick" or "quickly"
+   - 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 (see point below)
-   - we avoid these words by carefully selecting them during addition
+     prone and more difficult to guess
 
 c) sorted wordlists
-   - wordlist is sorted which allow more efficient lookup of the code words
+   - 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
 
-Wordlist can contain native characters, but they have to be encoded using UTF-8.
+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==
 
-User can decide to protect his mnemonic by passphrase. If passphrase is not present
-an empty string "" is used instead.
+A user may decide to protect their mnemonic by passphrase. If a passphrase is not
+present, an empty string "" is used instead.
 
-To create binary seed from mnemonic, we use PBKDF2 function with mnemonic sentence
-(in UTF-8) used as a password and string "mnemonic" + passphrase (again in UTF-8)
-used as a salt. Iteration count is set to 4096 and HMAC-SHA512 is used as a pseudo-
-random function. Desired length of the derived key is 512 bits (= 64 bytes).
+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
+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 (they'll lose the proposed method
-for typo detection in that case, but they can come up with their own).
+wordlists or even whole sentence generators, allowing for flexibility in wordlists
+for typo detection or other purposes.
 
-Described method also provides plausable deniability, because every passphrase
+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==
+
+* [[bip-0039/english.txt|English]]
+
 ==Test vectors==
 
 See https://github.com/trezor/python-mnemonic/blob/master/vectors.json