From a153c9b5e24d1d3c8b4b80e716a740ea08be2cbb Mon Sep 17 00:00:00 2001 From: Joe Date: Tue, 1 Nov 2022 11:03:28 +0000 Subject: [PATCH] clef version -> canonical account management page --- .../docs/fundamentals/account-management.md | 236 +++++++----------- .../fundamentals/account-management_clef.md | 198 --------------- src/pages/docs/getting-started/index.md | 6 +- 3 files changed, 89 insertions(+), 351 deletions(-) delete mode 100644 src/pages/docs/fundamentals/account-management_clef.md diff --git a/src/pages/docs/fundamentals/account-management.md b/src/pages/docs/fundamentals/account-management.md index a70a51a99f..0e547995f5 100644 --- a/src/pages/docs/fundamentals/account-management.md +++ b/src/pages/docs/fundamentals/account-management.md @@ -1,97 +1,120 @@ --- -title: Account Management +title: Account Management with Clef description: Guide to basic account management using Geth's built-in tools --- -The recommended practise for managing accounts in Geth is to use Clef. However, Geth also has its own, convenient account management tools. Eventually, these built in tools will be deprecated in favour of using Clef as the default account manager. This page describes account management using Geth's built-in tools. It is recommended to also visit the following pages that explain how to use Clef. +Geth uses an external signer called [Clef](/docs/clef/introduction) to manage accounts. This is a standalone pieve of software that runs independently of, but connects to, a Geth instance. Clef handles account creation, key management and signing transactions/data. This page explains how to use Clef to create and manage accounts for use with Geth. More information about Clef, including advanced setup options, are available in our dedicated Clef docs. -- [Getting started with Clef](/content/docs/getting_started/getting-started-with-clef.md) -- [Introduction to Clef](/content/docs/tools/Clef/Introduction.md) -- [Clef tutorial](/content/docs/tools/Clef/Tutorial.md) +## Initialize Clef -## Account command +The first time Clef is used it needs to be initialized with a master seed that unlocks Clef's secure vault and a path where the vault should be located. Clef will use the vault to store passwords for keystores, javascript auto-signing rules and hashes of rule files. To initialize Clef, pass a vault path to `clef init`, for example to store it in a new directory inside `/home/user/go-ethereum`: -Geth's `account` command is used to interact with accounts: - -``` -geth account [options...] [arguments...] +```sh +clef init /home/user/go-ethereum/clefdata ``` -The account command enables the user to create new accounts, list existing accounts, import private keys into a new account, update key formats and update the passwords that lock each account. In interactive mode, the user is prompted for passwords in the console when the `account` functions are invoked, whereas in non-interactive mode passwords to unlock accounts are saved to text files whose path is passed to Geth at startup. Non-interactive mode is only intended for use on private networks or known safe environments. +It is extremely important to remember the master seed and keep it secure. It allows access to the accounts under Clef's management. + +## Connecting Geth and Clef -The `account` subcommands are: +Clef and Geth should be started separately but with complementary configurations so that they can communicate. This requires Clef to know the `chain_id` of the network Geth will connect to so that this information can be included in any signatures. Clef also needs to know the location of the keystore where accounts are (or will be) stored. This is usually in a subdirectory inside Geth's data directory. Clef is also given a data directory which is also often placed conveniently inside Geth's data directory. To enable communication with Clef using Curl, `--http` can be passed which will start an HTTP server on `localhost:8550` by default. To start Clef configured for a Geth node connecting to the Sepolia testnet: +```sh +clef --chainid 11155111 --keystore ~/.go-ethereum/sepolia-data/keystore --configdir ~/go-ethereum/sepolia-data/clef --http ``` -COMMANDS: - list Print summary of existing accounts - new Create a new account - update Update an existing account - import Import a private key into a new account + +Clef will now start running in the terminal, beginning with a disclaimer and a prompt to click "ok": + +```terminal +WARNING! + +Clef is an account management tool. It may, like any software, contain bugs. + +Please take care to +- backup your keystore files, +- verify that the keystore(s) can be opened with your password. + +Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY +without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. See the GNU General Public License for more details. + +Enter 'ok' to proceed: +> ``` -Information about the subcommands can be displayed in the terminal using `geth account --help`. For example, for the `list` subcommand: +Geth can now be started in a separate terminal. To connect to Clef, ensure the data directory is consistent with the path provided to Clef and pass the location of the the Clef IPC file - which Clef saves to the path provided to its `--configdir` flag - in this case we set it to `~/go-ethereum/sepolia-data/clef`: +```sh +geth --sepolia --datadir sepolia --signer=sepolia-data/clef/clef.ipc ``` -$ geth account list --help -list [command options] [arguments...] -Print a short summary of all accounts +Remember that it is also necessary to have a consensus client running too, which requires `--http` and several `authrpc` values to be provided to Geth. A complete set of startup commands for the Geth-Lodestar client combinaton plus Clef is provided as an example in this [Gist](https://gist.github.com/jmcook1186/ea5de9215ecedb1b0105bcfa9c30d44c) - adapt it for different client combinations and configurations. + -OPTIONS: - --datadir "/home/.ethereum" Data directory for the databases and keystore - --keystore Directory for the keystore (default = inside the datadir) +## Interacting with Clef + +There are two modes of interaction with Clef. One is direct interaction, which is achieved by passing requests by HTTP or IPC with JSON-RPC data as defined in Clef's external API. This is the way to do things in Clef that don't require Geth, such as creating and listing accounts, or signing data offline. The other way is via Geth. With Geth started with Clef as an external signer, requests made to Geth that touch account data will route via Clef for approval. By default, the user approves or denies interactions manually by typing `y` or `n` into the Clef console when prompted, but custom rules can also be created to automate common tasks. + +### Creating accounts + +New accounts can be created using Clef's `account new` method. This generates a new key pair and adds them to the given `keystore` directory: + +```sh +clef newaccount --keystore sepolia-data/keystore ``` -## Creating new accounts +Clef will request the new password in the terminal. -New accounts can be created using `account new`. This generates a new key pair and adds them to the `keystore` directory in the `datadir`. To -create a new account in the default data directory: +The same can be achieved using raw JSON requests (this example send the request to Clef's exposed HTTP port using curl): ```shell -$ geth account new +curl -X POST --data '{"id": 0, "jsonrpc": "2.0", "method": "account_new", "params": []}' http://localhost:8550 -H "Content-Type: application/json" ``` - -This returns the following to the terminal: +The console will hang because Clef is waiting for manual approval. Switch to the Clef terminal and approve the action. Clef will prompt for a account password and then confirm the account creation in the terminal logs. A new keyfile has been added to the keystore in `go-ethereum/sepolia-data`. A JSON response is returned to the terminal the request originated from, containing the new account address in the `result` field. ```terminal -Your new account is locked with a password. Please give a password. Do not forget this password. -Passphrase: -Repeat Passphrase: -Address: {168bc315a2ee09042d83d7c5811b533620531f67} +{"jsonrpc": "2.0", "id": 0, "result": "0x168bc315a2ee09042d83d7c5811b533620531f67"} ``` It is critical to backup the account password safely and securely as it cannot be retrieved or reset. -{% include note.html content=" If the password provided on account creation is lost or forgotten, there is no way to retrive it and the account will simply stay locked forever. The password MUST be backed up safely and securely! -**IT IS CRITICAL TO BACKUP THE KEYSTORE AND REMEMBER PASSWORDS**" %} +{% include note.html content=" If the password provided on account creation is lost or forgotten, there is no way to retrive it and the account will simply stay locked forever. The password MUST be backed up safely and securely! **IT IS CRITICAL TO BACKUP THE KEYSTORE AND REMEMBER PASSWORDS**" %} The newly generated key files can be viewed in `/keystore/`. The file naming format is `UTC----
` where `date` is the date and time of key creation formatted according to [UTC 8601](https://www.iso.org/iso-8601-date-and-time-format.html) with zero time offset and seconds precise to eight decimal places. `address` is the 40 hexadecimal characters that make up the account address without a leading `0x`, for example: `UTC--2022-05-19T12-34-36.47413510Z--0b85e5a13e118466159b1e1b6a4234e5f9f784bb` -## Listing Accounts -Listing all existing accounts is achieved using the `account list` command. If the keystore is located anywhere other than the default location its path should be included with the `keystore` flag. For example, if the datadir is `some-dir`: +Note that there is also a Geth command for creating new accounts that will eventually be deprecated in favour of Clef. The following command will achieve the same as the RPC call suggested above: -```shell -geth account list --keystore some-dir/keystore +```sh +geth account new ``` -This command returns the following to the terminal for a keystore with two files: +### Listing accounts + +The accounts in the keystore can be listed to the terminal using `account_list` as follows: + +```sh +curl -X POST --data '{"id": 0, "jsonrpc": "2.0", "method": "account_list", "params": []}' http://localhost:8550 -H "Content-Type: application/json" +``` + +This returns a JSON object with the account addresses in an array in the `result` field. ```terminal -Account 0: {5afdd78bdacb56ab1dad28741ea2a0e47fe41331} keystore:///tmp/mykeystore/UTC--2017-04-28T08-46-27.437847599Z--5afdd78bdacb56ab1dad28741ea2a0e47fe41331 -Account 1: {9acb9ff906641a434803efb474c96a837756287f} keystore:///tmp/mykeystore/UTC--2017-04-28T08-46-52.180688336Z--9acb9ff906641a434803efb474c96a837756287f +{"jsonrpc": "2.0", "id": 0, "result": ["0x168bc315a2ee09042d83d7c5811b533620531f67", "0x0b85e5a13e118466159b1e1b6a4234e5f9f784bb"]} ``` The ordering of accounts when they are listed is lexicographic, but is effectively chronological based on time of creation due to the timestamp in the file name. It is safe to transfer the entire `keystore` directory or individual key files between Ethereum nodes. This is important because when accounts are added from other nodes the order of accounts in the keystore may change. It is therefore important not to rely on account indexes in scripts or code snippets. -## Importing accounts +Accounts can also be listed in the Javascript console using `eth.accounts`, which will defer to Clef for approval. + ### Import a keyfile -It is also possible to create a new account by importing a private key. For example, a user might already have some ether at an address they created using a browser wallet and now wish to use a new Geth node to interact with their funds. In this case, the private key can be exported from the browser wallet and imported into Geth. Geth requires the private key to be stored as a file which contains the private key as unencrypted -canonical elliptic curve bytes encoded into hex (i.e. plain text key without leading 0x). The new account is then saved in encrypted format, protected by a passphrase the user provides on request. As always, this passphrase must be securely and safely backed up - there is no way to retrieve or reset it if it is forgotten! +It is also possible to create an account by importing an existing private key. For example, a user might already have some ether at an address they created using a browser wallet and now wish to use a new Geth node to interact with their funds. In this case, the private key can be exported from the browser wallet and imported into Geth. It is possible to do this using Clef, but currently the method is not externally exposed and requires implementing a UI. There is a Python UI on the Geth Github that could be used as an example or it can be done using the default console UI. However, for now the most straightforward way to import an accoutn from a private key is to use Geth's `account import`. + +Geth requires the private key to be stored as a file which contains the private key as unencrypted canonical elliptic curve bytes encoded into hex (i.e. plain text key without leading 0x). The new account is then saved in encrypted format, protected by a passphrase the user provides on request. As always, this passphrase must be securely and safely backed up - there is no way to retrieve or reset it if it is forgotten! ```shell $ geth account import --datadir /some-dir ./keyfile @@ -106,7 +129,7 @@ Repeat Passphrase: Address: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d} ``` -This import/export process is not necessary for transferring accounts between Geth instances because the key files can simply be copied directly from one keystore to another. +This import/export process is **not necessary** for users transferring accounts between Geth instances because the key files can simply be copied directly from one keystore to another. It is also possible to import an account in non-interactive mode by saving the account password as plaintext in a `.txt` file and passing its path with the `--password` flag on startup. @@ -116,7 +139,7 @@ geth account import --password path/password.txt path/keyfile In this case, it is important to ensure the password file is not readable by anyone but the intended user. This can be achieved by changing the file permissions. On Linux, the following commands update the file permissions so only the current user has access: -```shell +```sh chmod 700 /path/to/password cat > /path/to/password @@ -124,31 +147,26 @@ cat > /path/to/password ### Import a presale wallet -Assuming the password is known, importing a presale wallet is very easy. The `wallet import` commands are used, passing the path to the wallet. +Assuming the password is known, importing a presale wallet is very easy. Geth's `wallet import` commands are used, passing the path to the wallet. -```shell +```sh geth wallet import /path/presale.wallet ``` ## Updating accounts -The `account update` subcommand is used to unlock an account and migrate it to the newest format. This is useful for accounts that may have been created in a format that has since been deprecated. The same command can be used to update the account password. The current password and account address are needed in order to update the account, as follows: +Clef can be used to set and remove passwords for an existing keystore file. To set a new password, pass the account address to `setpw`: -```shell -geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b +```sh +clef setpw a94f5374fce5edbc8e2a8697c15331677e6ebf0b ``` -The following will be returned to the terminal: +This will cause Clef to prompt for a new password, twice, and then the Clef master password to decrypt the keyfile. -```terminal -Unlocking account a94f5374fce5edbc8e2a8697c15331677e6ebf0b | Attempt 1/3 -Passphrase: -0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b -Account 'a94f5374fce5edbc8e2a8697c15331677e6ebf0b' unlocked. -Please give a new password. Do not forget this password. -Passphrase: -Repeat Passphrase: -0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b +Geth's `account update` subcommand can also be used to update the account password: + +```shell +geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b ``` Alternatively, in non-interactive mode the path to a password file containing the account password in unencrypted plaintext can be passed with the `--password` flag: @@ -157,104 +175,24 @@ Alternatively, in non-interactive mode the path to a password file containing th geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b --password path/password.txt ``` -Updating the account replaces the original file with a new one - this means the original file is no longer available after it has been updated. +Updating the account using `geth account update` replaces the original file with a new one - this means the original file is no longer available after it has been updated. This can be used to update a key file to the latest format. ## Unlocking accounts -In Geth, accounts are locked unless they are explicitly unlocked. If an account is intended to be used by apps connecting to Geth via RPC then it can be unlocked in non-interactive mode by passing the `--unlock` flag with a comma-separated list of account addresses (or keystore indexes) to unlock. This unlocks the accounts for one session only. Including the `--unlock` flag without any account addresses defaults to unlocking the first account -in the keystore. - -```shell -geth --unlock 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b -``` - -Geth will start and prompt the user to input the account password in the terminal. Alternatively, the user can provide a password as a text file and pass its path to `--password`: +With Clef, indiscriminate account unlocking is no longer a feature. Instead, Clef unlocks are locked until actions are explicitly approved manually by a user, unless they conform to some specific scenario that has been encoded in a ruleset. Please refer to our Clef docs for instructions for how to create rulesets. -```shell -geth --unlock 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b --password path/password.txt -``` -{% include note.html content=" By default, account **unlocking is forbidden when HTTP or Websocket access is enabled** (i.e. by passing `--http` or `ws` flag). This is because an attacker that manages to access the node via the externally-exposed HTTP/WS port can then control the unlocked account. -It is possible to force account unlock by including the `--allow-insecure-unlock` flag but this is unsafe and **not recommended** except for expert users that completely understand how it can be used safely. This is not a hypothetical risk: **there are bots that continually scan for http-enabled Ethereum nodes to attack**" %} +### Transactions -## Accounts in the Javascript console - -Account management can also be achieved in the Javascript console attached to a running Geth instance. Assuming Geth is already running, in a new terminal attach a Javascript console using the `geth.ipc` file. This file can be found in the data directory. Assuming the data directory is named `data` the console can be started using: - -```shell -geth attach data/geth.ipc -``` - -### New accounts - -New accounts can be generated using the Javascript console using `personal.newAccount()`. A new password is requested in the console and successful account creation is confirmed by the new account address being displayed. - -```shell -personal.newAccount() -``` - -Accounts can also be created by importing private keys directly in the Javascript console. The private key is passed as an unencrypted hex-encoded string to `personal.importRawKey()` along with a passphrase that will be used to encrypt the key. A new key file will be generated from the private key and saved to the keystore. - -```shell -personal.importRawKey("hexstringkey", "password") -``` - -### Listing accounts - -The `accounts` function in the `eth` namespace can be used to list the accounts that currently exist in the keystore.: - -``` -eth.accounts -``` - -or alternatively the same is achieved using: - -``` -personal.listAccounts -``` - -This returns an array of account addresses to the terminal. - -### Unlocking accounts - -To unlock an account, the `personal.unlockAccount` function can be used: - -``` -personal.unlockAccount(eth.accounts[1]) -``` - -The account passphrase is requested: - -```terminal -Unlock account 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b -Passphrase: -true -``` - -This unlocked account can now be used to sign and send transactions. it is also possible to pass the passphrase as an argument to `personal.unlockAccount()` along with a duration after which the accout will automatically re-lock (in seconds), as follows: - -```shell -personal.unlockAccount(eth.accounts[1], "passphrase", 60) -``` - -This unlocks the account for 60 seconds. However, this is not recommended because the command history is logged by the Javascript console which could compromise the security of the account. An unlocked account can be manually re-locked using `personal.lockAccount()`, passing the address as the sole argument. - -### Unlocking for transactions - -Sending transactions from the Javascript console also requires the sender account to be unlocked. There are two ways to send transactions: `eth.sendTransaction` and `personal.sendTransaction`. The difference between these two functions is that `eth.sendTransaction` requires the account to be -unlocked globally, at the node level (i.e., by unlocking it on the command line at the start of the Geth session). On the other hand, `personal.sendTransaction` takes a passphrase argument that unlocks the account temporarily in order to sign the transaction, then locks it again -immediately afterwards. For example, to send 5 ether between two accounts in the keystore: +Transactions can be sent using raw JSON requests to Geth or using `web3js` in the Javascript console. Either way, with Clef acting as the signer the transactions will not get sent until approval is given in Clef. The following code snippet shows how a transaction could be sent between two accounts in the keystore using the Javascript console. ```shell var tx = {from: eth.accounts[1], to: eth.accounts[2], value: web3.toWei(5, "ether")} -# this requires global account unlock for eth.accounts[1] +# this will hang until approval is given in the Clef console eth.sendTransaction(tx) - -# this unlocks eth.accounts[1] temporarily just to send the transaction -personal.sendTransaction(tx, "password") ``` ## Summary -This page has demonstrated how to use Geth's built-in account management tools, both on the command line and in the Javascript console. Accounts are stored encrypted by a password. It is critical that the account passwords and the keystore directory are safely and securely backed up. +This page has demonstrated how to manage accounts using Clef and Geth's account management tools. Accounts are stored encrypted by a password. It is critical that the account passwords and the keystore directory are safely and securely backed up. diff --git a/src/pages/docs/fundamentals/account-management_clef.md b/src/pages/docs/fundamentals/account-management_clef.md deleted file mode 100644 index 0e547995f5..0000000000 --- a/src/pages/docs/fundamentals/account-management_clef.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Account Management with Clef -description: Guide to basic account management using Geth's built-in tools ---- - -Geth uses an external signer called [Clef](/docs/clef/introduction) to manage accounts. This is a standalone pieve of software that runs independently of, but connects to, a Geth instance. Clef handles account creation, key management and signing transactions/data. This page explains how to use Clef to create and manage accounts for use with Geth. More information about Clef, including advanced setup options, are available in our dedicated Clef docs. - -## Initialize Clef - -The first time Clef is used it needs to be initialized with a master seed that unlocks Clef's secure vault and a path where the vault should be located. Clef will use the vault to store passwords for keystores, javascript auto-signing rules and hashes of rule files. To initialize Clef, pass a vault path to `clef init`, for example to store it in a new directory inside `/home/user/go-ethereum`: - -```sh -clef init /home/user/go-ethereum/clefdata -``` - -It is extremely important to remember the master seed and keep it secure. It allows access to the accounts under Clef's management. - -## Connecting Geth and Clef - -Clef and Geth should be started separately but with complementary configurations so that they can communicate. This requires Clef to know the `chain_id` of the network Geth will connect to so that this information can be included in any signatures. Clef also needs to know the location of the keystore where accounts are (or will be) stored. This is usually in a subdirectory inside Geth's data directory. Clef is also given a data directory which is also often placed conveniently inside Geth's data directory. To enable communication with Clef using Curl, `--http` can be passed which will start an HTTP server on `localhost:8550` by default. To start Clef configured for a Geth node connecting to the Sepolia testnet: - -```sh -clef --chainid 11155111 --keystore ~/.go-ethereum/sepolia-data/keystore --configdir ~/go-ethereum/sepolia-data/clef --http -``` - -Clef will now start running in the terminal, beginning with a disclaimer and a prompt to click "ok": - -```terminal -WARNING! - -Clef is an account management tool. It may, like any software, contain bugs. - -Please take care to -- backup your keystore files, -- verify that the keystore(s) can be opened with your password. - -Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY -without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR -PURPOSE. See the GNU General Public License for more details. - -Enter 'ok' to proceed: -> -``` - -Geth can now be started in a separate terminal. To connect to Clef, ensure the data directory is consistent with the path provided to Clef and pass the location of the the Clef IPC file - which Clef saves to the path provided to its `--configdir` flag - in this case we set it to `~/go-ethereum/sepolia-data/clef`: - -```sh -geth --sepolia --datadir sepolia --signer=sepolia-data/clef/clef.ipc -``` - -Remember that it is also necessary to have a consensus client running too, which requires `--http` and several `authrpc` values to be provided to Geth. A complete set of startup commands for the Geth-Lodestar client combinaton plus Clef is provided as an example in this [Gist](https://gist.github.com/jmcook1186/ea5de9215ecedb1b0105bcfa9c30d44c) - adapt it for different client combinations and configurations. - - -## Interacting with Clef - -There are two modes of interaction with Clef. One is direct interaction, which is achieved by passing requests by HTTP or IPC with JSON-RPC data as defined in Clef's external API. This is the way to do things in Clef that don't require Geth, such as creating and listing accounts, or signing data offline. The other way is via Geth. With Geth started with Clef as an external signer, requests made to Geth that touch account data will route via Clef for approval. By default, the user approves or denies interactions manually by typing `y` or `n` into the Clef console when prompted, but custom rules can also be created to automate common tasks. - -### Creating accounts - -New accounts can be created using Clef's `account new` method. This generates a new key pair and adds them to the given `keystore` directory: - -```sh -clef newaccount --keystore sepolia-data/keystore -``` - -Clef will request the new password in the terminal. - -The same can be achieved using raw JSON requests (this example send the request to Clef's exposed HTTP port using curl): - -```shell -curl -X POST --data '{"id": 0, "jsonrpc": "2.0", "method": "account_new", "params": []}' http://localhost:8550 -H "Content-Type: application/json" -``` -The console will hang because Clef is waiting for manual approval. Switch to the Clef terminal and approve the action. Clef will prompt for a account password and then confirm the account creation in the terminal logs. A new keyfile has been added to the keystore in `go-ethereum/sepolia-data`. A JSON response is returned to the terminal the request originated from, containing the new account address in the `result` field. - -```terminal -{"jsonrpc": "2.0", "id": 0, "result": "0x168bc315a2ee09042d83d7c5811b533620531f67"} -``` - -It is critical to backup the account password safely and securely as it cannot be retrieved or reset. - -{% include note.html content=" If the password provided on account creation is lost or forgotten, there is no way to retrive it and the account will simply stay locked forever. The password MUST be backed up safely and securely! **IT IS CRITICAL TO BACKUP THE KEYSTORE AND REMEMBER PASSWORDS**" %} - -The newly generated key files can be viewed in `/keystore/`. The file naming format is `UTC----
` where `date` is the date and time of key creation formatted according to [UTC 8601](https://www.iso.org/iso-8601-date-and-time-format.html) with zero time offset and seconds precise to eight decimal places. `address` is the 40 hexadecimal characters that make up the account address without a leading `0x`, for example: - -`UTC--2022-05-19T12-34-36.47413510Z--0b85e5a13e118466159b1e1b6a4234e5f9f784bb` - - -Note that there is also a Geth command for creating new accounts that will eventually be deprecated in favour of Clef. The following command will achieve the same as the RPC call suggested above: - -```sh -geth account new -``` - -### Listing accounts - -The accounts in the keystore can be listed to the terminal using `account_list` as follows: - -```sh -curl -X POST --data '{"id": 0, "jsonrpc": "2.0", "method": "account_list", "params": []}' http://localhost:8550 -H "Content-Type: application/json" -``` - -This returns a JSON object with the account addresses in an array in the `result` field. - -```terminal -{"jsonrpc": "2.0", "id": 0, "result": ["0x168bc315a2ee09042d83d7c5811b533620531f67", "0x0b85e5a13e118466159b1e1b6a4234e5f9f784bb"]} -``` - -The ordering of accounts when they are listed is lexicographic, but is effectively chronological based on time of creation due to the timestamp in the file name. It is safe to transfer the entire `keystore` directory or individual key files between Ethereum nodes. This is important because when accounts are added from other nodes the order of accounts in the keystore may change. It is therefore important not to rely on account indexes in scripts or code snippets. - -Accounts can also be listed in the Javascript console using `eth.accounts`, which will defer to Clef for approval. - - -### Import a keyfile - -It is also possible to create an account by importing an existing private key. For example, a user might already have some ether at an address they created using a browser wallet and now wish to use a new Geth node to interact with their funds. In this case, the private key can be exported from the browser wallet and imported into Geth. It is possible to do this using Clef, but currently the method is not externally exposed and requires implementing a UI. There is a Python UI on the Geth Github that could be used as an example or it can be done using the default console UI. However, for now the most straightforward way to import an accoutn from a private key is to use Geth's `account import`. - -Geth requires the private key to be stored as a file which contains the private key as unencrypted canonical elliptic curve bytes encoded into hex (i.e. plain text key without leading 0x). The new account is then saved in encrypted format, protected by a passphrase the user provides on request. As always, this passphrase must be securely and safely backed up - there is no way to retrieve or reset it if it is forgotten! - -```shell -$ geth account import --datadir /some-dir ./keyfile -``` - -The following information will be displayed in the terminal, indicating a successful import: - -```terminal -Please enter a passphrase now. -Passphrase: -Repeat Passphrase: -Address: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d} -``` - -This import/export process is **not necessary** for users transferring accounts between Geth instances because the key files can simply be copied directly from one keystore to another. - -It is also possible to import an account in non-interactive mode by saving the account password as plaintext in a `.txt` file and passing its path with the `--password` flag on startup. - -```shell -geth account import --password path/password.txt path/keyfile -``` - -In this case, it is important to ensure the password file is not readable by anyone but the intended user. This can be achieved by changing the file permissions. On Linux, the following commands update the file permissions so only the current user has access: - -```sh -chmod 700 /path/to/password -cat > /path/to/password - -``` - -### Import a presale wallet - -Assuming the password is known, importing a presale wallet is very easy. Geth's `wallet import` commands are used, passing the path to the wallet. - -```sh -geth wallet import /path/presale.wallet -``` - -## Updating accounts - -Clef can be used to set and remove passwords for an existing keystore file. To set a new password, pass the account address to `setpw`: - -```sh -clef setpw a94f5374fce5edbc8e2a8697c15331677e6ebf0b -``` - -This will cause Clef to prompt for a new password, twice, and then the Clef master password to decrypt the keyfile. - -Geth's `account update` subcommand can also be used to update the account password: - -```shell -geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b -``` - -Alternatively, in non-interactive mode the path to a password file containing the account password in unencrypted plaintext can be passed with the `--password` flag: - -```shell -geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b --password path/password.txt -``` - -Updating the account using `geth account update` replaces the original file with a new one - this means the original file is no longer available after it has been updated. This can be used to update a key file to the latest format. - -## Unlocking accounts - -With Clef, indiscriminate account unlocking is no longer a feature. Instead, Clef unlocks are locked until actions are explicitly approved manually by a user, unless they conform to some specific scenario that has been encoded in a ruleset. Please refer to our Clef docs for instructions for how to create rulesets. - - -### Transactions - -Transactions can be sent using raw JSON requests to Geth or using `web3js` in the Javascript console. Either way, with Clef acting as the signer the transactions will not get sent until approval is given in Clef. The following code snippet shows how a transaction could be sent between two accounts in the keystore using the Javascript console. - -```shell -var tx = {from: eth.accounts[1], to: eth.accounts[2], value: web3.toWei(5, "ether")} - -# this will hang until approval is given in the Clef console -eth.sendTransaction(tx) -``` - -## Summary - -This page has demonstrated how to manage accounts using Clef and Geth's account management tools. Accounts are stored encrypted by a password. It is critical that the account passwords and the keystore directory are safely and securely backed up. diff --git a/src/pages/docs/getting-started/index.md b/src/pages/docs/getting-started/index.md index 52ac673a78..1b29b06d49 100644 --- a/src/pages/docs/getting-started/index.md +++ b/src/pages/docs/getting-started/index.md @@ -3,11 +3,9 @@ title: Getting Started with Geth description: Instructions for getting up and running with Geth --- -This page explains how to set up Geth and execute some basic tasks using the command line tools. In order to use Geth, the software must first be installed. There are several ways Geth can be installed depending on the operating system and the user's choice of installation method, for example using a package manager, container or building from source. Instructions for installing Geth can be found on the ["Install and Build"](content/docs/getting_started/Installing-Geth.md) pages. Geth -also needs to be connected to a consensus client in order to function as an Ethereum node. The tutorial on this page assumes Geth and a consensus client have been installed successfully and that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see [Security](/content/docs/fundamentals/security.md). +This page explains how to set up Geth and execute some basic tasks using the command line tools. In order to use Geth, the software must first be installed. There are several ways Geth can be installed depending on the operating system and the user's choice of installation method, for example using a package manager, container or building from source. Instructions for installing Geth can be found on the ["Install and Build"](content/docs/getting_started/Installing-Geth.md) pages. Geth also needs to be connected to a consensus client in order to function as an Ethereum node. The tutorial on this page assumes Geth and a consensus client have been installed successfully and that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see [Security](/content/docs/fundamentals/security.md). -This page provides step-by-step instructions covering the fundamentals of using Geth. This includes generating accounts, joining an Ethereum network, syncing the blockchain and sending ether between accounts. This page uses Geth's built in account management tool. This is the simplest method for creating and accessing -accounts in Geth, is sufficiently secure for many purposes and provides a good entry point for understanding some of the basic Geth workflows. However, Geth also comes bundled with an external signer and account management tool called [Clef](/tools/Clef/introduction). It is best practise to use Clef instead of Geth's built-in account management tools because Clef is decoupled from Geth and can be run in a separate, secure environment. This page should be used as an initial entry point into basic Geth and readers should plan to advance from this page to [Getting started with Geth and Clef](/content/docs/getting_started/getting-started-with-clef.md). Eventually, Clef is intended to replace Geth's built-in account management tools. +This page provides step-by-step instructions covering the fundamentals of using Geth. This includes generating accounts, joining an Ethereum network, syncing the blockchain and sending ether between accounts. This page uses Geth's built in account management tool. This is the simplest method for creating and accessing accounts in Geth, is sufficiently secure for many purposes and provides a good entry point for understanding some of the basic Geth workflows. However, Geth also comes bundled with an external signer and account management tool called [Clef](/tools/Clef/introduction). It is best practise to use Clef instead of Geth's built-in account management tools because Clef is decoupled from Geth and can be run in a separate, secure environment. This page should be used as an initial entry point into basic Geth and readers should plan to advance from this page to [Getting started with Geth and Clef](/content/docs/getting_started/getting-started-with-clef.md). Eventually, Clef is intended to replace Geth's built-in account management tools. ## Prerequisites