github.com/aigarnetwork/aigar@v0.0.0-20191115204914-d59a6eb70f8e/cmd/clef/README.md (about) 1 # Clef 2 3 Clef can be used to sign transactions and data and is meant as a(n eventual) replacement for Geth's account management. This allows DApps to not depend on Geth's account management. When a DApp wants to sign data (or a transaction), it can send the content to Clef, which will then provide the user with context and asks for permission to sign the content. If the users grants the signing request, Clef will send the signature back to the DApp. 4 5 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 an untrusted remote Ethereum node, because a local one is not available, not synchronised with the chain, or is a node that has no built-in (or limited) account management. 6 7 Clef can run as a daemon on the same machine, off a usb-stick like [USB armory](https://inversepath.com/usbarmory), or even a separate VM in a [QubesOS](https://www.qubes-os.org/) type setup. 8 9 Check out the 10 11 * [CLI tutorial](tutorial.md) for some concrete examples on how Clef works. 12 * [Setup docs](docs/setup.md) for infos on how to configure Clef on QubesOS or USB Armory. 13 * [Data types](datatypes.md) for details on the communication messages between Clef and an external UI. 14 15 ## Command line flags 16 17 Clef accepts the following command line options: 18 19 ``` 20 COMMANDS: 21 init Initialize the signer, generate secret storage 22 attest Attest that a js-file is to be used 23 setpw Store a credential for a keystore file 24 delpw Remove a credential for a keystore file 25 gendoc Generate documentation about json-rpc format 26 help Shows a list of commands or help for one command 27 28 GLOBAL OPTIONS: 29 --loglevel value log level to emit to the screen (default: 4) 30 --keystore value Directory for the keystore (default: "$HOME/.ethereum/keystore") 31 --configdir value Directory for Clef configuration (default: "$HOME/.clef") 32 --chainid value Chain id to use for signing (1=mainnet, 3=Ropsten, 4=Rinkeby, 5=Goerli) (default: 1) 33 --lightkdf Reduce key-derivation RAM & CPU usage at some expense of KDF strength 34 --nousb Disables monitoring for and managing USB hardware wallets 35 --pcscdpath value Path to the smartcard daemon (pcscd) socket file (default: "/run/pcscd/pcscd.comm") 36 --rpcaddr value HTTP-RPC server listening interface (default: "localhost") 37 --rpcvhosts value Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost") 38 --ipcdisable Disable the IPC-RPC server 39 --ipcpath Filename for IPC socket/pipe within the datadir (explicit paths escape it) 40 --rpc Enable the HTTP-RPC server 41 --rpcport value HTTP-RPC server listening port (default: 8550) 42 --signersecret value A file containing the (encrypted) master seed to encrypt Clef data, e.g. keystore credentials and ruleset hash 43 --4bytedb-custom value File used for writing new 4byte-identifiers submitted via API (default: "./4byte-custom.json") 44 --auditlog value File used to emit audit logs. Set to "" to disable (default: "audit.log") 45 --rules value Path to the rule file to auto-authorize requests with 46 --stdio-ui Use STDIN/STDOUT as a channel for an external UI. This means that an STDIN/STDOUT is used for RPC-communication with a e.g. a graphical user interface, and can be used when Clef is started by an external process. 47 --stdio-ui-test Mechanism to test interface between Clef and UI. Requires 'stdio-ui'. 48 --advanced If enabled, issues warnings instead of rejections for suspicious requests. Default off 49 --help, -h show help 50 --version, -v print the version 51 ``` 52 53 Example: 54 55 ``` 56 $ clef -keystore /my/keystore -chainid 4 57 ``` 58 59 ## Security model 60 61 The security model of Clef is as follows: 62 63 * One critical component (the Clef binary / daemon) is responsible for handling cryptographic operations: signing, private keys, encryption/decryption of keystore files. 64 * Clef has a well-defined 'external' API. 65 * The 'external' API is considered UNTRUSTED. 66 * Clef also communicates with whatever process that invoked the binary, via stdin/stdout. 67 * This channel is considered 'trusted'. Over this channel, approvals and passwords are communicated. 68 69 The general flow for signing a transaction using e.g. Geth is as follows: 70  71 72 In this case, `geth` would be started with `--signer http://localhost:8550` and would relay requests to `eth.sendTransaction`. 73 74 ## TODOs 75 76 Some snags and todos 77 78 * [ ] Clef should take a startup param "--no-change", for UIs that do not contain the capability to perform changes to things, only approve/deny. Such a UI should be able to start the signer in a more secure mode by telling it that it only wants approve/deny capabilities. 79 * [x] It would be nice if Clef could collect new 4byte-id:s/method selectors, and have a secondary database for those (`4byte_custom.json`). Users could then (optionally) submit their collections for inclusion upstream. 80 * [ ] It should be possible to configure Clef to check if an account is indeed known to it, before passing on to the UI. The reason it currently does not, is that it would make it possible to enumerate accounts if it immediately returned "unknown account" (side channel attack). 81 * [x] It should be possible to configure Clef to auto-allow listing (certain) accounts, instead of asking every time. 82 * [x] Done Upon startup, Clef should spit out some info to the caller (particularly important when executed in `stdio-ui`-mode), invoking methods with the following info: 83 * [x] Version info about the signer 84 * [x] Address of API (HTTP/IPC) 85 * [ ] List of known accounts 86 * [ ] Have a default timeout on signing operations, so that if the user has not answered within e.g. 60 seconds, the request is rejected. 87 * [ ] `account_signRawTransaction` 88 * [ ] `account_bulkSignTransactions([] transactions)` should 89 * only exist if enabled via config/flag 90 * only allow non-data-sending transactions 91 * all txs must use the same `from`-account 92 * let the user confirm, showing 93 * the total amount 94 * the number of unique recipients 95 96 * Geth todos 97 - The signer should pass the `Origin` header as call-info to the UI. As of right now, the way that info about the request is put together is a bit of a hack into the HTTP server. This could probably be greatly improved. 98 - Relay: Geth should be started in `geth --signer localhost:8550`. 99 - Currently, the Geth APIs use `common.Address` in the arguments to transaction submission (e.g `to` field). This type is 20 `bytes`, and is incapable of carrying checksum information. The signer uses `common.MixedcaseAddress`, which retains the original input. 100 - The Geth API should switch to use the same type, and relay `to`-account verbatim to the external API. 101 * [x] Storage 102 * [x] An encrypted key-value storage should be implemented. 103 * See [rules.md](rules.md) for more info about this. 104 * Another potential thing to introduce is pairing. 105 * To prevent spurious requests which users just accept, implement a way to "pair" the caller with the signer (external API). 106 * Thus Geth/cpp would cryptographically handshake and afterwards the caller would be allowed to make signing requests. 107 * This feature would make the addition of rules less dangerous. 108 109 * Wallets / accounts. Add API methods for wallets. 110 111 ## Communication 112 113 ### External API 114 115 Clef listens to HTTP requests on `rpcaddr`:`rpcport` (or to IPC on `ipcpath`), with the same JSON-RPC standard as Geth. The messages are expected to be [JSON-RPC 2.0 standard](https://www.jsonrpc.org/specification). 116 117 Some of these call can require user interaction. Clients must be aware that responses may be delayed significantly or may never be received if a users decides to ignore the confirmation request. 118 119 The External API is **untrusted**: it does not accept credentials over this API, nor does it expect that requests have any authority. 120 121 ### Internal UI API 122 123 Clef has one native console-based UI, for operation without any standalone tools. However, there is also an API to communicate with an external UI. To enable that UI, the signer needs to be executed with the `--stdio-ui` option, which allocates `stdin` / `stdout` for the UI API. 124 125 An example (insecure) proof-of-concept of has been implemented in `pythonsigner.py`. 126 127 The model is as follows: 128 129 * The user starts the UI app (`pythonsigner.py`). 130 * The UI app starts `clef` with `--stdio-ui`, and listens to the 131 process output for confirmation-requests. 132 * `clef` opens the external HTTP API. 133 * When the `signer` receives requests, it sends a JSON-RPC request via `stdout`. 134 * The UI app prompts the user accordingly, and responds to `clef`. 135 * `clef` signs (or not), and responds to the original request. 136 137 ## External API 138 139 See the [external API changelog](extapi_changelog.md) for information about changes to this API. 140 141 ### Encoding 142 - number: positive integers that are hex encoded 143 - data: hex encoded data 144 - string: ASCII string 145 146 All hex encoded values must be prefixed with `0x`. 147 148 ## Methods 149 150 ### account_new 151 152 #### Create new password protected account 153 154 The signer will generate a new private key, encrypts it according to [web3 keystore spec](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) and stores it in the keystore directory. 155 The client is responsible for creating a backup of the keystore. If the keystore is lost there is no method of retrieving lost accounts. 156 157 #### Arguments 158 159 None 160 161 #### Result 162 - address [string]: account address that is derived from the generated key 163 - url [string]: location of the keyfile 164 165 #### Sample call 166 ```json 167 { 168 "id": 0, 169 "jsonrpc": "2.0", 170 "method": "account_new", 171 "params": [] 172 } 173 ``` 174 Response 175 ``` 176 { 177 "id": 0, 178 "jsonrpc": "2.0", 179 "result": { 180 "address": "0xbea9183f8f4f03d427f6bcea17388bdff1cab133", 181 "url": "keystore:///my/keystore/UTC--2017-08-24T08-40-15.419655028Z--bea9183f8f4f03d427f6bcea17388bdff1cab133" 182 } 183 } 184 ``` 185 186 ### account_list 187 188 #### List available accounts 189 List all accounts that this signer currently manages 190 191 #### Arguments 192 193 None 194 195 #### Result 196 - array with account records: 197 - account.address [string]: account address that is derived from the generated key 198 - account.type [string]: type of the 199 - account.url [string]: location of the account 200 201 #### Sample call 202 ```json 203 { 204 "id": 1, 205 "jsonrpc": "2.0", 206 "method": "account_list" 207 } 208 ``` 209 Response 210 ``` 211 { 212 "id": 1, 213 "jsonrpc": "2.0", 214 "result": [ 215 { 216 "address": "0xafb2f771f58513609765698f65d3f2f0224a956f", 217 "type": "account", 218 "url": "keystore:///tmp/keystore/UTC--2017-08-24T07-26-47.162109726Z--afb2f771f58513609765698f65d3f2f0224a956f" 219 }, 220 { 221 "address": "0xbea9183f8f4f03d427f6bcea17388bdff1cab133", 222 "type": "account", 223 "url": "keystore:///tmp/keystore/UTC--2017-08-24T08-40-15.419655028Z--bea9183f8f4f03d427f6bcea17388bdff1cab133" 224 } 225 ] 226 } 227 ``` 228 229 ### account_signTransaction 230 231 #### Sign transactions 232 Signs a transactions and responds with the signed transaction in RLP encoded form. 233 234 #### Arguments 235 2. transaction object: 236 - `from` [address]: account to send the transaction from 237 - `to` [address]: receiver account. If omitted or `0x`, will cause contract creation. 238 - `gas` [number]: maximum amount of gas to burn 239 - `gasPrice` [number]: gas price 240 - `value` [number:optional]: amount of Wei to send with the transaction 241 - `data` [data:optional]: input data 242 - `nonce` [number]: account nonce 243 3. method signature [string:optional] 244 - The method signature, if present, is to aid decoding the calldata. Should consist of `methodname(paramtype,...)`, e.g. `transfer(uint256,address)`. The signer may use this data to parse the supplied calldata, and show the user. The data, however, is considered totally untrusted, and reliability is not expected. 245 246 247 #### Result 248 - signed transaction in RLP encoded form [data] 249 250 #### Sample call 251 ```json 252 { 253 "id": 2, 254 "jsonrpc": "2.0", 255 "method": "account_signTransaction", 256 "params": [ 257 { 258 "from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db", 259 "gas": "0x55555", 260 "gasPrice": "0x1234", 261 "input": "0xabcd", 262 "nonce": "0x0", 263 "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0", 264 "value": "0x1234" 265 } 266 ] 267 } 268 ``` 269 Response 270 271 ```json 272 { 273 "id": 2, 274 "jsonrpc": "2.0", 275 "error": { 276 "code": -32000, 277 "message": "Request denied" 278 } 279 } 280 ``` 281 #### Sample call with ABI-data 282 283 284 ```json 285 { 286 "id": 67, 287 "jsonrpc": "2.0", 288 "method": "account_signTransaction", 289 "params": [ 290 { 291 "from": "0x694267f14675d7e1b9494fd8d72fefe1755710fa", 292 "gas": "0x333", 293 "gasPrice": "0x1", 294 "nonce": "0x0", 295 "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0", 296 "value": "0x0", 297 "data": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012" 298 }, 299 "safeSend(address)" 300 ] 301 } 302 ``` 303 Response 304 305 ```json 306 { 307 "jsonrpc": "2.0", 308 "id": 67, 309 "result": { 310 "raw": "0xf88380018203339407a565b7ed7d7a678680a4c162885bedbb695fe080a44401a6e4000000000000000000000000000000000000000000000000000000000000001226a0223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20ea02aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663", 311 "tx": { 312 "nonce": "0x0", 313 "gasPrice": "0x1", 314 "gas": "0x333", 315 "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0", 316 "value": "0x0", 317 "input": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012", 318 "v": "0x26", 319 "r": "0x223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20e", 320 "s": "0x2aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663", 321 "hash": "0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e" 322 } 323 } 324 } 325 ``` 326 327 Bash example: 328 ```bash 329 #curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"account_signTransaction","params":[{"from":"0x694267f14675d7e1b9494fd8d72fefe1755710fa","gas":"0x333","gasPrice":"0x1","nonce":"0x0","to":"0x07a565b7ed7d7a678680a4c162885bedbb695fe0", "value":"0x0", "data":"0x4401a6e40000000000000000000000000000000000000000000000000000000000000012"},"safeSend(address)"],"id":67}' http://localhost:8550/ 330 331 {"jsonrpc":"2.0","id":67,"result":{"raw":"0xf88380018203339407a565b7ed7d7a678680a4c162885bedbb695fe080a44401a6e4000000000000000000000000000000000000000000000000000000000000001226a0223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20ea02aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663","tx":{"nonce":"0x0","gasPrice":"0x1","gas":"0x333","to":"0x07a565b7ed7d7a678680a4c162885bedbb695fe0","value":"0x0","input":"0x4401a6e40000000000000000000000000000000000000000000000000000000000000012","v":"0x26","r":"0x223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20e","s":"0x2aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663","hash":"0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e"}}} 332 ``` 333 334 ### account_signData 335 336 #### Sign data 337 Signs a chunk of data and returns the calculated signature. 338 339 #### Arguments 340 - content type [string]: type of signed data 341 - `text/validator`: hex data with custom validator defined in a contract 342 - `application/clique`: [clique](https://github.com/ethereum/EIPs/issues/225) headers 343 - `text/plain`: simple hex data validated by `account_ecRecover` 344 - account [address]: account to sign with 345 - data [object]: data to sign 346 347 #### Result 348 - calculated signature [data] 349 350 #### Sample call 351 ```json 352 { 353 "id": 3, 354 "jsonrpc": "2.0", 355 "method": "account_signData", 356 "params": [ 357 "data/plain", 358 "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db", 359 "0xaabbccdd" 360 ] 361 } 362 ``` 363 Response 364 365 ```json 366 { 367 "id": 3, 368 "jsonrpc": "2.0", 369 "result": "0x5b6693f153b48ec1c706ba4169960386dbaa6903e249cc79a8e6ddc434451d417e1e57327872c7f538beeb323c300afa9999a3d4a5de6caf3be0d5ef832b67ef1c" 370 } 371 ``` 372 373 ### account_signTypedData 374 375 #### Sign data 376 Signs a chunk of structured data conformant to [EIP712]([EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md)) and returns the calculated signature. 377 378 #### Arguments 379 - account [address]: account to sign with 380 - data [object]: data to sign 381 382 #### Result 383 - calculated signature [data] 384 385 #### Sample call 386 ```json 387 { 388 "id": 68, 389 "jsonrpc": "2.0", 390 "method": "account_signTypedData", 391 "params": [ 392 "0xcd2a3d9f938e13cd947ec05abc7fe734df8dd826", 393 { 394 "types": { 395 "EIP712Domain": [ 396 { 397 "name": "name", 398 "type": "string" 399 }, 400 { 401 "name": "version", 402 "type": "string" 403 }, 404 { 405 "name": "chainId", 406 "type": "uint256" 407 }, 408 { 409 "name": "verifyingContract", 410 "type": "address" 411 } 412 ], 413 "Person": [ 414 { 415 "name": "name", 416 "type": "string" 417 }, 418 { 419 "name": "wallet", 420 "type": "address" 421 } 422 ], 423 "Mail": [ 424 { 425 "name": "from", 426 "type": "Person" 427 }, 428 { 429 "name": "to", 430 "type": "Person" 431 }, 432 { 433 "name": "contents", 434 "type": "string" 435 } 436 ] 437 }, 438 "primaryType": "Mail", 439 "domain": { 440 "name": "Ether Mail", 441 "version": "1", 442 "chainId": 1, 443 "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC" 444 }, 445 "message": { 446 "from": { 447 "name": "Cow", 448 "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826" 449 }, 450 "to": { 451 "name": "Bob", 452 "wallet": "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB" 453 }, 454 "contents": "Hello, Bob!" 455 } 456 } 457 ] 458 } 459 ``` 460 Response 461 462 ```json 463 { 464 "id": 1, 465 "jsonrpc": "2.0", 466 "result": "0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c" 467 } 468 ``` 469 470 ### account_ecRecover 471 472 #### Sign data 473 474 Derive the address from the account that was used to sign data with content type `text/plain` and the signature. 475 476 #### Arguments 477 - data [data]: data that was signed 478 - signature [data]: the signature to verify 479 480 #### Result 481 - derived account [address] 482 483 #### Sample call 484 ```json 485 { 486 "id": 4, 487 "jsonrpc": "2.0", 488 "method": "account_ecRecover", 489 "params": [ 490 "data/plain", 491 "0xaabbccdd", 492 "0x5b6693f153b48ec1c706ba4169960386dbaa6903e249cc79a8e6ddc434451d417e1e57327872c7f538beeb323c300afa9999a3d4a5de6caf3be0d5ef832b67ef1c" 493 ] 494 } 495 ``` 496 Response 497 498 ```json 499 { 500 "id": 4, 501 "jsonrpc": "2.0", 502 "result": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db" 503 } 504 ``` 505 506 ### account_import 507 508 #### Import account 509 Import a private key into the keystore. The imported key is expected to be encrypted according to the web3 keystore 510 format. 511 512 #### Arguments 513 - account [object]: key in [web3 keystore format](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) (retrieved with account_export) 514 515 #### Result 516 - imported key [object]: 517 - key.address [address]: address of the imported key 518 - key.type [string]: type of the account 519 - key.url [string]: key URL 520 521 #### Sample call 522 ```json 523 { 524 "id": 6, 525 "jsonrpc": "2.0", 526 "method": "account_import", 527 "params": [ 528 { 529 "address": "c7412fc59930fd90099c917a50e5f11d0934b2f5", 530 "crypto": { 531 "cipher": "aes-128-ctr", 532 "cipherparams": { 533 "iv": "401c39a7c7af0388491c3d3ecb39f532" 534 }, 535 "ciphertext": "eb045260b18dd35cd0e6d99ead52f8fa1e63a6b0af2d52a8de198e59ad783204", 536 "kdf": "scrypt", 537 "kdfparams": { 538 "dklen": 32, 539 "n": 262144, 540 "p": 1, 541 "r": 8, 542 "salt": "9a657e3618527c9b5580ded60c12092e5038922667b7b76b906496f021bb841a" 543 }, 544 "mac": "880dc10bc06e9cec78eb9830aeb1e7a4a26b4c2c19615c94acb632992b952806" 545 }, 546 "id": "09bccb61-b8d3-4e93-bf4f-205a8194f0b9", 547 "version": 3 548 } 549 ] 550 } 551 ``` 552 Response 553 554 ```json 555 { 556 "id": 6, 557 "jsonrpc": "2.0", 558 "result": { 559 "address": "0xc7412fc59930fd90099c917a50e5f11d0934b2f5", 560 "type": "account", 561 "url": "keystore:///tmp/keystore/UTC--2017-08-24T11-00-42.032024108Z--c7412fc59930fd90099c917a50e5f11d0934b2f5" 562 } 563 } 564 ``` 565 566 ### account_export 567 568 #### Export account from keystore 569 Export a private key from the keystore. The exported private key is encrypted with the original password. When the 570 key is imported later this password is required. 571 572 #### Arguments 573 - account [address]: export private key that is associated with this account 574 575 #### Result 576 - exported key, see [web3 keystore format](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) for 577 more information 578 579 #### Sample call 580 ```json 581 { 582 "id": 5, 583 "jsonrpc": "2.0", 584 "method": "account_export", 585 "params": [ 586 "0xc7412fc59930fd90099c917a50e5f11d0934b2f5" 587 ] 588 } 589 ``` 590 Response 591 592 ```json 593 { 594 "id": 5, 595 "jsonrpc": "2.0", 596 "result": { 597 "address": "c7412fc59930fd90099c917a50e5f11d0934b2f5", 598 "crypto": { 599 "cipher": "aes-128-ctr", 600 "cipherparams": { 601 "iv": "401c39a7c7af0388491c3d3ecb39f532" 602 }, 603 "ciphertext": "eb045260b18dd35cd0e6d99ead52f8fa1e63a6b0af2d52a8de198e59ad783204", 604 "kdf": "scrypt", 605 "kdfparams": { 606 "dklen": 32, 607 "n": 262144, 608 "p": 1, 609 "r": 8, 610 "salt": "9a657e3618527c9b5580ded60c12092e5038922667b7b76b906496f021bb841a" 611 }, 612 "mac": "880dc10bc06e9cec78eb9830aeb1e7a4a26b4c2c19615c94acb632992b952806" 613 }, 614 "id": "09bccb61-b8d3-4e93-bf4f-205a8194f0b9", 615 "version": 3 616 } 617 } 618 ``` 619 620 ## UI API 621 622 These methods needs to be implemented by a UI listener. 623 624 By starting the signer with the switch `--stdio-ui-test`, the signer will invoke all known methods, and expect the UI to respond with 625 denials. This can be used during development to ensure that the API is (at least somewhat) correctly implemented. 626 See `pythonsigner`, which can be invoked via `python3 pythonsigner.py test` to perform the 'denial-handshake-test'. 627 628 All methods in this API uses object-based parameters, so that there can be no mixups of parameters: each piece of data is accessed by key. 629 630 See the [ui API changelog](intapi_changelog.md) for information about changes to this API. 631 632 OBS! A slight deviation from `json` standard is in place: every request and response should be confined to a single line. 633 Whereas the `json` specification allows for linebreaks, linebreaks __should not__ be used in this communication channel, to make 634 things simpler for both parties. 635 636 ### ApproveTx / `ui_approveTx` 637 638 Invoked when there's a transaction for approval. 639 640 641 #### Sample call 642 643 Here's a method invocation: 644 ```bash 645 646 curl -i -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"account_signTransaction","params":[{"from":"0x694267f14675d7e1b9494fd8d72fefe1755710fa","gas":"0x333","gasPrice":"0x1","nonce":"0x0","to":"0x07a565b7ed7d7a678680a4c162885bedbb695fe0", "value":"0x0", "data":"0x4401a6e40000000000000000000000000000000000000000000000000000000000000012"},"safeSend(address)"],"id":67}' http://localhost:8550/ 647 ``` 648 Results in the following invocation on the UI: 649 ```json 650 651 { 652 "jsonrpc": "2.0", 653 "id": 1, 654 "method": "ui_approveTx", 655 "params": [ 656 { 657 "transaction": { 658 "from": "0x0x694267f14675d7e1b9494fd8d72fefe1755710fa", 659 "to": "0x0x07a565b7ed7d7a678680a4c162885bedbb695fe0", 660 "gas": "0x333", 661 "gasPrice": "0x1", 662 "value": "0x0", 663 "nonce": "0x0", 664 "data": "0x4401a6e40000000000000000000000000000000000000000000000000000000000000012", 665 "input": null 666 }, 667 "call_info": [ 668 { 669 "type": "WARNING", 670 "message": "Invalid checksum on to-address" 671 }, 672 { 673 "type": "Info", 674 "message": "safeSend(address: 0x0000000000000000000000000000000000000012)" 675 } 676 ], 677 "meta": { 678 "remote": "127.0.0.1:48486", 679 "local": "localhost:8550", 680 "scheme": "HTTP/1.1" 681 } 682 } 683 ] 684 } 685 686 ``` 687 688 The same method invocation, but with invalid data: 689 ```bash 690 691 curl -i -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"account_signTransaction","params":[{"from":"0x694267f14675d7e1b9494fd8d72fefe1755710fa","gas":"0x333","gasPrice":"0x1","nonce":"0x0","to":"0x07a565b7ed7d7a678680a4c162885bedbb695fe0", "value":"0x0", "data":"0x4401a6e40000000000000002000000000000000000000000000000000000000000000012"},"safeSend(address)"],"id":67}' http://localhost:8550/ 692 ``` 693 694 ```json 695 696 { 697 "jsonrpc": "2.0", 698 "id": 1, 699 "method": "ui_approveTx", 700 "params": [ 701 { 702 "transaction": { 703 "from": "0x0x694267f14675d7e1b9494fd8d72fefe1755710fa", 704 "to": "0x0x07a565b7ed7d7a678680a4c162885bedbb695fe0", 705 "gas": "0x333", 706 "gasPrice": "0x1", 707 "value": "0x0", 708 "nonce": "0x0", 709 "data": "0x4401a6e40000000000000002000000000000000000000000000000000000000000000012", 710 "input": null 711 }, 712 "call_info": [ 713 { 714 "type": "WARNING", 715 "message": "Invalid checksum on to-address" 716 }, 717 { 718 "type": "WARNING", 719 "message": "Transaction data did not match ABI-interface: WARNING: Supplied data is stuffed with extra data. \nWant 0000000000000002000000000000000000000000000000000000000000000012\nHave 0000000000000000000000000000000000000000000000000000000000000012\nfor method safeSend(address)" 720 } 721 ], 722 "meta": { 723 "remote": "127.0.0.1:48492", 724 "local": "localhost:8550", 725 "scheme": "HTTP/1.1" 726 } 727 } 728 ] 729 } 730 731 732 ``` 733 734 One which has missing `to`, but with no `data`: 735 736 737 ```json 738 739 { 740 "jsonrpc": "2.0", 741 "id": 3, 742 "method": "ui_approveTx", 743 "params": [ 744 { 745 "transaction": { 746 "from": "", 747 "to": null, 748 "gas": "0x0", 749 "gasPrice": "0x0", 750 "value": "0x0", 751 "nonce": "0x0", 752 "data": null, 753 "input": null 754 }, 755 "call_info": [ 756 { 757 "type": "CRITICAL", 758 "message": "Tx will create contract with empty code!" 759 } 760 ], 761 "meta": { 762 "remote": "signer binary", 763 "local": "main", 764 "scheme": "in-proc" 765 } 766 } 767 ] 768 } 769 ``` 770 771 ### ApproveListing / `ui_approveListing` 772 773 Invoked when a request for account listing has been made. 774 775 #### Sample call 776 777 ```json 778 779 { 780 "jsonrpc": "2.0", 781 "id": 5, 782 "method": "ui_approveListing", 783 "params": [ 784 { 785 "accounts": [ 786 { 787 "type": "Account", 788 "url": "keystore:///home/bazonk/.ethereum/keystore/UTC--2017-11-20T14-44-54.089682944Z--123409812340981234098123409812deadbeef42", 789 "address": "0x123409812340981234098123409812deadbeef42" 790 }, 791 { 792 "type": "Account", 793 "url": "keystore:///home/bazonk/.ethereum/keystore/UTC--2017-11-23T21-59-03.199240693Z--cafebabedeadbeef34098123409812deadbeef42", 794 "address": "0xcafebabedeadbeef34098123409812deadbeef42" 795 } 796 ], 797 "meta": { 798 "remote": "signer binary", 799 "local": "main", 800 "scheme": "in-proc" 801 } 802 } 803 ] 804 } 805 806 ``` 807 808 809 ### ApproveSignData / `ui_approveSignData` 810 811 #### Sample call 812 813 ```json 814 { 815 "jsonrpc": "2.0", 816 "id": 4, 817 "method": "ui_approveSignData", 818 "params": [ 819 { 820 "address": "0x123409812340981234098123409812deadbeef42", 821 "raw_data": "0x01020304", 822 "message": "\u0019Ethereum Signed Message:\n4\u0001\u0002\u0003\u0004", 823 "hash": "0x7e3a4e7a9d1744bc5c675c25e1234ca8ed9162bd17f78b9085e48047c15ac310", 824 "meta": { 825 "remote": "signer binary", 826 "local": "main", 827 "scheme": "in-proc" 828 } 829 } 830 ] 831 } 832 833 ``` 834 835 ### ShowInfo / `ui_showInfo` 836 837 The UI should show the info to the user. Does not expect response. 838 839 #### Sample call 840 841 ```json 842 { 843 "jsonrpc": "2.0", 844 "id": 9, 845 "method": "ui_showInfo", 846 "params": [ 847 { 848 "text": "Tests completed" 849 } 850 ] 851 } 852 853 ``` 854 855 ### ShowError / `ui_showError` 856 857 The UI should show the info to the user. Does not expect response. 858 859 ```json 860 861 { 862 "jsonrpc": "2.0", 863 "id": 2, 864 "method": "ShowError", 865 "params": [ 866 { 867 "text": "Testing 'ShowError'" 868 } 869 ] 870 } 871 872 ``` 873 874 ### OnApprovedTx / `ui_onApprovedTx` 875 876 `OnApprovedTx` is called when a transaction has been approved and signed. The call contains the return value that will be sent to the external caller. The return value from this method is ignored - the reason for having this callback is to allow the ruleset to keep track of approved transactions. 877 878 When implementing rate-limited rules, this callback should be used. 879 880 TLDR; Use this method to keep track of signed transactions, instead of using the data in `ApproveTx`. 881 882 ### OnSignerStartup / `ui_onSignerStartup` 883 884 This method provide the UI with information about what API version the signer uses (both internal and external) aswell as build-info and external API, 885 in k/v-form. 886 887 Example call: 888 ```json 889 890 { 891 "jsonrpc": "2.0", 892 "id": 1, 893 "method": "ui_onSignerStartup", 894 "params": [ 895 { 896 "info": { 897 "extapi_http": "http://localhost:8550", 898 "extapi_ipc": null, 899 "extapi_version": "2.0.0", 900 "intapi_version": "1.2.0" 901 } 902 } 903 ] 904 } 905 906 ``` 907 908 909 ### Rules for UI apis 910 911 A UI should conform to the following rules. 912 913 * A UI MUST NOT load any external resources that were not embedded/part of the UI package. 914 * For example, not load icons, stylesheets from the internet 915 * Not load files from the filesystem, unless they reside in the same local directory (e.g. config files) 916 * A Graphical UI MUST show the blocky-identicon for ethereum addresses. 917 * A UI MUST warn display appropriate warning if the destination-account is formatted with invalid checksum. 918 * A UI MUST NOT open any ports or services 919 * The signer opens the public port 920 * A UI SHOULD verify the permissions on the signer binary, and refuse to execute or warn if permissions allow non-user write. 921 * A UI SHOULD inform the user about the `SHA256` or `MD5` hash of the binary being executed 922 * A UI SHOULD NOT maintain a secondary storage of data, e.g. list of accounts 923 * The signer provides accounts 924 * A UI SHOULD, to the best extent possible, use static linking / bundling, so that required libraries are bundled 925 along with the UI. 926 927 928 ### UI Implementations 929 930 There are a couple of implementation for a UI. We'll try to keep this list up to date. 931 932 | Name | Repo | UI type| No external resources| Blocky support| Verifies permissions | Hash information | No secondary storage | Statically linked| Can modify parameters| 933 | ---- | ---- | -------| ---- | ---- | ---- |---- | ---- | ---- | ---- | 934 | QtSigner| https://github.com/holiman/qtsigner/| Python3/QT-based| :+1:| :+1:| :+1:| :+1:| :+1:| :x: | :+1: (partially)| 935 | GtkSigner| https://github.com/holiman/gtksigner| Python3/GTK-based| :+1:| :x:| :x:| :+1:| :+1:| :x: | :x: | 936 | Frame | https://github.com/floating/frame/commits/go-signer| Electron-based| :x:| :x:| :x:| :x:| ?| :x: | :x: | 937 | Clef UI| https://github.com/kyokan/clef-ui| Golang/QT-based| :+1:| :+1:| :x:| :+1:| :+1:| :x: | :+1: (approve tx only)|