Projects : gbw-signer : gbw-signer_usrbin
| 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 provides shell functions to streamline full wallet encryption using GPG. |
| 7 | |
| 8 | Prerequisites |
| 9 | ------------- |
| 10 | |
| 11 | gscm : the Gales Scheme interpreter. |
| 12 | |
| 13 | Installation |
| 14 | ------------ |
| 15 | |
| 16 | This software ignores some historical Unix conventions in favor of a simplified variant of Bernstein's /package scheme ( http://cr.yp.to/slashpackage.html ). Installation paths and command names are not configurable, which amounts to a global namespace claim, such that people and programs can count on finding components at known paths if they are to be found at all. User commands are symlinked into /usr/bin and will replace prior files in case of conflict; see "package/commands" for the list. |
| 17 | |
| 18 | You will need root privileges to install. |
| 19 | |
| 20 | 1. Create the top-level /package directory if necessary and place the tree at its fully version-qualified path: |
| 21 | |
| 22 | mkdir -p /package |
| 23 | cp -r /YOUR/PATH/TO/gbw-signer /package/gbw-signer-2 |
| 24 | |
| 25 | 2. Run the install script from the above directory: |
| 26 | |
| 27 | cd /package/gbw-signer-2 |
| 28 | sh package/install |
| 29 | |
| 30 | ECC cache generation will take a noticeable time, depending on hardware, though hopefully not so much as to suggest preparing a beverage. |
| 31 | |
| 32 | 3. Run the test suite: |
| 33 | |
| 34 | sh package/check |
| 35 | |
| 36 | Ensure there are no failures indicated. It should take about the same time. |
| 37 | |
| 38 | To revert to this version after installing a different one, simply repeat step 2. |
| 39 | |
| 40 | Operation |
| 41 | --------- |
| 42 | |
| 43 | A wallet is represented as a filesystem tree serving as key-value store, arranged as follows: |
| 44 | |
| 45 | wallet/ |
| 46 | keys/ |
| 47 | address : hex-encoded private key |
| 48 | ... |
| 49 | change : change address |
| 50 | fee : transaction fee in BTC/kB |
| 51 | outputs : unspent outputs table |
| 52 | transactions : linefeed-delimited raw transaction list |
| 53 | |
| 54 | 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: |
| 55 | |
| 56 | Address : address to which the output was sent, in the usual Base58 |
| 57 | Value : monetary value of the output, in decimal BTC (see Warnings below) |
| 58 | TXID : hash of transaction containing the output, in the "little-endian" hex format used by bitcoind |
| 59 | Index : position in the transaction's output vector, as decimal integer |
| 60 | |
| 61 | Any further text in a line is considered comment. |
| 62 | |
| 63 | 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. |
| 64 | |
| 65 | The main program is "gbw-signer", which provides subcommands for key generation or import and transaction issuance. Run "gbw-signer help" for details. |
| 66 | |
| 67 | GPG integration: setup |
| 68 | ---------------------- |
| 69 | |
| 70 | 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. |
| 71 | |
| 72 | 1. Set GBW_RECIPIENT to your desired GPG key ID for wallet encryption. |
| 73 | |
| 74 | 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. |
| 75 | |
| 76 | 3. Source the file /package/gbw-signer/library/gbw-shell.sh to load its function definitions. |
| 77 | |
| 78 | Example: |
| 79 | |
| 80 | GBW_RECIPIENT=0123456789ABCDEF |
| 81 | GBW_TMPDIR=/tmp |
| 82 | . /package/gbw-signer/library/gbw-shell.sh |
| 83 | |
| 84 | GPG integration: operation |
| 85 | -------------------------- |
| 86 | |
| 87 | 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. |
| 88 | |
| 89 | gbw-save : saves an encrypted copy of the tree, leaving the plaintext open. |
| 90 | |
| 91 | gbw-close : saves and deletes the plaintext tree. |
| 92 | |
| 93 | gbw-discard : deletes the plaintext tree without saving. |
| 94 | |
| 95 | gbw-open PATH : decrypts a saved wallet from PATH into a tree under GBW_TMPDIR and moves the shell to its root. |
| 96 | |
| 97 | 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. |
| 98 | |
| 99 | Warnings |
| 100 | -------- |
| 101 | |
| 102 | A strong entropy source is required in /dev/urandom. |
| 103 | |
| 104 | Compromised inputs can drain your funds even without disclosure of private keys. The most obvious case would be sending to a valid but unintended address. More subtle is that, because Bitcoin transactions do not explicitly specify fee and input values, an incorrect prior output value in the "outputs" table can drain funds in the form of an exhorbitant transaction fee. |
| 105 | |
| 106 | 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. |
| 107 | |
| 108 | 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. |
| 109 | |
| 110 | Enjoy your new nuclear briefcase ( http://trilema.com/2016/how-to-cut-the-wallet/#footnote_1_69751 ) ! |