github.com/mprishchepo/go-ethereum@v1.9.7-0.20191031044858-21506be82b68/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  ```js
    23  function asBig(str) {
    24  	if (str.slice(0, 2) == "0x") {
    25  		return new BigNumber(str.slice(2), 16)
    26  	}
    27  	return new BigNumber(str)
    28  }
    29  
    30  // Approve transactions to a certain contract if value is below a certain limit
    31  function ApproveTx(req) {
    32  	var limit = big.Newint("0xb1a2bc2ec50000")
    33  	var value = asBig(req.transaction.value);
    34  
    35  	if (req.transaction.to.toLowerCase() == "0xae967917c465db8578ca9024c205720b1a3651a9") && value.lt(limit)) {
    36  		return "Approve"
    37  	}
    38  	// If we return "Reject", it will be rejected.
    39  	// By not returning anything, it will be passed to the next UI, for manual processing
    40  }
    41  
    42  // Approve listings if request made from IPC
    43  function ApproveListing(req){
    44      if (req.metadata.scheme == "ipc"){ return "Approve"}
    45  }
    46  ```
    47  
    48  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
    49  invokes the corresponding method. In doing so, there are three possible outcomes:
    50  
    51  1. JS returns "Approve"
    52    * Auto-approve request
    53  2. JS returns "Reject"
    54    * Auto-reject request
    55  3. Error occurs, or something else is returned
    56    * Pass on to `next` ui: the regular UI channel.
    57  
    58  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.
    59  
    60  * At the time of writing, storage only exists as an ephemeral unencrypted implementation, to be used during testing.
    61  
    62  ### Things to note
    63  
    64  The Otto vm has a few [caveats](https://github.com/robertkrimen/otto):
    65  
    66  * "use strict" will parse, but does nothing.
    67  * The regular expression engine (re2/regexp) is not fully compatible with the ECMA5 specification.
    68  * Otto targets ES5. ES6 features (eg: Typed Arrays) are not supported.
    69  
    70  Additionally, a few more have been added
    71  
    72  * The rule execution cannot load external javascript files.
    73  * The only preloaded library 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.
    74  * 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.
    75  * 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.
    76  * The JS engine has access to `storage` and `console`.
    77  
    78  #### Security considerations
    79  
    80  ##### Security of ruleset
    81  
    82  Some security precautions can be made, such as:
    83  
    84  * 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.
    85    * This is to prevent attacks where files are dropped on the users disk.
    86  * 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.
    87    * If the user wishes to modify the ruleset, he'd then have to perform e.g. `signer --attest /path/to/ruleset --credential <creds>`
    88  
    89  ##### Security of implementation
    90  
    91  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
    92  implemented for `geth`. There are no known security vulnerabilities in, nor have we had any security-problems with it so far.
    93  
    94  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
    95  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
    96  to be gained from attacking the actual `signer` process from the `js` side would be if it could somehow extract cryptographic keys from memory.
    97  
    98  ##### Security in usability
    99  
   100  Javascript is flexible, but also easy to get wrong, especially when users assume that `js` can handle large integers natively. Typical errors
   101  include trying to multiply `gasCost` with `gas` without using `bigint`:s.
   102  
   103  It's unclear whether any other DSL could be more secure; since there's always the possibility of erroneously implementing a rule.
   104  
   105  
   106  ## Credential management
   107  
   108  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).
   109  
   110  ### Example implementation
   111  
   112  Upon startup of the signer, the signer is given a switch: `--seed <path/to/masterseed>`
   113  The `seed` contains a blob of bytes, which is the master seed for the `signer`.
   114  
   115  The `signer` uses the `seed` to:
   116  
   117  * Generate the `path` where the settings are stored.
   118    * `./settings/1df094eb-c2b1-4689-90dd-790046d38025/vault.dat`
   119    * `./settings/1df094eb-c2b1-4689-90dd-790046d38025/rules.js`
   120  * Generate the encryption password for `vault.dat`.
   121  
   122  The `vault.dat` would be an encrypted container storing the following information:
   123  
   124  * `ksp` entries
   125  * `sha256` hash of `rules.js`
   126  * Information about pair:ed callers (not yet specified)
   127  
   128  ### Security considerations
   129  
   130  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
   131  imagine leveraging OS-level keychains where supported. The setup is however in general similar to how ssh-keys are  stored in `.ssh/`.
   132  
   133  
   134  # Implementation status
   135  
   136  This is now implemented (with ephemeral non-encrypted storage for now, so not yet enabled).
   137  
   138  ## Example 1: ruleset for a rate-limited window
   139  
   140  
   141  ```js
   142  function big(str) {
   143  	if (str.slice(0, 2) == "0x") {
   144  		return new BigNumber(str.slice(2), 16)
   145  	}
   146  	return new BigNumber(str)
   147  }
   148  
   149  // Time window: 1 week
   150  var window = 1000* 3600*24*7;
   151  
   152  // Limit : 1 ether
   153  var limit = new BigNumber("1e18");
   154  
   155  function isLimitOk(transaction) {
   156  	var value = big(transaction.value)
   157  	// Start of our window function
   158  	var windowstart = new Date().getTime() - window;
   159  
   160  	var txs = [];
   161  	var stored = storage.get('txs');
   162  
   163  	if (stored != "") {
   164  		txs = JSON.parse(stored)
   165  	}
   166  	// First, remove all that have passed out of the time-window
   167  	var newtxs = txs.filter(function(tx){return tx.tstamp > windowstart});
   168  	console.log(txs, newtxs.length);
   169  
   170  	// Secondly, aggregate the current sum
   171  	sum = new BigNumber(0)
   172  
   173  	sum = newtxs.reduce(function(agg, tx){ return big(tx.value).plus(agg)}, sum);
   174  	console.log("ApproveTx > Sum so far", sum);
   175  	console.log("ApproveTx > Requested", value.toNumber());
   176  
   177  	// Would we exceed weekly limit ?
   178  	return sum.plus(value).lt(limit)
   179  
   180  }
   181  function ApproveTx(r) {
   182  	if (isLimitOk(r.transaction)) {
   183  		return "Approve"
   184  	}
   185  	return "Nope"
   186  }
   187  
   188  /**
   189  * OnApprovedTx(str) is called when a transaction has been approved and signed. The parameter
   190  	* 'response_str' contains the return value that will be sent to the external caller.
   191  * The return value from this method is ignore - the reason for having this callback is to allow the
   192  * ruleset to keep track of approved transactions.
   193  *
   194  * When implementing rate-limited rules, this callback should be used.
   195  * If a rule responds with neither 'Approve' nor 'Reject' - the tx goes to manual processing. If the user
   196  * then accepts the transaction, this method will be called.
   197  *
   198  * TLDR; Use this method to keep track of signed transactions, instead of using the data in ApproveTx.
   199  */
   200  function OnApprovedTx(resp) {
   201  	var value = big(resp.tx.value)
   202  	var txs = []
   203  	// Load stored transactions
   204  	var stored = storage.get('txs');
   205  	if (stored != "") {
   206  		txs = JSON.parse(stored)
   207  	}
   208  	// Add this to the storage
   209  	txs.push({tstamp: new Date().getTime(), value: value});
   210  	storage.put("txs", JSON.stringify(txs));
   211  }
   212  ```
   213  
   214  ## Example 2: allow destination
   215  
   216  ```js
   217  function ApproveTx(r) {
   218  	if (r.transaction.from.toLowerCase() == "0x0000000000000000000000000000000000001337") {
   219  		return "Approve"
   220  	}
   221  	if (r.transaction.from.toLowerCase() == "0x000000000000000000000000000000000000dead") {
   222  		return "Reject"
   223  	}
   224  	// Otherwise goes to manual processing
   225  }
   226  ```
   227  
   228  ## Example 3: Allow listing
   229  
   230  ```js
   231  function ApproveListing() {
   232  	return "Approve"
   233  }
   234  ```