github.com/niluplatform/go-nilu@v1.7.4-0.20200912082737-a0cb0776d52c/cmd/clef/rules.md (about) 1 # Rules 2 3 The `signer` binary contains a ruleset engine, implemented with [OttoVM](https://github.com/robertkrimen/otto) 4 5 It enables usecases like the following: 6 7 * I want to auto-approve transactions with contract `CasinoDapp`, with up to `0.05 ether` in value to maximum `1 ether` per 24h period 8 * I want to auto-approve transaction to contract `EthAlarmClock` with `data`=`0xdeadbeef`, if `value=0`, `gas < 44k` and `gasPrice < 40Gwei` 9 10 The two main features that are required for this to work well are; 11 12 1. Rule Implementation: how to create, manage and interpret rules in a flexible but secure manner 13 2. Credential managements and credentials; how to provide auto-unlock without exposing keys unnecessarily. 14 15 The section below deals with both of them 16 17 ## Rule Implementation 18 19 A ruleset file is implemented as a `js` file. Under the hood, the ruleset-engine is a `SignerUI`, implementing the same methods as the `json-rpc` methods 20 defined in the UI protocol. Example: 21 22 ```javascript 23 24 function asBig(str){ 25 if(str.slice(0,2) == "0x"){ return new BigNumber(str.slice(2),16)} 26 return new BigNumber(str) 27 } 28 29 // Approve transactions to a certain contract if value is below a certain limit 30 function ApproveTx(req){ 31 32 var limit = big.Newint("0xb1a2bc2ec50000") 33 var value = asBig(req.transaction.value); 34 35 if(req.transaction.to.toLowerCase()=="0xae967917c465db8578ca9024c205720b1a3651a9") 36 && value.lt(limit) ){ 37 return "Approve" 38 } 39 // If we return "Reject", it will be rejected. 40 // By not returning anything, it will be passed to the next UI, for manual processing 41 } 42 43 //Approve listings if request made from IPC 44 function ApproveListing(req){ 45 if (req.metadata.scheme == "ipc"){ return "Approve"} 46 } 47 48 ``` 49 50 Whenever the external API is called (and the ruleset is enabled), the `signer` calls the UI, which is an instance of a ruleset-engine. The ruleset-engine 51 invokes the corresponding method. In doing so, there are three possible outcomes: 52 53 1. JS returns "Approve" 54 * Auto-approve request 55 2. JS returns "Reject" 56 * Auto-reject request 57 3. Error occurs, or something else is returned 58 * Pass on to `next` ui: the regular UI channel. 59 60 A more advanced example can be found below, "Example 1: ruleset for a rate-limited window", using `storage` to `Put` and `Get` `string`s by key. 61 62 * At the time of writing, storage only exists as an ephemeral unencrypted implementation, to be used during testing. 63 64 ### Things to note 65 66 The Otto vm has a few [caveats](https://github.com/robertkrimen/otto): 67 68 * "use strict" will parse, but does nothing. 69 * The regular expression engine (re2/regexp) is not fully compatible with the ECMA5 specification. 70 * Otto targets ES5. ES6 features (eg: Typed Arrays) are not supported. 71 72 Additionally, a few more have been added 73 74 * The rule execution cannot load external javascript files. 75 * The only preloaded libary is [`bignumber.js`](https://github.com/MikeMcl/bignumber.js) version `2.0.3`. This one is fairly old, and is not aligned with the documentation at the github repository. 76 * Each invocation is made in a fresh virtual machine. This means that you cannot store data in global variables between invocations. This is a deliberate choice -- if you want to store data, use the disk-backed `storage`, since rules should not rely on ephemeral data. 77 * Javascript API parameters are _always_ an object. This is also a design choice, to ensure that parameters are accessed by _key_ and not by order. This is to prevent mistakes due to missing parameters or parameter changes. 78 * The JS engine has access to `storage` and `console`. 79 80 #### Security considerations 81 82 ##### Security of ruleset 83 84 Some security precautions can be made, such as: 85 86 * Never load `ruleset.js` unless the file is `readonly` (`r-??-??-?`). If the user wishes to modify the ruleset, he must make it writeable and then set back to readonly. 87 * This is to prevent attacks where files are dropped on the users disk. 88 * Since we're going to have to have some form of secure storage (not defined in this section), we could also store the `sha3` of the `ruleset.js` file in there. 89 * If the user wishes to modify the ruleset, he'd then have to perform e.g. `signer --attest /path/to/ruleset --credential <creds>` 90 91 ##### Security of implementation 92 93 The drawbacks of this very flexible solution is that the `signer` needs to contain a javascript engine. This is pretty simple to implement, since it's already 94 implemented for `geth`. There are no known security vulnerabilities in, nor have we had any security-problems with it so far. 95 96 The javascript engine would be an added attack surface; but if the validation of `rulesets` is made good (with hash-based attestation), the actual javascript cannot be considered 97 an attack surface -- if an attacker can control the ruleset, a much simpler attack would be to implement an "always-approve" rule instead of exploiting the js vm. The only benefit 98 to be gained from attacking the actual `signer` process from the `js` side would be if it could somehow extract cryptographic keys from memory. 99 100 ##### Security in usability 101 102 Javascript is flexible, but also easy to get wrong, especially when users assume that `js` can handle large integers natively. Typical errors 103 include trying to multiply `gasCost` with `gas` without using `bigint`:s. 104 105 It's unclear whether any other DSL could be more secure; since there's always the possibility of erroneously implementing a rule. 106 107 108 ## Credential management 109 110 The ability to auto-approve transaction means that the signer needs to have necessary credentials to decrypt keyfiles. These passwords are hereafter called `ksp` (keystore pass). 111 112 ### Example implementation 113 114 Upon startup of the signer, the signer is given a switch: `--seed <path/to/masterseed>` 115 The `seed` contains a blob of bytes, which is the master seed for the `signer`. 116 117 The `signer` uses the `seed` to: 118 119 * Generate the `path` where the settings are stored. 120 * `./settings/1df094eb-c2b1-4689-90dd-790046d38025/vault.dat` 121 * `./settings/1df094eb-c2b1-4689-90dd-790046d38025/rules.js` 122 * Generate the encryption password for `vault.dat`. 123 124 The `vault.dat` would be an encrypted container storing the following information: 125 126 * `ksp` entries 127 * `sha256` hash of `rules.js` 128 * Information about pair:ed callers (not yet specified) 129 130 ### Security considerations 131 132 This would leave it up to the user to ensure that the `path/to/masterseed` is handled in a secure way. It's difficult to get around this, although one could 133 imagine leveraging OS-level keychains where supported. The setup is however in general similar to how ssh-keys are stored in `.ssh/`. 134 135 136 # Implementation status 137 138 This is now implemented (with ephemeral non-encrypted storage for now, so not yet enabled). 139 140 ## Example 1: ruleset for a rate-limited window 141 142 143 ```javascript 144 145 function big(str){ 146 if(str.slice(0,2) == "0x"){ return new BigNumber(str.slice(2),16)} 147 return new BigNumber(str) 148 } 149 150 // Time window: 1 week 151 var window = 1000* 3600*24*7; 152 153 // Limit : 1 ether 154 var limit = new BigNumber("1e18"); 155 156 function isLimitOk(transaction){ 157 var value = big(transaction.value) 158 // Start of our window function 159 var windowstart = new Date().getTime() - window; 160 161 var txs = []; 162 var stored = storage.Get('txs'); 163 164 if(stored != ""){ 165 txs = JSON.parse(stored) 166 } 167 // First, remove all that have passed out of the time-window 168 var newtxs = txs.filter(function(tx){return tx.tstamp > windowstart}); 169 console.log(txs, newtxs.length); 170 171 // Secondly, aggregate the current sum 172 sum = new BigNumber(0) 173 174 sum = newtxs.reduce(function(agg, tx){ return big(tx.value).plus(agg)}, sum); 175 console.log("ApproveTx > Sum so far", sum); 176 console.log("ApproveTx > Requested", value.toNumber()); 177 178 // Would we exceed weekly limit ? 179 return sum.plus(value).lt(limit) 180 181 } 182 function ApproveTx(r){ 183 if (isLimitOk(r.transaction)){ 184 return "Approve" 185 } 186 return "Nope" 187 } 188 189 /** 190 * OnApprovedTx(str) is called when a transaction has been approved and signed. The parameter 191 * 'response_str' contains the return value that will be sent to the external caller. 192 * The return value from this method is ignore - the reason for having this callback is to allow the 193 * ruleset to keep track of approved transactions. 194 * 195 * When implementing rate-limited rules, this callback should be used. 196 * If a rule responds with neither 'Approve' nor 'Reject' - the tx goes to manual processing. If the user 197 * then accepts the transaction, this method will be called. 198 * 199 * TLDR; Use this method to keep track of signed transactions, instead of using the data in ApproveTx. 200 */ 201 function OnApprovedTx(resp){ 202 var value = big(resp.tx.value) 203 var txs = [] 204 // Load stored transactions 205 var stored = storage.Get('txs'); 206 if(stored != ""){ 207 txs = JSON.parse(stored) 208 } 209 // Add this to the storage 210 txs.push({tstamp: new Date().getTime(), value: value}); 211 storage.Put("txs", JSON.stringify(txs)); 212 } 213 214 ``` 215 216 ## Example 2: allow destination 217 218 ```javascript 219 220 function ApproveTx(r){ 221 if(r.transaction.from.toLowerCase()=="0x0000000000000000000000000000000000001337"){ return "Approve"} 222 if(r.transaction.from.toLowerCase()=="0x000000000000000000000000000000000000dead"){ return "Reject"} 223 // Otherwise goes to manual processing 224 } 225 226 ``` 227 228 ## Example 3: Allow listing 229 230 ```javascript 231 232 function ApproveListing(){ 233 return "Approve" 234 } 235 236 ```