diff --git a/EIPS/eip-2333.md b/EIPS/eip-2333.md index d74fc3c6bcb6e3..52330f3e05e191 100644 --- a/EIPS/eip-2333.md +++ b/EIPS/eip-2333.md @@ -39,6 +39,12 @@ This key derivation scheme has a Lamport key pair which is generated as a interm ## Specification +### Version + +Due to the evolving BLS standard, the `KeyGen` function was updated, meaning that `hkdf_mod_r` no longer reflected what appeared in the BLS standard. This EIP was updated on the 11th of June 2020 to reflect this new method for deriving keys, **if you are implementing this EIP, please make sure your version is up to date.** + +### Specification + Keys are defined in terms of a tree structure where a key is determined by the tree's seed and a tree path. This is very useful as one can start with a single source of entropy and build out a practically unlimited number of keys. The specification can be broken into two sub-components: generating the master key, and constructing a child key from its parent. The master key is used as the root of the tree and then the tree is built in layers on top of this root. ### The Tree Structure @@ -130,6 +136,7 @@ Every key generated via the key derivation process derives a child key via a set ##### Inputs * `IKM`, a secret octet string. +* `key_info`, an optional octet string (default=`""`, the empty string) ##### Outputs @@ -139,17 +146,17 @@ Every key generated via the key derivation process derives a child key via a set * `HKDF-Extract` is as defined in RFC5869, instantiated with hash H. * `HKDF-Expand` is as defined in RFC5869, instantiated with hash H. -* `L` is the integer given by ceil((1.5 * ceil(log2(r))) / 8). +* `L` is the integer given by `ceil((3 * ceil(log2(r))) / 16)`, `L=48`. * `"BLS-SIG-KEYGEN-SALT-"` is an ASCII string comprising 20 octets. -* `""` is the empty string. * `OS2IP` is as defined in [RFC3447](https://ietf.org/rfc/rfc3447.txt) (Big endian encoding) -* `r` is the order of the BLS 12-381 curve defined in [the draft IETF BLS signature scheme standard](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00) `r=52435875175126190479447740508185965837690552500527637822603658699938581184513` +* `I2OSP` is as defined in [RFC3447](https://ietf.org/rfc/rfc3447.txt) (Big endian decoding) +* `r` is the order of the BLS 12-381 curve defined in [the draft IETF BLS signature scheme standard](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-02) `r=52435875175126190479447740508185965837690552500527637822603658699938581184513` ##### Procedure ```text -1. PRK = HKDF-Extract("BLS-SIG-KEYGEN-SALT-", IKM) -2. OKM = HKDF-Expand(PRK, "", L) +1. PRK = HKDF-Extract("BLS-SIG-KEYGEN-SALT-", IKM || I2OSP(0, 1)) +2. OKM = HKDF-Expand(PRK, key_info || I2OSP(L, 2), L) 3. SK = OS2IP(OKM) mod r 4. return SK ``` @@ -204,11 +211,11 @@ The Lamport signatures used within this scheme have 255 bits worth of security, ### SHA256 -SHA256 is used as the hash function throughout this standard as it is the hash function chosen by the for the [IETF BLS12-381 standard](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00). Using a single hash function for everything decreases the number of cryptographic primitives required to implement the entire BLS standardised key-stack while reducing the surface for flaws in the overall system. +SHA256 is used as the hash function throughout this standard as it is the hash function chosen by the for the [IETF BLS12-381 standard](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-02). Using a single hash function for everything decreases the number of cryptographic primitives required to implement the entire BLS standardised key-stack while reducing the surface for flaws in the overall system. ### `hkdf_mod_r()` -The function `hkdf_mod_r()` in this standard is the same as the `KeyGen` function described in the [draft IETF BLS standard](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00) and therefore the private key obtained from `KeyGen` is equal to that obtained from `hkdf_mod_r` for the same seed bytes. This means that common engineering can be done when implementing this function. Additionally because of its inclusion in an IETF standard, it has had much scrutiny by many cryptographers and cryptanalysts, thereby lending credence to its safety as a key derivation mechanism. +The function `hkdf_mod_r()` in this standard is the same as the `KeyGen` function described in the [draft IETF BLS standard](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-02) and therefore the private key obtained from `KeyGen` is equal to that obtained from `hkdf_mod_r` for the same seed bytes. This means that common engineering can be done when implementing this function. Additionally because of its inclusion in an IETF standard, it has had much scrutiny by many cryptographers and cryptanalysts, thereby lending credence to its safety as a key derivation mechanism. While `hkdf_mod_r()` has modulo bias, the magnitude of this bias is minuscule (the output size of HKDF is set to 48 bytes which is greater 2128 time larger than the curve order). This bias is deemed acceptable in light of the simplicity of the constant time scheme. @@ -272,7 +279,7 @@ child_SK = 741954310531627918393743084244935870132797316553040716629495647309530 ## Implementation -* [Python](https://github.com/CarlBeek/eth2.0-deposit-tooling/blob/master/key_derivation/tree.py) +* [Python](https://github.com/ethereum/eth2.0-deposit-cli) ## Copyright