A better private key storage format

Aergo 2.2 introduces a new format for storing private keys. The new keystore format offers better portability thanks to a well-defined standard and an additional layer of security due to a more durable derivation of keys from passphrases. The new format contains all information needed to decrypt a private key, given the passphrase. That means that even if standards change or clients stop being supported some day, using just this one passphrase-protected file you can always recover your private key. It is also an easy way to move between different clients, e.g. Aergo Connect, aergocli, Athena IDE, JDBC. You can find details about the file format in Aergo’s documentation.

Aergo Connect

New in version: 0.3.0 (If you already had it installed, it will update automatically. If not, install it here.)

If you’re using Aergo Connect, you can find the new Keystore format as an option on the Export and Import views:

We recommend using this method as a safer alternative to the old string-based format. Everyone who is storing any significant value of AERGO tokens should download and backup this file in a secure location.

Athena IDE

New version: will be available here soon

Our IDE extension for Atom also supports the new Keystore format when importing an account:

JDBC

See also: Introduction to JDBC

New version: will be available here soon

In the new version of Aergo’s JDBC adapter, you can supply a keystore file using a new option.

On Properties/General, the Username is your account’s address, the Password is the keystore file’s password. On Properties/Optional, add a custom option keystore=/path/to/aergo/data (the directory containing the keystore directory).

Aergocli

For more details, check the aergocli documentation

As well as support for storing, importing and exporting using the new format, aergocli now also supports using a local keystore, i.e. private keys saved on your disk using the keystore format, for all account transactions. This is the new default behavior — if you want to continue using the old method, see below.

By default, aergocli stores accounts in $HOME/.aergo, but you can also set the directory used to store keystore files manually using the — keystore parameter.

Creating and using accounts with a local keystore

Create account:

$ aergocli account new
Enter password:
Repeat  Password: AmMzAUeQyRcLS8EUpKJJfyHsBQNv6YndmywrY3SJUbSUhFdxRr21

Get some testnet aergo via the Faucet.

Check account:

$ aergocli -H testnet-api.aergo.io getstate — address AmMzAUeQyRcLS8EUpKJJfyHsBQNv6YndmywrY3SJUbSUhFdxRr21
{“account”:”AmMzAUeQyRcLS8EUpKJJfyHsBQNv6YndmywrY3SJUbSUhFdxRr21″, “nonce”:0, “balance”:”5 aergo”}

Send a tx to yourself:

$ aergocli -H testnet-api.aergo.io sendtx — amount 0 — from AmMzAUeQyRcLS8EUpKJJfyHsBQNv6YndmywrY3SJUbSUhFdxRr21 — to AmMzAUeQyRcLS8EUpKJJfyHsBQNv6YndmywrY3SJUbSUhFdxRr21
Enter password:
{
“hash”: “BQ1rLwv7YAThFEFC2FaBUS2x6oLvDCuEh5Q6z7GLrvpR”
}

Check the tx on Aergoscan: https://testnet.aergoscan.io/transaction/BQ1rLwv7YAThFEFC2FaBUS2x6oLvDCuEh5Q6z7GLrvpR

Export/import

You can export accounts using the new format like this:

$ aergocli account export — address YOUR_ADDRESS > YOUR_ADDRESS__keystore.txt

Continue using the old method (server-based account)

In aergocli versions before 2.2.0, account actions would use an account that is stored on the remote server (full node) you are connected to. This is fine if you are running your own full node, but for the vast majority of users who want to connect to publicly available nodes, this is not useful. That is why the default behavior was changed to use local keystores (as explained above).

To use the previous method of selecting accounts from the connected server, pass the ` — node-keystore` flag to aergocli. Remember you then have to unlock accounts before using them on the server.

You can use this to export accounts from your node as a keystore file and then import it into your local keystore:

$ aergocli -H YOUR_NODE_IP — node-keystore account export — address YOUR_ADDRESS > YOUR_ADDRESS__keystore.txt

$ aergocli account import — path YOUR_ADDRESS__keystore.txt

Security advice

The encryption method used for the keystore format is considered safe if you use a good password. If you want to read more about how it works, check out this Medium article.

However, please note that no matter what encryption is used to store a private key, it is only ever as secure as the computer used to generate and decrypt it. For that reason, only hardware wallets can provide real security. If you are storing a substantial amount of Aergo, we recommend keeping them as ERC-20 tokens secured in a ERC-20 enabled hardware wallet. We are planning to support Ledger hardware wallets in the near future, so that you can secure native tokens more securely.

Posts

The Aergo Keystore