Automatically merged updates to draft EIP(s) 2335 (ethereum#2749)

Hi, I'm a bot! This change was automatically merged because: - It only modifies existing Draft or Last Call EIP(s) - The PR was approved or written by at least one author of each modified EIP - The build is passing
tkstanczak · Nov 7, 2020 · 957f3f6 · 957f3f6
1 parent f855cf3
commit 957f3f6
Showing 1 changed file with 31 additions and 9 deletions.
diff --git a/EIPS/eip-2335.md b/EIPS/eip-2335.md
@@ -36,9 +36,17 @@ In Ethereum 1, [the Web3 Secret Storage Definition](https://github.com/ethereum/
 
 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.
 
+### Password requirements
+
+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.
+
+#### Control codes removal
+
+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.
+
 ### Modules
 
-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.
+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.
 
@@ -92,6 +100,10 @@ The `cipher.function` encrypts the secret using the decryption key, thus to decr
 |----------------------|-----------------|--------------------------|-------------|-------------------------------------------------|
 | AES-128 Counter Mode | `"aes-128-ctr"` | <ul><li>`"iv"`</li></ul> |             | [RFC 3686](https://tools.ietf.org/html/rfc3686) |
 
+## Description
+
+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**.
+
 ## PubKey
 
 The `pubkey` is the public key associated with the 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](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00)), but can be seen as a byte-string in the abstract and should be directly compatible with the appropriate signature library.
@@ -133,6 +145,9 @@ The keystore, at its core, is constructed with modules which allow for the confi
                         }
                     }
                 },
+                "description": {
+                    "type": "string"
+                },
                 "pubkey": {
                     "type": "string"
                 },
@@ -192,11 +207,12 @@ This specification is not backwards compatible with the [existing keystore stand
 
 ## Test Cases
 
-Password `'testpassword'`
-Secret `0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`
-
 ### Scrypt Test Vector
 
+Password `"𝔱𝔢𝔰𝔱𝔭𝔞𝔰𝔰𝔴𝔬𝔯𝔡🔑"`
+Encoded Password: `0x7465737470617373776f7264f09f9491`
+Secret `0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`
+
 ```json
 {
     "crypto": {
@@ -214,16 +230,17 @@ Secret `0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`
         "checksum": {
             "function": "sha256",
             "params": {},
-            "message": "149aafa27b041f3523c53d7acba1905fa6b1c90f9fef137568101f44b531a3cb"
+            "message": "d2217fe5f3e9a1e34581ef8a78f7c9928e436d36dacc5e846690a5581e8ea484"
         },
         "cipher": {
             "function": "aes-128-ctr",
             "params": {
                 "iv": "264daa3f303d7259501c93d997d84fe6"
             },
-            "message": "54ecc8863c0550351eee5720f3be6a5d4a016025aa91cd6436cfec938d6a8d30"
+            "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",
@@ -233,6 +250,10 @@ Secret `0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`
 
 ### PBKDF2 Test Vector
 
+Password `"𝔱𝔢𝔰𝔱𝔭𝔞𝔰𝔰𝔴𝔬𝔯𝔡🔑"`
+Encoded Password: `0x7465737470617373776f7264f09f9491`
+Secret `0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`
+
 ```json
 {
     "crypto": {
@@ -249,16 +270,17 @@ Secret `0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`
         "checksum": {
             "function": "sha256",
             "params": {},
-            "message": "18b148af8e52920318084560fd766f9d09587b4915258dec0676cba5b0da09d8"
+            "message": "8a9f5d9912ed7e75ea794bc5a89bca5f193721d30868ade6f73043c6ea6febf1"
         },
         "cipher": {
             "function": "aes-128-ctr",
             "params": {
                 "iv": "264daa3f303d7259501c93d997d84fe6"
             },
-            "message": "a9249e0ca7315836356e4c7440361ff22b9fe71e2e2ed34fc1eb03976924ed48"
+            "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",
@@ -270,7 +292,7 @@ Secret `0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`
 
 Implementations exist in the following languages:
 
-* [Python3](https://github.com/CarlBeek/eth2.0-deposit-tooling/blob/master/keystores.py)
+* [Python3](https://github.com/ethereum/eth2.0-deposit-cli)
 * [TypeScript](https://github.com/nodefactoryio/bls-keystore)
 * [Go](https://github.com/wealdtech/go-eth2-wallet-encryptor-keystorev4/)