From 28015a44803473c461388da3eb090361ee05467a Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Thu, 21 Nov 2019 22:36:34 +0000 Subject: [PATCH 01/13] Initial draft of walletstore --- EIPS/eip-walletstore.md | 208 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 EIPS/eip-walletstore.md diff --git a/EIPS/eip-walletstore.md b/EIPS/eip-walletstore.md new file mode 100644 index 0000000000000..04286425a501f --- /dev/null +++ b/EIPS/eip-walletstore.md @@ -0,0 +1,208 @@ +--- +eip: tbd +title: Walletstore +author: Jim McDonald (Jim@mcdee.net) +discussions-to: tbd +status: Draft +type: Standards Track +category: ERC +created: 2019-11-21 +requires: 2333, 2334 +--- + +## Simple Summary + +A JSON format for the storage and retrieval of Ethereum 2 wallet definitions. + +## Abstract + +Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets can be created. + +## Motivation + +Ethereum wallets often require additional metadata above that in the keystore, for example a hierarchical deterministic wallet needs to know the seed and index of the last account created to generate new accounts. In addition, wallets themselves can have names. Standardizing this information and how it is stored allows it to be portable between different wallet providers with minimal effort. + +## Specification + +The elements of a walletstore are as follows: + +### UUID + +The `uuid` provided in the walletstore is a randomly-generated type 4 UUID as specified by [RFC 4122](https://tools.ietf.org/html/rfc4122). It is intended to be used as a 128-bit proxy for referring to a particular wallet, used to uniquely identify wallets. + +This element MUST be present. It MUST be a string following the syntactic structure as laid out in [section 3 of RFC 4122](https://tools.ietf.org/html/rfc4122#section-3). + +### Name + +The `name` provided in the walletstore is a UTF-8 string. It is intended to serve as the user-friendly accessor. The only restriction on the name is that it MUST NOT start with the underscore (`_`) character. + +This element MUST be present. It MUST be a string. + +### Version + +The `version` provided is the version of the walletstore. + +This element MUST be present. It MUST be the integer `1`. + +### Type + +The `type` provided is the type of wallet. This informs mechanisms such as key generation. + +This element MUST be present. It MUST be one of the following two strings: + + - `non-deterministic`: defined for wallets that create private keys from random information + - `hierarchical deterministic`: defined for wallets that create private keys based on the hierarchical deterministic method as outlined in [EIP-2334](https://github.com/ethereum/E IPs/blob/master/EIPS/eip-2334.md) + +### Crypto + +The `crypto` provided is the secure storage of a secret for wallets that require this information. For example `hierarchical deterministic` wallets have a seed from which they calculate individual private keys. + +The `crypto` section follows the definition described in [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md). + +This element MAY be present if the wallet type requires it. + +### Next Account + +The `nextaccount` provided is the next account to generate for wallets that require this information. For example, `hierarchical deterministic` wallets create private keys based on a path that has an incrementing value (the first wallet will be `m/12381/60/0/0`, the second `m/12381/60/1/0`, the third `m/12381/60/2/0` etc.). + +This element MAY be present if the wallet type requires it. If present it MUST be a non-negative integer. + +## JSON schema + +The walletstore follows a similar format to that of the keystore described in [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md). + +```json +{ + "$ref": "#/definitions/Walletstore", + "definitions": { + "Walletstore": { + "type": "object", + "properties": { + "crypto": { + "type": "object", + "properties": { + "kdf": { + "$ref": "#/definitions/Module" + }, + "checksum": { + "$ref": "#/definitions/Module" + }, + "cipher": { + "$ref": "#/definitions/Module" + } + } + }, + "name": { + "type": "string" + }, + "nextaccount": { + "type": "integer" + }, + "type": { + "type": "string" + }, + "uuid": { + "type": "string", + "format": "uuid" + }, + "version": { + "type": "integer" + } + }, + "required": [ + "name", + "type", + "uuid", + "version" + ], + "title": "Walletstore" + }, + "Module": { + "type": "object", + "properties": { + "function": { + "type": "string" + }, + "params": { + "type": "object" + }, + "message": { + "type": "string" + } + }, + "required": [ + "function", + "message", + "params" + ] + } + } +} +``` + +## Rationale + +A standard for walletstores, similar to that for keystores, provides a higher level of compatability between wallets and allows for simpler wallet and key interchange between them. + +## Test Cases + +### Non-deterministic Test Vector + +```json +{ + "name": "Test wallet 1", + "type": "non-deterministic", + "uuid": "5d71e10b-6e00-4cab-a5a0-866a5d8843c3", + "version": 1 +} +``` + +### Hierarchical deterministic Test Vector + +Password `'testpassword'` +Seed `0x147addc7ec981eb2715a22603813271cce540e0b7f577126011eb06249d9227c` + +```json +{ + "crypto": { + "checksum": { + "function": "sha256", + "message": "8bdadea203eeaf8f23c96137af176ded4b098773410634727bd81c4e8f7f1021", + "params": {} + }, + "cipher": { + "function": "aes-128-ctr", + "message": "7f8211b88dfb8694bac7de3fa32f5f84d0a30f15563358133cda3b287e0f3f4a", + "params": { + "iv": "9476702ab99beff3e8012eff49ffb60d" + } + }, + "kdf": { + "function": "pbkdf2", + "message": "", + "params": { + "c": 16, + "dklen": 32, + "prf": "hmac-sha256", + "salt": "dd35b0c08ebb672fe18832120a55cb8098f428306bf5820f5486b514f61eb712" + } + } + }, + "name": "Test wallet 2", + "nextaccount": 0, + "type": "hierarchical deterministic", + "uuid": "b74559b8-ed56-4841-b25c-dba1b7c9d9d5", + "version": 1 +} +``` + +## Implementation + +A Go implementation of the non-deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-nd](https://github.com/wealdtech/go-eth2-wallet-nd). + +A Go implementation of the hierarchical deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-hd](https://github.com/wealdtech/go-eth2-wallet-hd). + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + From de77ea577058617268d110c412fe4e1def004bf2 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Thu, 21 Nov 2019 22:39:24 +0000 Subject: [PATCH 02/13] Update tbds --- EIPS/eip-walletstore.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-walletstore.md b/EIPS/eip-walletstore.md index 04286425a501f..11175dfd71d9a 100644 --- a/EIPS/eip-walletstore.md +++ b/EIPS/eip-walletstore.md @@ -1,8 +1,8 @@ --- -eip: tbd +eip: 2386 title: Walletstore author: Jim McDonald (Jim@mcdee.net) -discussions-to: tbd +discussions-to: https://ethereum-magicians.org/t/eip-2386-walletstore/3792 status: Draft type: Standards Track category: ERC From 6d9526f05ec5969471278bd6e56b84ba85f3150a Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Thu, 21 Nov 2019 22:48:14 +0000 Subject: [PATCH 03/13] Fix spelling --- EIPS/eip-walletstore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-walletstore.md b/EIPS/eip-walletstore.md index 11175dfd71d9a..251dc7a8d033a 100644 --- a/EIPS/eip-walletstore.md +++ b/EIPS/eip-walletstore.md @@ -142,7 +142,7 @@ The walletstore follows a similar format to that of the keystore described in [E ## Rationale -A standard for walletstores, similar to that for keystores, provides a higher level of compatability between wallets and allows for simpler wallet and key interchange between them. +A standard for walletstores, similar to that for keystores, provides a higher level of compatibility between wallets and allows for simpler wallet and key interchange between them. ## Test Cases From f80da55ced58e8c099087d0ab59aa7fceac3a988 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 27 Nov 2019 00:45:51 +0000 Subject: [PATCH 04/13] Rename file to EIP number --- EIPS/{eip-walletstore.md => eip-2386.md} | 0 EIPS/eip-hdwlayout.md | 219 +++++++++++++++++++++++ 2 files changed, 219 insertions(+) rename EIPS/{eip-walletstore.md => eip-2386.md} (100%) create mode 100644 EIPS/eip-hdwlayout.md diff --git a/EIPS/eip-walletstore.md b/EIPS/eip-2386.md similarity index 100% rename from EIPS/eip-walletstore.md rename to EIPS/eip-2386.md diff --git a/EIPS/eip-hdwlayout.md b/EIPS/eip-hdwlayout.md new file mode 100644 index 0000000000000..4756dd60b970f --- /dev/null +++ b/EIPS/eip-hdwlayout.md @@ -0,0 +1,219 @@ +--- +eip: tba +title: Hierarchical store wallet layout +author: Jim McDonald (Jim@mcdee.net) +discussions-to: tba +status: Draft +type: Standards Track +category: ERC +created: 2019-11-26 +requires: ? +--- + +## Simple Summary + +A layout for storing an Ethereum wallet within a hierarchical store (e.g. a filesystem). + +## Abstract + +Ethereum wallets have no standards for their layout in persistent storage, making different wallet implementations incompatible. This defines a standard for Ethereum wallets that can be followed by wallets to provide a single layout that works across any hierarchical store. + +##### Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets can be created. + +## Motivation + +Ethereum wallets often require additional metadata above that in the keystore, for example a hierarchical deterministic wallet needs to know the seed and index of the last account created to generate new accounts. In addition, wallets themselves can have names. Standardizing this information and how it is stored allows it to be portable between different wallet providers with minimal effort. + +## Specification + +There are three elements for a wallet that need to be addressed. These are defined below. + +### Wallet container +The wallet container holds all walletstore and keystore objects. + +The wallet container is identified by the wallet's UUID. It MUST be a string following the syntactic structure as laid out in [section 3 of RFC 4122](https:// tools.ietf.org/html/rfc4122#section-3). + +### Walletstore +The walletstore element contains the walletstore and is held within the wallet container. It is identified by the wallet's UUID. It MUST be a string following the syntactic structure as laid out in [section 3 of RFC 4122](https:// tools.ietf.org/html/rfc4122#section-3). + +### Keystore +The keystore element contains the keystore for a given key and is held within the wallet container. It is identified by the key's UUID. It MUST be a string following the syntactic structure as laid out in [section 3 of RFC 4122](https:// tools.ietf.org/html/rfc4122#section-3). + +### Hierarchical stores +Hierarchical stores are a common way to store and organize information. The most common example is the filesystem, but a number of object-based stores such as + +Putting these elements together for a sample wallet with wallet UUID `1f031fff-c51d-44fc-8baf-d6b304cb70a7` and key UUIDs `1302106c-8441-4e2e-b687-6c77f49fc624` and `4a320100-83fd-4db7-8126-6d6d205ba834` gives the following layout: + +``` +- 1f031fff-c51d-44fc-8baf-d6b304cb70a7 ++- 1302106c-8441-4e2e-b687-6c77f49fc624 ++- 1f031fff-c51d-44fc-8baf-d6b304cb70a7 ++- 4a320100-83fd-4db7-8126-6d6d205ba834 +``` + +## Non-hierarchical stores +Non-hierarchical stores + +``` +1f031fff-c51d-44fc-8baf-d6b304cb70a7:1302106c-8441-4e2e-b687-6c77f49fc624 +1f031fff-c51d-44fc-8baf-d6b304cb70a7:1f031fff-c51d-44fc-8baf-d6b304cb70a7 +1f031fff-c51d-44fc-8baf-d6b304cb70a7:4a320100-83fd-4db7-8126-6d6d205ba834 +``` + +### Iterating over wallets + +### Iterating over keys + +### Crypto + +The `crypto` provided is the secure storage of a secret for wallets that require this information. For example `hierarchical deterministic` wallets have a seed from which they calculate individual private keys. + +The `crypto` section follows the definition described in [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md). + +This element MAY be present if the wallet type requires it. + +### Next Account + +The `nextaccount` provided is the next account to generate for wallets that require this information. For example, `hierarchical deterministic` wallets create private keys based on a path that has an incrementing value (the first wallet will be `m/12381/60/0/0`, the second `m/12381/60/1/0`, the third `m/12381/60/2/0` etc.). + +This element MAY be present if the wallet type requires it. If present it MUST be a non-negative integer. + +## JSON schema + +The walletstore follows a similar format to that of the keystore described in [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md). + +```json +{ + "$ref": "#/definitions/Walletstore", + "definitions": { + "Walletstore": { + "type": "object", + "properties": { + "crypto": { + "type": "object", + "properties": { + "kdf": { + "$ref": "#/definitions/Module" + }, + "checksum": { + "$ref": "#/definitions/Module" + }, + "cipher": { + "$ref": "#/definitions/Module" + } + } + }, + "name": { + "type": "string" + }, + "nextaccount": { + "type": "integer" + }, + "type": { + "type": "string" + }, + "uuid": { + "type": "string", + "format": "uuid" + }, + "version": { + "type": "integer" + } + }, + "required": [ + "name", + "type", + "uuid", + "version" + ], + "title": "Walletstore" + }, + "Module": { + "type": "object", + "properties": { + "function": { + "type": "string" + }, + "params": { + "type": "object" + }, + "message": { + "type": "string" + } + }, + "required": [ + "function", + "message", + "params" + ] + } + } +} +``` + +## Rationale + +A standard for walletstores, similar to that for keystores, provides a higher level of compatibility between wallets and allows for simpler wallet and key interchange between them. + +## Test Cases + +### Non-deterministic Test Vector + +```json +{ + "name": "Test wallet 1", + "type": "non-deterministic", + "uuid": "5d71e10b-6e00-4cab-a5a0-866a5d8843c3", + "version": 1 +} +``` + +### Hierarchical deterministic Test Vector + +Password `'testpassword'` +Seed `0x147addc7ec981eb2715a22603813271cce540e0b7f577126011eb06249d9227c` + +```json +{ + "crypto": { + "checksum": { + "function": "sha256", + "message": "8bdadea203eeaf8f23c96137af176ded4b098773410634727bd81c4e8f7f1021", + "params": {} + }, + "cipher": { + "function": "aes-128-ctr", + "message": "7f8211b88dfb8694bac7de3fa32f5f84d0a30f15563358133cda3b287e0f3f4a", + "params": { + "iv": "9476702ab99beff3e8012eff49ffb60d" + } + }, + "kdf": { + "function": "pbkdf2", + "message": "", + "params": { + "c": 16, + "dklen": 32, + "prf": "hmac-sha256", + "salt": "dd35b0c08ebb672fe18832120a55cb8098f428306bf5820f5486b514f61eb712" + } + } + }, + "name": "Test wallet 2", + "nextaccount": 0, + "type": "hierarchical deterministic", + "uuid": "b74559b8-ed56-4841-b25c-dba1b7c9d9d5", + "version": 1 +} +``` + +## Implementation + +A Go implementation of the non-deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-nd](https://github.com/wealdtech/go-eth2-wallet-nd). + +A Go implementation of the hierarchical deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-hd](https://github.com/wealdtech/go-eth2-wallet-hd). + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + From dc65eedcd19f9b14aa48e780c7360a9a5f9427da Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 27 Nov 2019 01:45:42 +0000 Subject: [PATCH 05/13] Remove extraneous file --- EIPS/eip-hdwlayout.md | 219 ------------------------------------------ 1 file changed, 219 deletions(-) delete mode 100644 EIPS/eip-hdwlayout.md diff --git a/EIPS/eip-hdwlayout.md b/EIPS/eip-hdwlayout.md deleted file mode 100644 index 4756dd60b970f..0000000000000 --- a/EIPS/eip-hdwlayout.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -eip: tba -title: Hierarchical store wallet layout -author: Jim McDonald (Jim@mcdee.net) -discussions-to: tba -status: Draft -type: Standards Track -category: ERC -created: 2019-11-26 -requires: ? ---- - -## Simple Summary - -A layout for storing an Ethereum wallet within a hierarchical store (e.g. a filesystem). - -## Abstract - -Ethereum wallets have no standards for their layout in persistent storage, making different wallet implementations incompatible. This defines a standard for Ethereum wallets that can be followed by wallets to provide a single layout that works across any hierarchical store. - -##### Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets can be created. - -## Motivation - -Ethereum wallets often require additional metadata above that in the keystore, for example a hierarchical deterministic wallet needs to know the seed and index of the last account created to generate new accounts. In addition, wallets themselves can have names. Standardizing this information and how it is stored allows it to be portable between different wallet providers with minimal effort. - -## Specification - -There are three elements for a wallet that need to be addressed. These are defined below. - -### Wallet container -The wallet container holds all walletstore and keystore objects. - -The wallet container is identified by the wallet's UUID. It MUST be a string following the syntactic structure as laid out in [section 3 of RFC 4122](https:// tools.ietf.org/html/rfc4122#section-3). - -### Walletstore -The walletstore element contains the walletstore and is held within the wallet container. It is identified by the wallet's UUID. It MUST be a string following the syntactic structure as laid out in [section 3 of RFC 4122](https:// tools.ietf.org/html/rfc4122#section-3). - -### Keystore -The keystore element contains the keystore for a given key and is held within the wallet container. It is identified by the key's UUID. It MUST be a string following the syntactic structure as laid out in [section 3 of RFC 4122](https:// tools.ietf.org/html/rfc4122#section-3). - -### Hierarchical stores -Hierarchical stores are a common way to store and organize information. The most common example is the filesystem, but a number of object-based stores such as - -Putting these elements together for a sample wallet with wallet UUID `1f031fff-c51d-44fc-8baf-d6b304cb70a7` and key UUIDs `1302106c-8441-4e2e-b687-6c77f49fc624` and `4a320100-83fd-4db7-8126-6d6d205ba834` gives the following layout: - -``` -- 1f031fff-c51d-44fc-8baf-d6b304cb70a7 -+- 1302106c-8441-4e2e-b687-6c77f49fc624 -+- 1f031fff-c51d-44fc-8baf-d6b304cb70a7 -+- 4a320100-83fd-4db7-8126-6d6d205ba834 -``` - -## Non-hierarchical stores -Non-hierarchical stores - -``` -1f031fff-c51d-44fc-8baf-d6b304cb70a7:1302106c-8441-4e2e-b687-6c77f49fc624 -1f031fff-c51d-44fc-8baf-d6b304cb70a7:1f031fff-c51d-44fc-8baf-d6b304cb70a7 -1f031fff-c51d-44fc-8baf-d6b304cb70a7:4a320100-83fd-4db7-8126-6d6d205ba834 -``` - -### Iterating over wallets - -### Iterating over keys - -### Crypto - -The `crypto` provided is the secure storage of a secret for wallets that require this information. For example `hierarchical deterministic` wallets have a seed from which they calculate individual private keys. - -The `crypto` section follows the definition described in [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md). - -This element MAY be present if the wallet type requires it. - -### Next Account - -The `nextaccount` provided is the next account to generate for wallets that require this information. For example, `hierarchical deterministic` wallets create private keys based on a path that has an incrementing value (the first wallet will be `m/12381/60/0/0`, the second `m/12381/60/1/0`, the third `m/12381/60/2/0` etc.). - -This element MAY be present if the wallet type requires it. If present it MUST be a non-negative integer. - -## JSON schema - -The walletstore follows a similar format to that of the keystore described in [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md). - -```json -{ - "$ref": "#/definitions/Walletstore", - "definitions": { - "Walletstore": { - "type": "object", - "properties": { - "crypto": { - "type": "object", - "properties": { - "kdf": { - "$ref": "#/definitions/Module" - }, - "checksum": { - "$ref": "#/definitions/Module" - }, - "cipher": { - "$ref": "#/definitions/Module" - } - } - }, - "name": { - "type": "string" - }, - "nextaccount": { - "type": "integer" - }, - "type": { - "type": "string" - }, - "uuid": { - "type": "string", - "format": "uuid" - }, - "version": { - "type": "integer" - } - }, - "required": [ - "name", - "type", - "uuid", - "version" - ], - "title": "Walletstore" - }, - "Module": { - "type": "object", - "properties": { - "function": { - "type": "string" - }, - "params": { - "type": "object" - }, - "message": { - "type": "string" - } - }, - "required": [ - "function", - "message", - "params" - ] - } - } -} -``` - -## Rationale - -A standard for walletstores, similar to that for keystores, provides a higher level of compatibility between wallets and allows for simpler wallet and key interchange between them. - -## Test Cases - -### Non-deterministic Test Vector - -```json -{ - "name": "Test wallet 1", - "type": "non-deterministic", - "uuid": "5d71e10b-6e00-4cab-a5a0-866a5d8843c3", - "version": 1 -} -``` - -### Hierarchical deterministic Test Vector - -Password `'testpassword'` -Seed `0x147addc7ec981eb2715a22603813271cce540e0b7f577126011eb06249d9227c` - -```json -{ - "crypto": { - "checksum": { - "function": "sha256", - "message": "8bdadea203eeaf8f23c96137af176ded4b098773410634727bd81c4e8f7f1021", - "params": {} - }, - "cipher": { - "function": "aes-128-ctr", - "message": "7f8211b88dfb8694bac7de3fa32f5f84d0a30f15563358133cda3b287e0f3f4a", - "params": { - "iv": "9476702ab99beff3e8012eff49ffb60d" - } - }, - "kdf": { - "function": "pbkdf2", - "message": "", - "params": { - "c": 16, - "dklen": 32, - "prf": "hmac-sha256", - "salt": "dd35b0c08ebb672fe18832120a55cb8098f428306bf5820f5486b514f61eb712" - } - } - }, - "name": "Test wallet 2", - "nextaccount": 0, - "type": "hierarchical deterministic", - "uuid": "b74559b8-ed56-4841-b25c-dba1b7c9d9d5", - "version": 1 -} -``` - -## Implementation - -A Go implementation of the non-deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-nd](https://github.com/wealdtech/go-eth2-wallet-nd). - -A Go implementation of the hierarchical deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-hd](https://github.com/wealdtech/go-eth2-wallet-hd). - -## Copyright - -Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). - From 541e0c25f2bb64704d7083776a6264f29d122611 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 27 Nov 2019 12:23:48 +0000 Subject: [PATCH 06/13] Update title; use canonical URLs for referenced EIPs --- EIPS/eip-2386.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/EIPS/eip-2386.md b/EIPS/eip-2386.md index 251dc7a8d033a..e990bc18e31bf 100644 --- a/EIPS/eip-2386.md +++ b/EIPS/eip-2386.md @@ -1,6 +1,6 @@ --- eip: 2386 -title: Walletstore +title: Ethereum 2 Walletstore author: Jim McDonald (Jim@mcdee.net) discussions-to: https://ethereum-magicians.org/t/eip-2386-walletstore/3792 status: Draft @@ -16,7 +16,7 @@ A JSON format for the storage and retrieval of Ethereum 2 wallet definitions. ## Abstract -Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets can be created. +Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets can be created. ## Motivation @@ -51,13 +51,13 @@ The `type` provided is the type of wallet. This informs mechanisms such as key This element MUST be present. It MUST be one of the following two strings: - `non-deterministic`: defined for wallets that create private keys from random information - - `hierarchical deterministic`: defined for wallets that create private keys based on the hierarchical deterministic method as outlined in [EIP-2334](https://github.com/ethereum/E IPs/blob/master/EIPS/eip-2334.md) + - `hierarchical deterministic`: defined for wallets that create private keys based on the hierarchical deterministic method as outlined in [EIP-2334](https://eips.ethereum.org/EIPS/eip-2334) ### Crypto The `crypto` provided is the secure storage of a secret for wallets that require this information. For example `hierarchical deterministic` wallets have a seed from which they calculate individual private keys. -The `crypto` section follows the definition described in [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md). +The `crypto` section follows the definition described in [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333). This element MAY be present if the wallet type requires it. @@ -69,7 +69,7 @@ This element MAY be present if the wallet type requires it. If present it MUST ## JSON schema -The walletstore follows a similar format to that of the keystore described in [EIP-2333](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2333.md). +The walletstore follows a similar format to that of the keystore described in [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333). ```json { From 23a91a8b78372e87e733b322064448067eb34cfb Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 27 Nov 2019 12:48:32 +0000 Subject: [PATCH 07/13] Fix email format --- EIPS/eip-2386.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2386.md b/EIPS/eip-2386.md index e990bc18e31bf..02bf058432840 100644 --- a/EIPS/eip-2386.md +++ b/EIPS/eip-2386.md @@ -1,7 +1,7 @@ --- eip: 2386 title: Ethereum 2 Walletstore -author: Jim McDonald (Jim@mcdee.net) +author: Jim McDonald discussions-to: https://ethereum-magicians.org/t/eip-2386-walletstore/3792 status: Draft type: Standards Track From 5acbbfca9ccfd5c842a968166795166c696b3a54 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 4 Dec 2019 09:37:30 +0000 Subject: [PATCH 08/13] Update motivation --- EIPS/eip-2386.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/EIPS/eip-2386.md b/EIPS/eip-2386.md index 02bf058432840..421b7180106f0 100644 --- a/EIPS/eip-2386.md +++ b/EIPS/eip-2386.md @@ -20,7 +20,9 @@ Ethereum has the concept of keystores: pieces of data that define a key (see [EI ## Motivation -Ethereum wallets often require additional metadata above that in the keystore, for example a hierarchical deterministic wallet needs to know the seed and index of the last account created to generate new accounts. In addition, wallets themselves can have names. Standardizing this information and how it is stored allows it to be portable between different wallet providers with minimal effort. +There are multiple different methods to generate private keys. They may, for example, be generated from random data (_i.e._ non-deterministically) or from seed data and a deterministic path (_i.e._ hierarchical deterministic). Historically, individual keys have been generated without reference to each other, however the idea of the wallet being both a grouping of keys and a definition of how future keys will be generated allows a higher degree of flexibility. A single user could have multiple wallets that have different levels of security on them, different key generation methods, _etc._ If a user has multiple wallets they need identification, both programmatically and in a user-friendly fashion. + +Given that a wallet has an amount of data and metadata that is useful when accessing existing keys and creating new keys, standardizing this information and how it is stored allows it to be portable between different wallet providers with minimal effort. ## Specification From 4494da0966afa7318ec0157948821b19c4248805 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 13 May 2020 11:43:15 +0100 Subject: [PATCH 09/13] Reduce scope to hierarchical deterministice wallets only --- EIPS/eip-2386.md | 42 +++++++++++++----------------------------- 1 file changed, 13 insertions(+), 29 deletions(-) diff --git a/EIPS/eip-2386.md b/EIPS/eip-2386.md index 421b7180106f0..abedc76feba87 100644 --- a/EIPS/eip-2386.md +++ b/EIPS/eip-2386.md @@ -1,6 +1,6 @@ --- eip: 2386 -title: Ethereum 2 Walletstore +title: Ethereum 2 Hierarchical Deterministic Walletstore author: Jim McDonald discussions-to: https://ethereum-magicians.org/t/eip-2386-walletstore/3792 status: Draft @@ -12,21 +12,21 @@ requires: 2333, 2334 ## Simple Summary -A JSON format for the storage and retrieval of Ethereum 2 wallet definitions. +A JSON format for the storage and retrieval of Ethereum 2 hierarchical deterministic (HD) wallet definitions. ## Abstract -Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets can be created. +Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets are created. ## Motivation -There are multiple different methods to generate private keys. They may, for example, be generated from random data (_i.e._ non-deterministically) or from seed data and a deterministic path (_i.e._ hierarchical deterministic). Historically, individual keys have been generated without reference to each other, however the idea of the wallet being both a grouping of keys and a definition of how future keys will be generated allows a higher degree of flexibility. A single user could have multiple wallets that have different levels of security on them, different key generation methods, _etc._ If a user has multiple wallets they need identification, both programmatically and in a user-friendly fashion. +Hierarchical deterministic wallets create keys from a _seed_ and a _path_. The seed needs to be accessible to create new keys, however it should also be protected to the same extent as private keys to stop it from becoming an easy attack vector. The path, or at least the variable part of it, needs to be stored to ensure that keys are not duplicated. Providing a standard method to do this can promote interoperability between wallets and similar software. Given that a wallet has an amount of data and metadata that is useful when accessing existing keys and creating new keys, standardizing this information and how it is stored allows it to be portable between different wallet providers with minimal effort. ## Specification -The elements of a walletstore are as follows: +The elements of a hierarchical deterministic walletstore are as follows: ### UUID @@ -50,24 +50,19 @@ This element MUST be present. It MUST be the integer `1`. The `type` provided is the type of wallet. This informs mechanisms such as key generation. -This element MUST be present. It MUST be one of the following two strings: - - - `non-deterministic`: defined for wallets that create private keys from random information - - `hierarchical deterministic`: defined for wallets that create private keys based on the hierarchical deterministic method as outlined in [EIP-2334](https://eips.ethereum.org/EIPS/eip-2334) +This element MUST be present. It MUST be the string `hierarchical deterministic`. ### Crypto -The `crypto` provided is the secure storage of a secret for wallets that require this information. For example `hierarchical deterministic` wallets have a seed from which they calculate individual private keys. - -The `crypto` section follows the definition described in [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333). +The `crypto` provided is the secure storage of a secret for wallets that require this information. For hierarchical deterministic wallets this is the seed from which they calculate individual private keys. -This element MAY be present if the wallet type requires it. +This element MUST be present. It MUST be an object that follows the definition described in [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333). ### Next Account -The `nextaccount` provided is the next account to generate for wallets that require this information. For example, `hierarchical deterministic` wallets create private keys based on a path that has an incrementing value (the first wallet will be `m/12381/60/0/0`, the second `m/12381/60/1/0`, the third `m/12381/60/2/0` etc.). +The `nextaccount` provided is the index to be supplied to the path `m/12381/60//0` when creating a new private key from the seed. -This element MAY be present if the wallet type requires it. If present it MUST be a non-negative integer. +This element MUST be present if the wallet type requires it. It MUST be a non-negative integer. ## JSON schema @@ -116,6 +111,8 @@ The walletstore follows a similar format to that of the keystore described in [E "type", "uuid", "version" + "crypto" + "nextaccount" ], "title": "Walletstore" }, @@ -148,18 +145,7 @@ A standard for walletstores, similar to that for keystores, provides a higher le ## Test Cases -### Non-deterministic Test Vector - -```json -{ - "name": "Test wallet 1", - "type": "non-deterministic", - "uuid": "5d71e10b-6e00-4cab-a5a0-866a5d8843c3", - "version": 1 -} -``` - -### Hierarchical deterministic Test Vector +### Test Vector Password `'testpassword'` Seed `0x147addc7ec981eb2715a22603813271cce540e0b7f577126011eb06249d9227c` @@ -200,8 +186,6 @@ Seed `0x147addc7ec981eb2715a22603813271cce540e0b7f577126011eb06249d9227c` ## Implementation -A Go implementation of the non-deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-nd](https://github.com/wealdtech/go-eth2-wallet-nd). - A Go implementation of the hierarchical deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-hd](https://github.com/wealdtech/go-eth2-wallet-hd). ## Copyright From be4827b9d8f06e659e9792f3a29134a7c0d30ac3 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Thu, 10 Sep 2020 20:11:48 +0100 Subject: [PATCH 10/13] Update EIPS/eip-2386.md Co-authored-by: Micah Zoltu --- EIPS/eip-2386.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/EIPS/eip-2386.md b/EIPS/eip-2386.md index abedc76feba87..80398448119c4 100644 --- a/EIPS/eip-2386.md +++ b/EIPS/eip-2386.md @@ -188,7 +188,9 @@ Seed `0x147addc7ec981eb2715a22603813271cce540e0b7f577126011eb06249d9227c` A Go implementation of the hierarchical deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-hd](https://github.com/wealdtech/go-eth2-wallet-hd). +## Security Considerations +TBD + ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). - From 53aec280c8311febe2afe6724e3e01505268b70a Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Thu, 10 Sep 2020 20:15:07 +0100 Subject: [PATCH 11/13] Update references to EIPs --- EIPS/eip-2386.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/EIPS/eip-2386.md b/EIPS/eip-2386.md index 80398448119c4..a23199ee0afd6 100644 --- a/EIPS/eip-2386.md +++ b/EIPS/eip-2386.md @@ -7,7 +7,7 @@ status: Draft type: Standards Track category: ERC created: 2019-11-21 -requires: 2333, 2334 +requires: 2334, 2335 --- ## Simple Summary @@ -16,7 +16,7 @@ A JSON format for the storage and retrieval of Ethereum 2 hierarchical determini ## Abstract -Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets are created. +Ethereum has the concept of keystores: pieces of data that define a key (see [EIP-2335](https://eips.ethereum.org/EIPS/eip-2335) for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets are created. ## Motivation @@ -56,17 +56,17 @@ This element MUST be present. It MUST be the string `hierarchical deterministic The `crypto` provided is the secure storage of a secret for wallets that require this information. For hierarchical deterministic wallets this is the seed from which they calculate individual private keys. -This element MUST be present. It MUST be an object that follows the definition described in [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333). +This element MUST be present. It MUST be an object that follows the definition described in [EIP-2335](https://eips.ethereum.org/EIPS/eip-2335). ### Next Account -The `nextaccount` provided is the index to be supplied to the path `m/12381/60//0` when creating a new private key from the seed. +The `nextaccount` provided is the index to be supplied to the path `m/12381/60//0` when creating a new private key from the seed. The path follows [EIP-2334](https://eips.ethereum.org/EIPS/eip-2334). This element MUST be present if the wallet type requires it. It MUST be a non-negative integer. ## JSON schema -The walletstore follows a similar format to that of the keystore described in [EIP-2333](https://eips.ethereum.org/EIPS/eip-2333). +The walletstore follows a similar format to that of the keystore described in [EIP-2335](https://eips.ethereum.org/EIPS/eip-2335). ```json { From a066b68162a484e7be4814ea3e59f2a809e3618c Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Thu, 10 Sep 2020 20:29:04 +0100 Subject: [PATCH 12/13] Added security section --- EIPS/eip-2386.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/EIPS/eip-2386.md b/EIPS/eip-2386.md index a23199ee0afd6..543ed4999d4aa 100644 --- a/EIPS/eip-2386.md +++ b/EIPS/eip-2386.md @@ -189,7 +189,12 @@ Seed `0x147addc7ec981eb2715a22603813271cce540e0b7f577126011eb06249d9227c` A Go implementation of the hierarchical deterministic wallet can be found at [https://github.com/wealdtech/go-eth2-wallet-hd](https://github.com/wealdtech/go-eth2-wallet-hd). ## Security Considerations -TBD + +The seed stored in the `crypto` section of the wallet can be used to generate any key along the derived path. As such, the security of all keys generated by HD wallets is reduced to the security of the passphrase and strength of the encryption used to protect the seed, regardless of the security of the passphrase and strength of the encryption used to protect individual keystores. + +It is possible to work with only the walletstore plus an index for each key, in which case stronger passphrases can be used as decryption only needs to take place once. It is also possible to use generated keystores without the walletstore, in which case a breach of security will expose only the keystore. + +An example high-security configuration may involve the walletstore existing on an offline computer, from which keystores are generated. The keystores can then be moved individually to an online computer to be used for signing. ## Copyright From 7b2341441e72770ab36e535c463001ec4d404afa Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Thu, 10 Sep 2020 20:29:54 +0100 Subject: [PATCH 13/13] Update EIPS/eip-2386.md Co-authored-by: Micah Zoltu --- EIPS/eip-2386.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-2386.md b/EIPS/eip-2386.md index 543ed4999d4aa..0d3381e65bae4 100644 --- a/EIPS/eip-2386.md +++ b/EIPS/eip-2386.md @@ -64,7 +64,7 @@ The `nextaccount` provided is the index to be supplied to the path `m/12381/60/< This element MUST be present if the wallet type requires it. It MUST be a non-negative integer. -## JSON schema +### JSON schema The walletstore follows a similar format to that of the keystore described in [EIP-2335](https://eips.ethereum.org/EIPS/eip-2335).