go-ethereum/docs/_clef/Overview.md

---
title: Clef overview
---


_A reasonably secure wallet_

Goal: Accommodate arbitrary high requirements for security (through _isolation_ and _separation_), while still providing _usability_.

Clef can be used to sign transactions and data and is meant as a replacement for geth's account management.
This allows DApps not to depend on geth's account management. When a DApp wants to sign data it can send the data to
the signer, the signer will then provide the user with context and asks the user for permission to sign the data. If
the users grants the signing request the signer will send the signature back to the DApp.
  
This setup allows a DApp to connect to a remote Ethereum node and send transactions that are locally signed. This can
help in situations when a DApp is connected to a remote node because a local Ethereum node is not available, not
synchronised with the chain or a particular Ethereum node that has no built-in (or limited) account management.
  
Clef can run as a daemon on the same machine, or off a usb-stick like [usb armory](https://inversepath.com/usbarmory),
or a separate VM in a [QubesOS](https://www.qubes-os.org/) type os setup.


## More info

Check out 

* the [tutorial](Tutorial) for some concrete examples on how the signer works.
* the [setup docs](Setup) for some information on how to configure it to work on QubesOS or USBArmory. 
* more info about [rules](Rules)
* the [data types](datatypes) for detailed information on the json types used in the communication between
  clef and an external UI 

## Security model

The security model of the signer is as follows:

* One critical binary is responsible for all cryptographic ops.
* The signer has a well-defined 'external' API - **UNTRUSTED**.
* The signer also has bidirectional APIs with whoever invoked it, via stdin/stdout -- considered **TRUSTED**.
    * `clef` exposes API for the UI to consume,
    * `ui` exposes API for `clef` to consume


The basic premise being, 

* A small(ish) binary without dependencies, 
* that is deployed on a trusted (secure) machine, 
* which serves untrusted requests, 
* in a hostile (network) environment


The general flow for signing a transaction using e.g. geth is as follows:

![image](sign_flow.png)


Clef relies on __sign-what-you-see__. To provide as much context as possible, 

- It parses calldata against 4byte database of method signatures. 
- It alerts the user about the origin of the request (ip, `user-agent`,`transport`, `Origin`)


# Setup scenarios

One setup scenario is to use virtualization, e.g. within QubesOS, where to 
Clef is deployed on a non-networked machine (`ethvault` below)

![](./qubes/clef_qubes_qrexec.png)


Another option is to deploy Clef on a separate physical device, e.g. USB Armory, 
and access the CLI-UI via SSH on the interface provided by the USB ethernet 
adapter, and expose HTTP interface via tunneling. 

![](https://inversepath.com/images/usbarmory_coin_web.jpg)


## Multi-user setup

Clef can also be used in a situation where several people need to make transactions, 
and some other person (finance) does approval. 


## Architecture

Clef is divided into two parts

- Clef
- UI

Clef has a CLI natively, but a more refined UI can start `clef` in _standard-input-output-IO mode_.

---

Clef _native_ CLI user interface example:
```
--------- Transaction request-------------
to:    0x8A8eAFb1cf62BfBeb1741769DAE1a9dd47996192
from:     0x8A8eAFb1cf62BfBeb1741769DAE1a9dd47996192 [chksum ok]
value:    1 wei
gas:      0x1 (1)
gasprice: 1 wei
nonce:    0x1 (1)

Request context:
	127.0.0.1:59870 -> HTTP/1.1 -> localhost:8550

Additional HTTP header data, provided by the external caller:
	User-Agent: Go-http-client/1.1
	Origin: 
-------------------------------------------
Approve? [y/N]:
> y
Enter password to approve:
```

`clef` will invoke API-methods on the UI whenever an action is required. 

- `ui_ApproveTx`
- `ui_ApproveListing`
- ...

This is called the `internal api`, or `ui-api`. 

![](clef_architecture_pt1.png)

![](clef_architecture_pt2.png)

### Rules

Historically, a user who wanted an easy way to sign transactions repeatedly, would
use some variant of `personal.unlock`. That is a very insecure way of managing 
accounts, and is not present in Clef. Clef instead implements Rules, which can 
be customized to provide the same type of ease of use, but with much higher
security-guarantees. 

Examples of rules:

* "I want to allow transactions with contract `CasinoDapp`, with up to `0.05 ether` in value to maximum `1 ether` per 24h period"
* "I want to allow transaction to contract `EthAlarmClock` with `data`=`0xdeadbeef`, if `value=0`, `gas < 44k` and `gasPrice < 40Gwei`"

Clef comes with a Javascript VM which can evaluate a ruleset file. The ruleset
file has access to the same interface that an external UI would have. 

#### Example 1: Allow listing

```javascript
    function ApproveListing(){
        return "Approve"
    }
```

---

#### Example 2: Allow destination

```javascript
function ApproveTx(r){
        var ok = "0x0000000000000000000000000000000000001337";
        var nope = "0x000000000000000000000000000000000000dead";
        if(r.transaction.from.toLowerCase()== ok){ 
            return "Approve"
        }
        if(r.transaction.from.toLowerCase()==nope){ 
            return "Reject"
        }
	// Otherwise goes to manual processing
}
```

---

#### Example 3: a rate-limited window


```javascript
	function big(str){
		if(str.slice(0,2) == "0x"){ return new BigNumber(str.slice(2),16)}
		return new BigNumber(str)
	}

	// Time window: 1 week
	var window = 1000* 3600*24*7;
	// Limit : 1 ether
	var limit = new BigNumber("1e18");
    
	function isLimitOk(transaction){
		var value = big(transaction.value)
		// Start of our window function
		var windowstart = new Date().getTime() - window;

		var txs = [];
		var stored = storage.Get('txs');

		if(stored != ""){
			txs = JSON.parse(stored)
		}
		// First, remove all that have passed out of the time-window
		var newtxs = txs.filter(function(tx){return tx.tstamp > windowstart});
		console.log(txs, newtxs.length);
		// Secondly, aggregate the current sum
		sum = new BigNumber(0)
		sum = newtxs.reduce(function(agg, tx){ return big(tx.value).plus(agg)}, sum);
		// Would we exceed weekly limit ?
		return sum.plus(value).lt(limit)

	}
	function ApproveTx(r){
		if (isLimitOk(r.transaction)){
			return "Approve"
		}
		return "Nope"
	}

	/**
	* OnApprovedTx(str) is called when a transaction has been approved and signed. 
	*/
 	function OnApprovedTx(resp){
		var value = big(resp.tx.value)
		var txs = []
		// Load stored transactions
		var stored = storage.Get('txs');
		if(stored != ""){
			txs = JSON.parse(stored)
		}
		// Add this to the storage
		txs.push({tstamp: new Date().getTime(), value: value});
		storage.Put("txs", JSON.stringify(txs));
	}

```

### A note about passwords...

In normal mode, passwords are supplied via UI. 
In order to use rules, keystore passwords must be stored in `clef`. Clef uses an encrypted container to store 

- Keystore passwords
- SHA256 hash of ruleset file
- Key/value pairs accessible to the Javascript ruleset implementation
  - This, in turn, enables the ruleset files to save data and thus implement
  things like the rate-limited window.
  
---
## External UIs

The `clef` daemon can be wrapped by an external process, which can then take
the part of a UI. 

![](clef_architecture_pt3.png)
QT UI on Ubuntu
![](https://raw.githubusercontent.com/holiman/qtsigner/master/screenshot.png)

GTK UI on Qubes

![](https://raw.githubusercontent.com/ethereum/go-ethereum/master/cmd/clef/docs/qubes/qubes_newaccount-2.png)

### Rules for UI apis

A UI should conform to the following rules.

* A UI MUST NOT load any external resources that were not embedded/part of the UI package.
  * For example, not load icons, stylesheets from the internet
  * Not load files from the filesystem, unless they reside in the same local directory (e.g. config files)
* A Graphical UI MUST show the blocky-identicon for ethereum addresses.
* A UI MUST warn display approproate warning if the destination-account is formatted with invalid checksum.
* A UI MUST NOT open any ports or services
  * The signer opens the public port
* A UI SHOULD verify the permissions on the signer binary, and refuse to execute or warn if permissions allow non-user write.
* A UI SHOULD inform the user about the `SHA256` or `MD5` hash of the binary being executed
* A UI SHOULD NOT maintain a secondary storage of data, e.g. list of accounts
  * The signer provides accounts
* A UI SHOULD, to the best extent possible, use static linking / bundling, so that required libraries are bundled
along with the UI.


### UI Implementations 

There are a couple of implementation for a UI. We'll try to keep this list up to date. Currently, none of these are finished. 

| Name | Repo | UI type| No external resources| Blocky support| Verifies permissions | Hash information | No secondary storage | Statically linked| Can modify parameters|
| ---- | ---- | -------| ---- | ---- | ---- |---- | ---- | ---- | ---- |
| QtSigner| https://github.com/holiman/qtsigner/| Python3/QT-based| :+1:| :+1:| :+1:| :+1:| :+1:| :x: |  :+1: (partially)|
| GtkSigner| https://github.com/holiman/gtksigner| Python3/GTK-based| :+1:| :x:| :x:| :+1:| :+1:| :x: |  :x: |
| Frame | https://github.com/floating/frame/commits/go-signer| Electron-based| :x:| :x:| :x:| :x:| ?| :x: |  :x: |
| Clef UI| https://github.com/ethereum/clef-ui| Golang/QT-based| :+1:| :+1:| :x:| :+1:| :+1:| :x: |  :+1: (approve tx only)|


## Geth integration

The `--signer` CLI option for `geth` means that `geth` can use `clef` as a 
backend signer. 

Although some things, like `personal.unlock` disappears, `clef` has otherwise
a corresponding (or exceeding) feature set:

* Full set of options for hardware interaction (derivation etc) via UI
* EIP 191/712 - signing typed data

Clef can even sign Clique headers in a private network
![](clef_architecture_pt4.png)