github.com/alexdevranger/node-1.8.27@v0.0.0-20221128213301-aa5841e41d2d/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 44 ```text 45 #sha256sum rules.js 46 6c21d1737429d6d4f2e55146da0797782f3c0a0355227f19d702df377c165d72 rules.js 47 ``` 48 49 ...now `attest` the file... 50 51 ```text 52 #./signer attest 6c21d1737429d6d4f2e55146da0797782f3c0a0355227f19d702df377c165d72 53 54 INFO [02-21|12:14:38] Ruleset attestation updated sha256=6c21d1737429d6d4f2e55146da0797782f3c0a0355227f19d702df377c165d72 55 ``` 56 57 ...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: 58 59 ```text 60 #cp $GOPATH/src/github.com/alexdevranger/node-1.8.27/cmd/clef/4byte.json $PWD 61 ``` 62 63 At this point, we can start the signer with the rule-file: 64 65 ```text 66 #./signer --rules rules.js --rpc 67 68 INFO [09-25|20:28:11.866] Using CLI as UI-channel 69 INFO [09-25|20:28:11.876] Loaded 4byte db signatures=5509 file=./4byte.json 70 INFO [09-25|20:28:11.877] Rule engine configured file=./rules.js 71 DEBUG[09-25|20:28:11.877] FS scan times list=100.781µs set=13.253µs diff=5.761µs 72 DEBUG[09-25|20:28:11.884] Ledger support enabled 73 DEBUG[09-25|20:28:11.888] Trezor support enabled 74 INFO [09-25|20:28:11.888] Audit logs configured file=audit.log 75 DEBUG[09-25|20:28:11.888] HTTP registered namespace=account 76 INFO [09-25|20:28:11.890] HTTP endpoint opened url=http://localhost:8550 77 DEBUG[09-25|20:28:11.890] IPC registered namespace=account 78 INFO [09-25|20:28:11.890] IPC endpoint opened url=<nil> 79 ------- Signer info ------- 80 * extapi_version : 2.0.0 81 * intapi_version : 2.0.0 82 * extapi_http : http://localhost:8550 83 * extapi_ipc : <nil> 84 ``` 85 86 Any list-requests will now be auto-approved by our rule-file. 87 88 ## Under the hood 89 90 While doing the operations above, these files have been created: 91 92 ```text 93 #ls -laR ~/.signer/ 94 /home/martin/.signer/: 95 total 16 96 drwx------ 3 martin martin 4096 feb 21 12:14 . 97 drwxr-xr-x 71 martin martin 4096 feb 21 12:12 .. 98 drwx------ 2 martin martin 4096 feb 21 12:14 43f73718397aa54d1b22 99 -rwx------ 1 martin martin 256 feb 21 12:12 secrets.dat 100 101 /home/martin/.signer/43f73718397aa54d1b22: 102 total 12 103 drwx------ 2 martin martin 4096 feb 21 12:14 . 104 drwx------ 3 martin martin 4096 feb 21 12:14 .. 105 -rw------- 1 martin martin 159 feb 21 12:14 config.json 106 107 #cat /home/martin/.signer/43f73718397aa54d1b22/config.json 108 {"ruleset_sha256":{"iv":"6v4W4tfJxj3zZFbl","c":"6dt5RTDiTq93yh1qDEjpsat/tsKG7cb+vr3sza26IPL2fvsQ6ZoqFx++CPUa8yy6fD9Bbq41L01ehkKHTG3pOAeqTW6zc/+t0wv3AB6xPmU="}} 109 110 ``` 111 112 In `~/.signer`, the `secrets.dat` file was created, containing the `master_seed`. 113 The `master_seed` was then used to derive a few other things: 114 115 - `vault_location` : in this case `43f73718397aa54d1b22` . 116 - Thus, if you use a different `master_seed`, another `vault_location` will be used that does not conflict with each other. 117 - Example: `signer --signersecret /path/to/afile ...` 118 - `config.json` which is the encrypted key/value storage for configuration data, containing the key `ruleset_sha256`. 119 120 ## Adding credentials 121 122 In order to make more useful rules like signing transactions, the signer needs access to the passwords needed to unlock keystores. 123 124 ```text 125 #./signer addpw "0x694267f14675d7e1b9494fd8d72fefe1755710fa" "test_password" 126 127 INFO [02-21|13:43:21] Credential store updated key=0x694267f14675d7e1b9494fd8d72fefe1755710fa 128 ``` 129 130 ## More advanced rules 131 132 Now let's update the rules to make use of credentials: 133 134 ```javascript 135 function ApproveListing() { 136 return "Approve"; 137 } 138 function ApproveSignData(r) { 139 if (r.address.toLowerCase() == "0x694267f14675d7e1b9494fd8d72fefe1755710fa") { 140 if (r.message.indexOf("bazonk") >= 0) { 141 return "Approve"; 142 } 143 return "Reject"; 144 } 145 // Otherwise goes to manual processing 146 } 147 ``` 148 149 In this example: 150 151 - Any requests to sign data with the account `0x694...` will be 152 - auto-approved if the message contains with `bazonk` 153 - auto-rejected if it does not. 154 - Any other signing-requests will be passed along for manual approve/reject. 155 156 _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 gdubx use the same keystore by specifing `--keystore path/to/your/keystore` when running clef._ 157 158 Attest the new file... 159 160 ```text 161 #sha256sum rules.js 162 2a0cb661dacfc804b6e95d935d813fd17c0997a7170e4092ffbc34ca976acd9f rules.js 163 164 #./signer attest 2a0cb661dacfc804b6e95d935d813fd17c0997a7170e4092ffbc34ca976acd9f 165 166 INFO [02-21|14:36:30] Ruleset attestation updated sha256=2a0cb661dacfc804b6e95d935d813fd17c0997a7170e4092ffbc34ca976acd9f 167 ``` 168 169 And start the signer: 170 171 ``` 172 #./signer --rules rules.js --rpc 173 174 INFO [09-25|21:02:16.450] Using CLI as UI-channel 175 INFO [09-25|21:02:16.466] Loaded 4byte db signatures=5509 file=./4byte.json 176 INFO [09-25|21:02:16.467] Rule engine configured file=./rules.js 177 DEBUG[09-25|21:02:16.468] FS scan times list=1.45262ms set=21.926µs diff=6.944µs 178 DEBUG[09-25|21:02:16.473] Ledger support enabled 179 DEBUG[09-25|21:02:16.475] Trezor support enabled 180 INFO [09-25|21:02:16.476] Audit logs configured file=audit.log 181 DEBUG[09-25|21:02:16.476] HTTP registered namespace=account 182 INFO [09-25|21:02:16.478] HTTP endpoint opened url=http://localhost:8550 183 DEBUG[09-25|21:02:16.478] IPC registered namespace=account 184 INFO [09-25|21:02:16.478] IPC endpoint opened url=<nil> 185 ------- Signer info ------- 186 * extapi_version : 2.0.0 187 * intapi_version : 2.0.0 188 * extapi_http : http://localhost:8550 189 * extapi_ipc : <nil> 190 ``` 191 192 And then test signing, once with `bazonk` and once without: 193 194 ``` 195 #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/ 196 {"jsonrpc":"2.0","id":67,"result":"0x93e6161840c3ae1efc26dc68dedab6e8fc233bb3fefa1b4645dbf6609b93dace160572ea4ab33240256bb6d3dadb60dcd9c515d6374d3cf614ee897408d41d541c"} 197 198 #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/ 199 {"jsonrpc":"2.0","id":67,"error":{"code":-32000,"message":"Request denied"}} 200 201 ``` 202 203 Meanwhile, in the signer output: 204 205 ```text 206 INFO [02-21|14:42:41] Op approved 207 INFO [02-21|14:42:56] Op rejected 208 ``` 209 210 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: 211 212 ```text 213 #tail -n 4 audit.log 214 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 215 t=2018-02-21T14:42:42+0100 lvl=info msg=Sign api=signer type=response data=93e6161840c3ae1efc26dc68dedab6e8fc233bb3fefa1b4645dbf6609b93dace160572ea4ab33240256bb6d3dadb60dcd9c515d6374d3cf614ee897408d41d541c error=nil 216 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 217 t=2018-02-21T14:42:56+0100 lvl=info msg=Sign api=signer type=response data= error="Request denied" 218 ```