Projects : gbw-signer : gbw-signer_subdir_genesis
| 1 | About |
| 2 | ----- |
| 3 | |
| 4 | This is gbw-signer, the offline signing component of Gales Bitcoin Wallet as described at http://fixpoint.welshcomputing.com/2019/gales-bitcoin-wallet-spec-and-battle-plan/ , written by Jacob Welsh for JWRD Computing. |
| 5 | |
| 6 | It is written in Scheme with original implementations of the cryptographic primitives, and shell functions to simplify full wallet encryption using GPG. |
| 7 | |
| 8 | Prerequisites |
| 9 | ------------- |
| 10 | |
| 11 | gscm : the Gales Scheme interpreter. |
| 12 | |
| 13 | Installation |
| 14 | ------------ |
| 15 | |
| 16 | This software sheds some historical Unix conventions in favor of Bernstein's /package scheme ( http://cr.yp.to/slashpackage.html ), which I find meshes fairly well with the ideas of V. If this is your first time using it, you may need to create the /package directory and add /command to your shell's PATH variable. |
| 17 | |
| 18 | 1. Press or otherwise install the tree at the path: |
| 19 | |
| 20 | /package/gbw-signer-1 |
| 21 | |
| 22 | The installation path is not configurable. This amounts to a claim on the global namespace, as command names always do. People and programs can count on finding components at known paths if they are to be found at all, as surely as with /bin/sh. This doesn't mean the files must physically exist under /package; for example, a symlink from there could ease working on the code as a non-root user. |
| 23 | |
| 24 | 2. From the above directory, run (as root): |
| 25 | |
| 26 | sh package/install |
| 27 | |
| 28 | ECC cache generation will take a noticeable time, depending on hardware, though hopefully not so much as to suggest preparing a beverage. |
| 29 | |
| 30 | 3. Run the test suite: |
| 31 | |
| 32 | sh package/check |
| 33 | |
| 34 | Ensure there are no failures indicated. It should take about the same time. |
| 35 | |
| 36 | Operation |
| 37 | --------- |
| 38 | |
| 39 | A wallet is represented as a filesystem tree serving as key-value store, arranged as follows: |
| 40 | |
| 41 | wallet/ |
| 42 | keys/ |
| 43 | address : hex-encoded private key |
| 44 | ... |
| 45 | change : change address |
| 46 | fee : transaction fee in BTC/kB |
| 47 | outputs : unspent outputs table |
| 48 | transactions : linefeed-delimited raw transaction list |
| 49 | |
| 50 | The outputs table is awk-style, that is, with fields separated by one or more space or tab characters and records separated by linefeeds. It can be constructed by hand or using the companion "gbw-node" tools to collect it from the blockchain. Fields are, in order: |
| 51 | |
| 52 | Address : address to which the output was sent, in the usual Base58 |
| 53 | Value : monetary value of the output, in decimal BTC (see Warnings below) |
| 54 | TXID : hash of transaction containing the output, in the "little-endian" hex format used by bitcoind |
| 55 | Index : position in the transaction's output vector, as decimal integer |
| 56 | |
| 57 | Any further text in a line is considered comment. |
| 58 | |
| 59 | An initial wallet tree must be constructed including empty keys directory, change, fee, and outputs. "gbw-init" described below can assist with all but the outputs part. |
| 60 | |
| 61 | The main program is "gbw-signer", which provides subcommands for key generation or import and transaction issuance. Run "gbw-signer help" for details. |
| 62 | |
| 63 | GPG integration: setup |
| 64 | ---------------------- |
| 65 | |
| 66 | Wallet encryption is managed by working with a tree in memory then saving to a GPG encrypted tar file. Tools are included to facilitate this; they operate through the shell environment and thus are configured using it. Presumably you will want to do this in your shell startup (~/.bashrc or equivalent) to make it permanent. |
| 67 | |
| 68 | 1. Set GBW_RECIPIENT to your desired GPG key ID for wallet encryption. |
| 69 | |
| 70 | 2. Set GBW_TMPDIR to an absolute path to a writeable temporary directory. To avoid spilling plaintext keys to permanent storage, this must be on a tmpfs and the machine must not have swap enabled. |
| 71 | |
| 72 | 3. Source the file /package/gbw-signer/library/gbw-shell.sh to load its function definitions. |
| 73 | |
| 74 | Example: |
| 75 | |
| 76 | GBW_RECIPIENT=0123456789ABCDEF |
| 77 | GBW_TMPDIR=/tmp |
| 78 | . /package/gbw-signer/library/gbw-shell.sh |
| 79 | |
| 80 | GPG integration: operation |
| 81 | -------------------------- |
| 82 | |
| 83 | gbw-init PATH : creates a new wallet tree under GBW_TMPDIR and moves the shell to its root. PATH specifies where the GPG-encrypted archive will be later saved. |
| 84 | |
| 85 | gbw-save : saves an encrypted copy of the tree, leaving the plaintext open. |
| 86 | |
| 87 | gbw-close : saves and deletes the plaintext tree. |
| 88 | |
| 89 | gbw-discard : deletes the plaintext tree without saving. |
| 90 | |
| 91 | gbw-open PATH : decrypts a saved wallet from PATH into a tree under GBW_TMPDIR and moves the shell to its root. |
| 92 | |
| 93 | Shell variables prefixed with GBW_ are used to coordinate these commands; see source for details. The save process is believed to be atomic but as always, keep backups, and verify that you can re-open an encrypted wallet before counting on it. |
| 94 | |
| 95 | Warnings |
| 96 | -------- |
| 97 | |
| 98 | A strong entropy source is required in /dev/urandom. |
| 99 | |
| 100 | Compromised inputs can drain your funds even without disclosure of private keys. The most obvious case would be sending to a valid but incorrect address. More subtle is that, because Bitcoin transactions do not explicitly specify fee and input values, an incorrect value field in "outputs" can result in excess input consumption and incorrect change computation, causing loss through exhorbitant transaction fee. |
| 101 | |
| 102 | The cryptographic operations do not use constant-time algorithms, thus side channel attacks (timing, electromagnetic, sonic, power, thermal) are possible. Fixing this is in scope for future revisions; meanwhile, use appropriate precautions. |
| 103 | |
| 104 | The signer does not include checking for hardware faults, which while rare are not impossible. Fixing this is in scope for future revisions; meanwhile, it may be prudent to decode raw transactions after signing to verify addresses and amounts prior to broadcasting. |
| 105 | |
| 106 | Enjoy your new nuclear briefcase ( http://trilema.com/2016/how-to-cut-the-wallet/#footnote_1_69751 ) ! |