-
Notifications
You must be signed in to change notification settings - Fork 11
/
easyseed.1.txt
195 lines (148 loc) · 8.58 KB
/
easyseed.1.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
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 <nullius@nym.zone>.
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