Use of different bitgen commands

================================

There are a number of bitgen commands that generate new keypairs:

* brainwallet
* bulk
* dice
* hash
* hex
* mnemonic
* random
* (vanity)

random
======
The "random" command generates a new keypair using /dev/random
as the entropy source. This is very convenient, but the
generated address is only as secure as the input from /dev/random.

On Linux the random number from /dev/random is probably of very high

quality, but the Linux distribution may be using a modified version
of the random number generator which may give less than perfect
random numbers. Therefore it could be a good idea to generate the
random numbers manually instead.

Example invocation:
$ bitgen random

dice
====
The "dice" command takes 100 throws from a 6-sided dice as random
input and converts that to a private key. The 100 numbers from 1 to 6
gives 256 bits of entropy for the bitcoin private key.

Example invocation:
$ bitgen dice
16251625162416241624162416241624162416426124614261426142125125162634361436142615216
52165212121212616

brainwallet
===========
The "brainwallet" command takes a salt a long arbitrary string as input
and converts that to a 256 bit private key.

The recommendation is to use an email address as a salt, since this

is a personally unique string which is used often, and therefore easy
to remember. It is also stored in many places, such as in your friends
inbox, so it will not be forgotten. bitgen will accept any string,
as a salt, but by following this recommendation you should be able to
remember the right salt even 20 years from now. Also use lower case
for the email address.

Note that the salt is not secret, its purpose is to make your
private key unique.
The bitgen brainwallet key derivation is done using the KDF Argon2,
of the input string followed by sha256.

The purpose of a brainwallet is that the passphrase should be possible

for humans to remember so that the key can be transported without
writing it down.

The passphrase should be long enough to give 256 bits of entropy.

bitgen will not accept passphrases shorter that 50 characters.

However, even with a large number of characters, the input must

be impossible to guess. For example, a long string of only "A":s
will be predictible enough to be guessed and should therefore not be used.
Also sentences that exist in books or on the Internet should not be used.

Example of passphrases:
"This is a sEnTeNcE with (10-5-2)+0-1 strrrrange WoRdS: Hyberfurtic, Megasilver and
Fillitelling
which will end Very vEry veRy verY VERY soon! Over and out. Bye bye.
Sill there? Good night gentlemen and ladiEs..."

"This is! my oWn way of having 159 SecTureNiceGoodPerfectIncredibleAmazing

sec rets that only I kno w aBout today and in the farFar future"

Using both upper and lower case characters, numbers and special characters
will improve the entrophy and therefore the security of passphrase.

Example invocation:
$ bitgen brainwallet bob123@gmail.com "This is! my oWn way of having a
SecureNiceGoodPerfectIncredibleAmazing sec ret that only I kno w about"

hash
====
The "hash" command takes the sha256 hash of the input string to
generate the key pair.

With the "hash" command many random keys should be pressed on

the keybord in order to give the has input. The random string should
be very long in order to maximize the entropy.

At least 200 characters are needed, and bitgen will not accept less
than that.

Example invocation:
$ bitgen hash sdfkljsdklfjsklfjskldfjdkjkjdejdjdjdfjslakiusiodfuiosduio
cdhjklsdjsdjkhfiljfhskljhfsjkfhjkdhfjsdhfjksdfhsjkhfjkhdjhdjdjdjdjdjdjd
jdjdfhskjdfhsdjklfsklfjsklfjsdklfjskljfsdklfsdjklhfsdhfshfjkhdjkhvhvhvb
vbxcbxchjbvxjbvxjkcjcvhjskjfhsjkhfdhfskjrhwyuiuuduuduududududisfusydfui
sdfysufyujsdfdfhalsdflaksdjaklsdjakljjjdjdjjdjdjdjjddkfjsjdfskdfsdjjdjd
jjwjqjqjqosbgdfisgodghsodghdoghsopsdhjksmudjdbhjdhjhjdhhsdjkhfjkhdjkhsd
jkhfjksdklfjskljfklsdjfkldjkkkdkkdfksfjsdlfjkskdfjskldjfkjkkkdkdkdkdkkd
kekekekekekkekekdfjfkgjksfjslkdfjkljfkjbjbjnjmmmdmdmsdfkjsdklfjklsfdsdf
ydyydydydydyddasiufyisdifoosdfosdufsodfuiuduududfdudiifdufsdifdiusidufs
jfdjsdlfkjsdlkjfdslkfjslkdflkjdslkfdjlkjkdkdkkdkdkdkdkfjsdkjfksjdfjdkdk

hex
===
The "hex" command is used to give the raw private key in hex format.
This could be used if you have a given private key in hex format
and need the corresponding public address and WIF.

With a 16-sided dice it could also be used to generate a new key pair.

There should be exactly 64 hex characters to give 256 bits.

