A JSON format for the storage and interchange of BLS12-381 private keys.
A keystore is a mechanism for storing private keys. It is a JSON file that encrypts a private key and is the standard for interchanging keys between devices as until a user provides their password, their key is safe.
This specification is designed not only to be an Ethereum 2.0 standard, but one that is adopted by the wider community who have adopted the BLS12-381 signature standard. It is therefore important also to consider the needs of the wider industry along with those specific to Ethereum. As a part of these considerations, it is the intention of the author that this standard eventually migrate to a more neutral repository in the future.
The secure storage and exchange of keys is a vital component of the user experience as people are expected to hold their own keys. It allows users to control access to individual keys and their use by applications.
In Ethereum 1, the Web3 Secret Storage Definition fulfills these requirements, however it is not perfectly suitable for these purposes moving forward. Specifically the problems with the existing standard are:
The use of Keccak256. Eth1 keystores use Keccak for their checksum, a sensible choice considering its usage within Ethereum 1. BLS12-381 signatures, keys (EIP-2333), and key-storage are inter-chain standards, the establishment and proliferation of which hinges on them being neutral to all chains, something which Keccak is not.
A lack of abstraction. Eth1 keystores are a result of an iterative design process whereby functionality was added and modified as needed without considering how abstractions could simplify the notion of different properties.
The process of decrypting the secret held within a keystore can be broken down into 3 sub-processes: obtaining the decryption key, verifying the password and decrypting the secret. Each process has its own functions which can be selected from as well as parameters required for the function all of which are specified within the keystore file itself.
The password is a string of arbitrary unicode characters. The password is first converted to its NFKD representation, then the control codes (specified below) are stripped from the password and finally it is UTF-8 encoded.
The C0, C1, and Delete control codes are not valid characters in the password and should therefore be stripped from the password. C0 are the control codes between 0x00 - 0x1F (inclusive) and C1 codes lie between 0x80 and 0x9F (inclusive). Delete, commonly known as "backspace", is the UTF-8 character 7F which must also be stripped. Note that space (Sp UTF-8 0x20) is a valid character in passwords despite it being a pseudo-control character.
This standard makes use of the notion of a module which serves to represent, in an abstract sense, the different Β cryptographic constructions and corresponding parameters for each component of the keystore. The idea being that components can be swapped out without affecting the rest of the specification should the need arise.
A module is comprised of a function, which defines which cryptographic construct is being used, params, the parameters required by the function, and message the primary input to the function.
The decryption key is an intermediate key which is used both to verify the user-supplied password is correct, as well as for the final secret decryption. This key is simply derived from the password, the function, and the params specified by thekdf module as per the keystore file.
| KDF | "function" |
"params" |
"message" |
Definition |
|---|---|---|---|---|
| PBKDF2-SHA-256 | "pbkdf2" |
|
RFC 2898 | |
| scrypt | "scrypt" |
|
RFC 7914 |
The password verification step verifies that the password is correct with respect to the checksum.message, cipher.message, and kdf. This is done by appending the cipher.message to the 2nd 16 bytes of the decryption key, obtaining its SHA256 hash and verifying whether it matches the checksum.message.
decryption_key, the octet string obtained from decryption key processcipher_message, the octet string obtained from keystore file from crypto.cipher.messagechecksum_message, the octet string obtained from keystore file from crypto.checksum.messagevalid_password, aΒ boolean value indicating whether the password is valida[0:3] returns a slice of a including octets 0, 1, 2a | b is the concatenation of a with b0. DK_slice = decryption_key[16:32]
1. pre_image = DK_slice | cipher_message
2. checksum = SHA256(pre_image)
3. valid_password = checksum == checksum_message
4. return valid_password
| Hash | "function" |
"params" |
"message" |
Definition |
|---|---|---|---|---|
| SHA-256 | "sha256" |
RFC 6234 |
The cipher.function encrypts the secret using the decryption key, thus to decrypt it, the decryption key along with the cipher.function and cipher.params must be used. If the decryption_key is longer than the key size required by the cipher, it is truncated to the correct number of bits. In the case of aes-128-ctr, only the first 16 bytes of the decryption_key are used as the AES key.
| Cipher | "function" |
"params" |
"message" |
Definition |
|---|---|---|---|---|
| AES-128 Counter Mode | "aes-128-ctr" |
|
RFC 3686 |
This field is an optional field to help explain the purpose and identify a particular keystores in a user-friendly manner. While this field can, and should, be used to help distinguish keystores from one-another, the description is not necessarily unique.
The pubkey is the public key associated with the private key secured within the keystore. It is stored here to improve user experience and security which is achieved by not requiring users to enter their password just to obtain their public keys. This field is required if the secret being stored within the keystore is a private key. The encoding of the pubkey is specified in the in the appropriate signature standard (eg. BLS12-381 signature standard), but can be seen as a byte-string in the abstract and should be directly compatible with the appropriate signature library.
The path indicates where in the key-tree a key originates from. It is a string defined by EIP-2334, if no path is known or the path is not relevant, the empty string, "" indicates this. The path can specify an arbitrary depth within the tree and the deepest node within the tree indicates the depth of the key stored within this file.
The uuid provided in the keystore is a randomly generated UUID as specified by RFC 4122. It is used as a 128-bit proxy for referring to a particular set of keys or account.
The version is set to 4.
The keystore, at its core, is constructed with modules which allow for the configuration of the cryptographic constructions used password hashing, password verification and secret decryption. Each module is composed of: function, params, and message which corresponds with which construction is to be used, what the configuration for the construction is, and what the input is.
{
"$ref": "#/definitions/Keystore",
"definitions": {
"Keystore": {
"type": "object",
"properties": {
"crypto": {
"type": "object",
"properties": {
"kdf": {
"$ref": "#/definitions/Module"
},
"checksum": {
"$ref": "#/definitions/Module"
},
"cipher": {
"$ref": "#/definitions/Module"
}
}
},
"description": {
"type": "string"
},
"pubkey": {
"type": "string"
},
"path": {
"type": "string"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "integer"
}
},
"required": [
"crypto",
"path",
"uuid",
"version"
],
"title": "Keystore"
},
"Module": {
"type": "object",
"properties": {
"function": {
"type": "string"
},
"params": {
"type": "object"
},
"message": {
"type": "string"
}
},
"required": [
"function",
"message",
"params"
]
}
}
}
The rationale behind the design of this specification is largely the same as that behind the Ethereum 1 keystore definition except for the lack of support for Keccak (explained in motivation above) and the notion of modules.
Modules provide a very useful level of abstraction which allow the Key-Derivation-Function, Checksum, and Cipher to be thought of as instances of the same thing allowing for their substitution with minimal effort.
The version is set to 4 to prevent collisions with the existing Ethereum keystore standard.
This specification is not backwards compatible with the existing keystore standard due to the lack of Keccak256 checksums as explained above. While this format is capable of supporting Keccak checksums via the Checksum module, it would defeat the purpose of this standard to include it as this standard could no longer be considered neutral with respect to other projects in the industry.
Password "π±π’π°π±πππ°π°π΄π¬π―π‘π"
Encoded Password: 0x7465737470617373776f7264f09f9491
Secret 0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f
{
"crypto": {
"kdf": {
"function": "scrypt",
"params": {
"dklen": 32,
"n": 262144,
"p": 1,
"r": 8,
"salt": "d4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3"
},
"message": ""
},
"checksum": {
"function": "sha256",
"params": {},
"message": "d2217fe5f3e9a1e34581ef8a78f7c9928e436d36dacc5e846690a5581e8ea484"
},
"cipher": {
"function": "aes-128-ctr",
"params": {
"iv": "264daa3f303d7259501c93d997d84fe6"
},
"message": "06ae90d55fe0a6e9c5c3bc5b170827b2e5cce3929ed3f116c2811e6366dfe20f"
}
},
"description": "This is a test keystore that uses scrypt to secure the secret.",
"pubkey": "9612d7a727c9d0a22e185a1c768478dfe919cada9266988cb32359c11f2b7b27f4ae4040902382ae2910c15e2b420d07",
"path": "m/12381/60/3141592653/589793238",
"uuid": "1d85ae20-35c5-4611-98e8-aa14a633906f",
"version": 4
}
Password "π±π’π°π±πππ°π°π΄π¬π―π‘π"
Encoded Password: 0x7465737470617373776f7264f09f9491
Secret 0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f
{
"crypto": {
"kdf": {
"function": "pbkdf2",
"params": {
"dklen": 32,
"c": 262144,
"prf": "hmac-sha256",
"salt": "d4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3"
},
"message": ""
},
"checksum": {
"function": "sha256",
"params": {},
"message": "8a9f5d9912ed7e75ea794bc5a89bca5f193721d30868ade6f73043c6ea6febf1"
},
"cipher": {
"function": "aes-128-ctr",
"params": {
"iv": "264daa3f303d7259501c93d997d84fe6"
},
"message": "cee03fde2af33149775b7223e7845e4fb2c8ae1792e5f99fe9ecf474cc8c16ad"
}
},
"description": "This is a test keystore that uses PBKDF2 to secure the secret.",
"pubkey": "9612d7a727c9d0a22e185a1c768478dfe919cada9266988cb32359c11f2b7b27f4ae4040902382ae2910c15e2b420d07",
"path": "m/12381/60/0/0",
"uuid": "64625def-3331-4eea-ab6f-782f3ed16a83",
"version": 4
}
Implementations exist in the following languages:
Copyright and related rights waived via CC0.