github.com/MaynardMiner/ethereumprogpow@v1.8.23/cmd/clef/tutorial.md (about) 1 ## Initializing the signer 2 3 First, initialize the master seed. 4 5 ```text 6 #./signer init 7 8 WARNING! 9 10 The signer is alpha software, and not yet publically released. This software has _not_ been audited, and there 11 are no guarantees about the workings of this software. It may contain severe flaws. You should not use this software 12 unless you agree to take full responsibility for doing so, and know what you are doing. 13 14 TLDR; THIS IS NOT PRODUCTION-READY SOFTWARE! 15 16 17 Enter 'ok' to proceed: 18 >ok 19 A master seed has been generated into /home/martin/.signer/secrets.dat 20 21 This is required to be able to store credentials, such as : 22 * Passwords for keystores (used by rule engine) 23 * Storage for javascript rules 24 * Hash of rule-file 25 26 You should treat that file with utmost secrecy, and make a backup of it. 27 NOTE: This file does not contain your accounts. Those need to be backed up separately! 28 ``` 29 30 (for readability purposes, we'll remove the WARNING printout in the rest of this document) 31 32 ## Creating rules 33 34 Now, you can create a rule-file. Note that it is not mandatory to use predefined rules, but it's really handy. 35 36 ```javascript 37 function ApproveListing(){ 38 return "Approve" 39 } 40 ``` 41 42 Get the `sha256` hash. If you have openssl, you can do `openssl sha256 rules.js`... 43 ```text 44 #sha256sum rules.js 45 6c21d1737429d6d4f2e55146da0797782f3c0a0355227f19d702df377c165d72 rules.js 46 ``` 47 ...now `attest` the file... 48 ```text 49 #./signer attest 6c21d1737429d6d4f2e55146da0797782f3c0a0355227f19d702df377c165d72 50 51 INFO [02-21|12:14:38] Ruleset attestation updated sha256=6c21d1737429d6d4f2e55146da0797782f3c0a0355227f19d702df377c165d72 52 ``` 53 54 ...and (this is required only for non-production versions) load a mock-up `4byte.json` by copying the file from the source to your current working directory: 55 ```text 56 #cp $GOPATH/src/github.com/ethereum/go-ethereum/cmd/clef/4byte.json $PWD 57 ``` 58 59 At this point, we can start the signer with the rule-file: 60 ```text 61 #./signer --rules rules.js --rpc 62 63 INFO [09-25|20:28:11.866] Using CLI as UI-channel 64 INFO [09-25|20:28:11.876] Loaded 4byte db signatures=5509 file=./4byte.json 65 INFO [09-25|20:28:11.877] Rule engine configured file=./rules.js 66 DEBUG[09-25|20:28:11.877] FS scan times list=100.781µs set=13.253µs diff=5.761µs 67 DEBUG[09-25|20:28:11.884] Ledger support enabled 68 DEBUG[09-25|20:28:11.888] Trezor support enabled 69 INFO [09-25|20:28:11.888] Audit logs configured file=audit.log 70 DEBUG[09-25|20:28:11.888] HTTP registered namespace=account 71 INFO [09-25|20:28:11.890] HTTP endpoint opened url=http://localhost:8550 72 DEBUG[09-25|20:28:11.890] IPC registered namespace=account 73 INFO [09-25|20:28:11.890] IPC endpoint opened url=<nil> 74 ------- Signer info ------- 75 * extapi_version : 2.0.0 76 * intapi_version : 2.0.0 77 * extapi_http : http://localhost:8550 78 * extapi_ipc : <nil> 79 ``` 80 81 Any list-requests will now be auto-approved by our rule-file. 82 83 ## Under the hood 84 85 While doing the operations above, these files have been created: 86 87 ```text 88 #ls -laR ~/.signer/ 89 /home/martin/.signer/: 90 total 16 91 drwx------ 3 martin martin 4096 feb 21 12:14 . 92 drwxr-xr-x 71 martin martin 4096 feb 21 12:12 .. 93 drwx------ 2 martin martin 4096 feb 21 12:14 43f73718397aa54d1b22 94 -rwx------ 1 martin martin 256 feb 21 12:12 secrets.dat 95 96 /home/martin/.signer/43f73718397aa54d1b22: 97 total 12 98 drwx------ 2 martin martin 4096 feb 21 12:14 . 99 drwx------ 3 martin martin 4096 feb 21 12:14 .. 100 -rw------- 1 martin martin 159 feb 21 12:14 config.json 101 102 #cat /home/martin/.signer/43f73718397aa54d1b22/config.json 103 {"ruleset_sha256":{"iv":"6v4W4tfJxj3zZFbl","c":"6dt5RTDiTq93yh1qDEjpsat/tsKG7cb+vr3sza26IPL2fvsQ6ZoqFx++CPUa8yy6fD9Bbq41L01ehkKHTG3pOAeqTW6zc/+t0wv3AB6xPmU="}} 104 105 ``` 106 107 In `~/.signer`, the `secrets.dat` file was created, containing the `master_seed`. 108 The `master_seed` was then used to derive a few other things: 109 110 - `vault_location` : in this case `43f73718397aa54d1b22` . 111 - Thus, if you use a different `master_seed`, another `vault_location` will be used that does not conflict with each other. 112 - Example: `signer --signersecret /path/to/afile ...` 113 - `config.json` which is the encrypted key/value storage for configuration data, containing the key `ruleset_sha256`. 114 115 116 ## Adding credentials 117 118 In order to make more useful rules like signing transactions, the signer needs access to the passwords needed to unlock keystores. 119 120 ```text 121 #./signer addpw "0x694267f14675d7e1b9494fd8d72fefe1755710fa" "test_password" 122 123 INFO [02-21|13:43:21] Credential store updated key=0x694267f14675d7e1b9494fd8d72fefe1755710fa 124 ``` 125 ## More advanced rules 126 127 Now let's update the rules to make use of credentials: 128 129 ```javascript 130 function ApproveListing(){ 131 return "Approve" 132 } 133 function ApproveSignData(r){ 134 if( r.address.toLowerCase() == "0x694267f14675d7e1b9494fd8d72fefe1755710fa") 135 { 136 if(r.message.indexOf("bazonk") >= 0){ 137 return "Approve" 138 } 139 return "Reject" 140 } 141 // Otherwise goes to manual processing 142 } 143 144 ``` 145 In this example: 146 * Any requests to sign data with the account `0x694...` will be 147 * auto-approved if the message contains with `bazonk` 148 * auto-rejected if it does not. 149 * Any other signing-requests will be passed along for manual approve/reject. 150 151 _Note: make sure that `0x694...` is an account you have access to. You can create it either via the clef or the traditional account cli tool. If the latter was chosen, make sure both clef and geth use the same keystore by specifing `--keystore path/to/your/keystore` when running clef._ 152 153 Attest the new file... 154 ```text 155 #sha256sum rules.js 156 2a0cb661dacfc804b6e95d935d813fd17c0997a7170e4092ffbc34ca976acd9f rules.js 157 158 #./signer attest 2a0cb661dacfc804b6e95d935d813fd17c0997a7170e4092ffbc34ca976acd9f 159 160 INFO [02-21|14:36:30] Ruleset attestation updated sha256=2a0cb661dacfc804b6e95d935d813fd17c0997a7170e4092ffbc34ca976acd9f 161 ``` 162 163 And start the signer: 164 165 ``` 166 #./signer --rules rules.js --rpc 167 168 INFO [09-25|21:02:16.450] Using CLI as UI-channel 169 INFO [09-25|21:02:16.466] Loaded 4byte db signatures=5509 file=./4byte.json 170 INFO [09-25|21:02:16.467] Rule engine configured file=./rules.js 171 DEBUG[09-25|21:02:16.468] FS scan times list=1.45262ms set=21.926µs diff=6.944µs 172 DEBUG[09-25|21:02:16.473] Ledger support enabled 173 DEBUG[09-25|21:02:16.475] Trezor support enabled 174 INFO [09-25|21:02:16.476] Audit logs configured file=audit.log 175 DEBUG[09-25|21:02:16.476] HTTP registered namespace=account 176 INFO [09-25|21:02:16.478] HTTP endpoint opened url=http://localhost:8550 177 DEBUG[09-25|21:02:16.478] IPC registered namespace=account 178 INFO [09-25|21:02:16.478] IPC endpoint opened url=<nil> 179 ------- Signer info ------- 180 * extapi_version : 2.0.0 181 * intapi_version : 2.0.0 182 * extapi_http : http://localhost:8550 183 * extapi_ipc : <nil> 184 ``` 185 186 And then test signing, once with `bazonk` and once without: 187 188 ``` 189 #curl -H "Content-Type: application/json" -X POST --data "{\"jsonrpc\":\"2.0\",\"method\":\"account_sign\",\"params\":[\"0x694267f14675d7e1b9494fd8d72fefe1755710fa\",\"0x$(xxd -pu <<< ' bazonk baz gaz')\"],\"id\":67}" http://localhost:8550/ 190 {"jsonrpc":"2.0","id":67,"result":"0x93e6161840c3ae1efc26dc68dedab6e8fc233bb3fefa1b4645dbf6609b93dace160572ea4ab33240256bb6d3dadb60dcd9c515d6374d3cf614ee897408d41d541c"} 191 192 #curl -H "Content-Type: application/json" -X POST --data "{\"jsonrpc\":\"2.0\",\"method\":\"account_sign\",\"params\":[\"0x694267f14675d7e1b9494fd8d72fefe1755710fa\",\"0x$(xxd -pu <<< ' bonk baz gaz')\"],\"id\":67}" http://localhost:8550/ 193 {"jsonrpc":"2.0","id":67,"error":{"code":-32000,"message":"Request denied"}} 194 195 ``` 196 197 Meanwhile, in the signer output: 198 ```text 199 INFO [02-21|14:42:41] Op approved 200 INFO [02-21|14:42:56] Op rejected 201 ``` 202 203 The signer also stores all traffic over the external API in a log file. The last 4 lines shows the two requests and their responses: 204 205 ```text 206 #tail -n 4 audit.log 207 t=2018-02-21T14:42:41+0100 lvl=info msg=Sign api=signer type=request metadata="{\"remote\":\"127.0.0.1:49706\",\"local\":\"localhost:8550\",\"scheme\":\"HTTP/1.1\"}" addr="0x694267f14675d7e1b9494fd8d72fefe1755710fa [chksum INVALID]" data=202062617a6f6e6b2062617a2067617a0a 208 t=2018-02-21T14:42:42+0100 lvl=info msg=Sign api=signer type=response data=93e6161840c3ae1efc26dc68dedab6e8fc233bb3fefa1b4645dbf6609b93dace160572ea4ab33240256bb6d3dadb60dcd9c515d6374d3cf614ee897408d41d541c error=nil 209 t=2018-02-21T14:42:56+0100 lvl=info msg=Sign api=signer type=request metadata="{\"remote\":\"127.0.0.1:49708\",\"local\":\"localhost:8550\",\"scheme\":\"HTTP/1.1\"}" addr="0x694267f14675d7e1b9494fd8d72fefe1755710fa [chksum INVALID]" data=2020626f6e6b2062617a2067617a0a 210 t=2018-02-21T14:42:56+0100 lvl=info msg=Sign api=signer type=response data= error="Request denied" 211 ```