Example invocation:
$ bitgen hex f2a123b23bbbcbb12f123231239aacabcefefaefabcbcb6347f734623748f3f3

mnemonic
========
The "mnemonic" command should be used when the mnemonic sentence for
a private key is known. The mnemonic could for example have been
generated by another command such as "random" or "dice".

A mnemonic sentence is a list of 24 english words from a known

dictionary consisting of 2048 words.

The bitgen mnenomics follow the BIP39 standard where applicable.

However, the mnemonic in bitgen is used for the private key and
not the seed as stated in BIP39.

The mnemonic contains a 8 bit checksum as stated by BIP39,

and it is therefore not possible to select 24 random words from
the wordlist. When doing so, in most cases the checksum will be
wrong and the sentence will be rejected by bitgen.

Example invocation:
$ bitgen mnemonic "verify animal uncle jazz royal sudden rough edge couple broom
private fiscal useful latin salt just slice boss worry hand casino piece sound
inch"

bulk
====
The "bulk" command is used to generate many key pairs with a single
command. The "bulk" command use /dev/random as input for the
private key. The numbers of address pairs to generate should be
specified on the command line.

Example invocation:
$ bitgen bulk 10

vanity
======
The vanity command is used to generate "vanity" bitcoin addresses,
which means addresses that starts with a specified string.

An example of a vanity address is:

1PetervVuW7yuK55HEN4pBnWMHhBQwonj

This address starts with the string "1Peter", which makes the
address look more personal than a complete random string.
In bitgen version 0.8, the support for vanity addresses is a bit slow,
and can therefore only be used for short prefixes.
Prefixes with 6 characters (plus the leading "1")
are however possible to use. With enough patience perhaps even 7?

The speed will be improved in future releases of bitgen.

The argument to "bitgen vanity" is the leading string

including the leading "1". Examples:

1a
1aa
1bye
1hello
1peter

The search is done without regard to case, which means that

1Aa, 1AA, and 1aa will all match "1aa".

Vanity address search starts at a random address, and then increases

the private key by one for each try. The first address that is searched
is generated from /dev/random. In future versions of bitgen it will
be possible to specify the starting point of the search with
"dice", "hex" and so on.

Example invocation:
$ bitgen vanity 1bit

Mini private key handling

=========================
A bitcoin mini private key is a key with the following form:
S6c56bnXQiBjk9mqSYE7ykVQ7NzrRy

Normal private keys are longer, for example:

5JibXtTHBncvnKbcg1ujFHR3QeovupFgXzuJnrHUCXoqfhn3jJW

The mini private keys have been used to print private keys
hidden inside physical coins. The small space makes the short
private keys easier to use than a full WIF key.

Note that the entropy is smaller for mini private keys than
normal bitcoin private keys.

bitgen can be used to convert a mini private key to wif format,

and is also able to generate new mini private keys.

mini
====
The "mini" command generates new mini private keys.

The entropy in mini private keys is enough for safety,

but normal keys contains more entropy so it is not recommanded
to use mini private keys unless there is strong reason for that
such as using physical coins.

The start value with searching for a mini private key is taken from
/dev/random.
Example invocation:
$ bitgen mini

miniToWif
=========
The "miniToWif" command converts a given mini private key to the
corresponding private key in wif format and the public address.

The parameter is the mini private key.

Example invocation:
$ bitgen miniToWif SoYit5uXp13A4nYbGmLwMzG6MnEDbY

Payment requests
================

Bitgen can create payment requests, such as invoices.

The ps or pdf file with the invoice can then be sent with for example
email to the person that is asked to pay.

Current graphical design is rather simple, future bitgen versions

will elaborate the visual design.

reqPayment
==========
The "reqPayment" is used to create an invoice for the specified
public bitcoin address. Optional parameters are the amount to pay,
a label, a message, and the last payment date.

The amount, label and message are encoded into the QR-code.

Example invocation:
$ bitgen reqPayment 1CXfBhBtbLv8jRoJ2ZtAnoCq2Adgdi6HDt
$ bitgen reqPayment 1CXfBhBtbLv8jRoJ2ZtAnoCq2Adgdi6HDt 0.1
$ bitgen reqPayment 1CXfBhBtbLv8jRoJ2ZtAnoCq2Adgdi6HDt 0.1 "Payment"
$ bitgen reqPayment 1CXfBhBtbLv8jRoJ2ZtAnoCq2Adgdi6HDt 0.1 "Payment" "Please pay"
$ bitgen reqPayment 1CXfBhBtbLv8jRoJ2ZtAnoCq2Adgdi6HDt 0.1 "Payment" "Please pay"
"19 jun 2016"

pubAddr
=======

The command "pubAddr" is similar to the "reqPayment" command,

bit the layout of the generated postscript file differs.

