Original

What is a keystore file

A keystore file is en encrypted version of your unique private key that you will use to sign your transactions. If you lose this file your lose your assets.

What do keystore files look like

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "crypto": {
    "cipher": "aes-128-ctr",
    "cipherparams": {
      "iv": "83dbcc02d8ccb40e466191a123791e0e"
    },
    "ciphertext": "d172bf743a674da9cdad04534d56926ef8358534d458fffccd4e6ad2fbde479c",
    "kdf": "scrypt",
    "kdfparams": {
      "dklen": 32,
      "n": 262144,
      "r": 1,
      "p": 8,
      "salt": "ab0c7876052600dd703518d6fc3fe8984592145b591fc8fb5c6d43190334ba19"
    },
    "mac": "2103ac29920d71da29f15d75b4a16dbe95cfd7ff8faea1056c33131d846e3097"
  },
  "id": "3198bc9c-6672-5ab3-d995-4942343ae5b6",
  "version": 3
}

Thses fields mean:

  • cipher: The name of a symmetric AES algorithm

  • cipherparams: The parameters required for the “cipher” algorithm above

  • ciphertext: The private key encrypted using the “cipher” algorithm above

  • kdf: A key derivation function used to let you encrypt your keystore file with a password

  • kdfparams: The parameters required for the “kdf” algorithm above

  • mac: A code used to verify your password

Work flow

  1. Encrypting your private key

These symmetric algorithms use a key to encrypt some data. The resulting data is encrypted and can be decrypted with the same method and the same key.

The relation between cipher, cipherparams, ciphertext:

  • cipher is the symmetric algorithm used to encrypt the private key.

  • cipherparams are the parameters required for teh symmetric algorithm.

  • ciphertext is the encrypted input of the symmetric input.

You get the decryption-key as the output of the kdf.

By this, you need to retrieve your decryption-key(namely the key used in encryption) to decrypt your private key.

  1. Protect with your passphrase

To make sure unlocking your account is easy, you don’t need to remember your very long and non-user-friendly decrption-key that is used to decrypt ciphertext. Instead, the developers have opted for a passphrase-based protection.

The keystore use a kdf(key derivation function) that computes the decryption-key given a passphrase and a list of parameters.

  • kdf is the key derivation function used to compute the decryption-key from your passphrase.

  • kdfparams are the parameters required for the function

By the passphrase with kdfparams, the kdf returns your decrption-key.

  1. Make sure your passphrase is right

We need to guarantee that the passphrase typed to unlock the account is right, that it is the same one as the one entered when the keystore is generated.

This is where the field mac in the keystore works. Just after the kdf is executed, its result(decryption-key) and ciphertext are processed and compared to mac. If the result is the same as mac, then the passphrase was right and the decrption-key is correct.

Conclusion