In this case you youself mightbe the recipient of the public address.
pubaddr can for example be used when you need to send bitcoins to your
own address.

Example invocation:
$ bitgen pubAddr 1Phsu4GfjHc6o4gACWHcFi2WL2f1ZtN6gh
Hierarchial random generation
=============================
The HR option is for advanced users, and requires more understanding
of the underlaying cryptographic operations.

It is closely related to HD wallets (hierarchial deterministic),

and uses similar cryptographic operations.

However, non-deterministic key generation is used instead of

deterministic private key generation. In fact, the generation should
ideally be completely random.

The idea is simple. First a "root" key pair is generated.

The public part from that root key is then used to generate new
bitcoin addresses. The only way to recover the private key for
the address is to use both the root private key and the secondary
private keys.

This has several uses. For example it is possible to generate new

bitcoin addresses in a hostile environment such as a computers
infected with spyware. As long as the original private key was
generated on a clean computer unconnected to the internet the new
addresses will be safe.

It can also be used to let another person create new bitcoin

addresses that only the person with the root key can access
the funds for.

genRoot
=======
The "genRoot" command generates a new root key pair to use for
bitcoin address generation. A generation method should be specified,
such as for example "dice" or "random".

This will create a "privroot" and a "pubroot" file, as well as

ps-files with the same information. However, in this case
the "privroot" and pubroot files are directly usable.

Example invocation:
$ bitgen genRoot random

This might for example create the follwing files:

root_9493E6C8_priv.privroot
root_9493E6C8_pub.pubroot

genPub
======
The "genPub" command takes a public root key as input and generates a
bitcoin public address from that. In order to do so a 256 bit
random number is used. In the current bitgen version only /dev/random
is used for this random number generation, but future versions will
support the other methods as well, "dice", "hex", etc.

The result is a public bitcoin address that is saved to ps-files.

However, the private ps-files will not contain any private key
that can be directly used (WIF). Instead a 256 bit random number
will be included. That random number is called "private index".
Knowledge of this "private index" will not be enough to spend
the funds in the bitcoin address. This means that this information
is not as critical as the original private root key.
Even so, it is recommended to keep this information just as secure
as the original private root key.

Example invocation:
$ bitgen genPub root_9493E6C8_pub.pubroot

genPriv
=======
The "genPriv" command is used to recover private keys that
corresponds to bitcoin addresses generated with "genPub".

In order to obtain the private key two pieces of information

must be given:

* The root private key (.privroot)

* The private index for the intended bitcoin address (.privindex)

Providing both parts will give the private keys to access the funds.

The normal "_share.ps" and "_private.ps" files will be created.

Example invocation:
$ bitgen genPriv root_9493E6C8_priv.privroot
1LZcyGzhLiKrnb7Ekkt2wK7QZZvAAhS2vf.privindex

Key information commands

=======================
There are some commands that can be used to obtain information about
a specified private or public address.

infoPrivate
===============
The "verifyPrivate" commands gives information about a private key in
wif format. It also verifies that the given string is a
valid private key.

Example invocation:
$ bitgen infoPrivate 5KQNfT4KZnRGC2GstzAZDMQMBznA3Ex9dUnzEmjYoRoLnTPbR5a

verifyAddress
=============
The "infoAddress" commands verifies that a public bitcoin address
is a valid.

Example invocation:
$ bitgen infoAddress 12oN6MMEFdxCRxodxRdu9m1hawifP5Sqr2
Input of secret information
===========================

Bitgen commands are given on the command line, and this may include
information used to generate a private key, for example dice throws.
However, this very sensitive information often ends up in a
local history file, which could be read by someone else.
Bitgen has an option to read sensitive information from standard input
instead of from the command line. This will prevent the information
from beeing stored in a shell history file.

This option is activated by specifying a dash ("-") instead of the

secret information on the command line.

For example, the "dice" command can be done as follows:

$ bitgen dice 16251625162416241624162.....

When the "-"-option is used, the following command should be given:

$ bitgen dice -

This will read the dice throws from the standard input.

Using standard input redirection

================================
When using the "-" option, bitgen will read from standard input
in order to get the information. It is possible to use
bitgen interactively, and input the information directly
on the console. However, it is also possible to redirect standard
input instead of using it interactively.

The shell normally redirects when using the "<" character.

For example, the following example takes the
passphrase from the file "passphrase.txt", instead of reading
from the console:

$ bitgen brainwallet bob@gmail.com - < passphrase.txt

Here is another example, which displays information about a

private key:
$ echo 5JnR1ULR1zzp6PJVqsCBoHqbbHrbCoSSaUpZHJJMPCQ8UaR7Szz > mypriv.txt
$ bitgen infoPrivate - < mypriv.txt

This will display information about the given private key.