From b9cacee9253912be17c583e7670a2976c4c66149 Mon Sep 17 00:00:00 2001 From: Joel Thorstensson Date: Sat, 1 Aug 2020 11:50:04 +0200 Subject: [PATCH 1/4] EIP: Add DID related methods to the JSON-RPC --- EIPS/eip-add-did-related-methods.md | 179 ++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 EIPS/eip-add-did-related-methods.md diff --git a/EIPS/eip-add-did-related-methods.md b/EIPS/eip-add-did-related-methods.md new file mode 100644 index 0000000000000..3dd5b4040c8af --- /dev/null +++ b/EIPS/eip-add-did-related-methods.md @@ -0,0 +1,179 @@ +--- +eip: +title: Add DID related methods to the JSON-RPC +author: Joel Thorstensson (@oed) +discussions-to: +status: Draft +type: Standards Track +category: Interface +created: 2020-08-01 +--- + + + +## Simple Summary + +Add new methods to the JSON-RPC for signing and decrypting JOSE and COSE objects under a new `did_*` prefix. + +## Abstract + +This EIP describes five new methods to add to the JSON-RPC that enables wallets to support DIDs as well as JOSE and COSE. These standards enables wallets to support data decryption as well as authenticated data, both in standard formats using JOSE and COSE. With these new methods apps can request the DID from a users wallet, from which a DID document can be resolved. The DID document contains public keys that can be used for encryption and signature verification. This enables Alice to discover Bobs public keys by only knowing Bobs DID. This EIP does not enforce the user of any particular DID method or JOSE/COSE algorithms, wallets are free to implement these however they wish. + +## Motivation + +There has been one main previous effort ([#130](https://github.com/ethereum/EIPs/issues/130), [#1098](https://github.com/ethereum/EIPs/pull/1098)) to add decryption to ethereum wallets in a standard way. This previous approach used a non stadard way to encode and represent data encrypted using `x25519-xsalsa20-poly1305`. While this approach does provide a functional way to add encryption support to wallets, it does not take into account similar work that has gone into standardizing the way encrypted data is represented, namely using [JOSE](https://datatracker.ietf.org/wg/jose/documents/) and [COSE](https://datatracker.ietf.org/wg/cose/documents/). Both of these are standards from IETF for representing signed and encrypted objects. Another shortcomming of the previous approach is that it's impossible to retreive the `x25519` public key from another user if only an ethereum address is known. Public key discoverability is at the core of the work that is happening with the [W3C DID standard](https://w3c.github.io/did-core), where given a DID a document which contains public keys can always be discovered. Implementations of this standard already exist and are adopted within the Ethereum community, e.g. [`did:ethr`](https://github.com/decentralized-identity/ethr-did-resolver/) and [`did:3`](https://github.com/3box/3id-resolver). Interoperability between JOSE/COSE and DIDs [already exists](https://github.com/decentralized-identity/did-jwt), and work is being done to [strengthen it](https://github.com/decentralized-identity/did-jose-extensions). Adding support for JOSE/COSE and DIDs will enable Ethereum wallets to support a wide range of new use cases such as more traditional authentication using JWTs, as well as new emerging technologies such as [Secure Data Stores](https://identity.foundation/secure-data-store/) and [encrypted data in IPFS](https://github.com/ipld/specs/pull/269). + +## Specification +Five new JSON-RPC methods are specified under the new `did_*` prefix. + +### Auth + +Authenticate the current rpc connection to the DID methods. + +Prompt the user to give permission to the current connection to access the user DID and the given `paths`. + +##### Method: + +`did_authenticate` + +##### Params: + +* `paths` - an array of strings + +##### Returns: + +* `did` - the DID which authentication was given for +* `paths` - the paths which was given permission for + + + +#### CreateJWS + +Creates a JSON Web Signature. + +An additional property `kid` with the value which represents the DID and the key that was used to sign the JWS ([details](https://github.com/decentralized-identity/did-jose-extensions/issues/2)). + +##### Method: + +`did_createJWS` + +##### Params: + +* `payload` - the payload to sign, json object +* `protected` - the protoected header, json object +* `did` - the DID that should sign the message, may include the key fragment, string + +##### Returns: + +A JWS with compact serialization, string + +##### Recommendation: + +Use `secp256k1` for singning, alternatively `ed25519`. + + + +#### CreateCWS + +Creates a CBOR Web Signature. + +An additional property `kid` with the value which represents the DID and the key that was used to sign the CWS. + +##### Method: + +`did_createCWS` + +##### Params: + +* `payload` - the payload to sign, json object +* `protected` - the protoected header, json object +* `did` - the DID that should sign the message, may include the key fragment, string + +##### Returns: + +A CWE encoded as base64, string + +##### Recommendation: + +Use either `secp256k1` for singning. + + + +#### DecryptJWE + +Decrypt the given JWE. + +If the cleartext object contains a property `paths` that contains an array of strings and one of the paths in there are already authenticated using `did_authenticate` the decryption should happen without user confirmation. + +##### Method: + +`did_decryptJWE` + +##### Params: + +* `jwe` - a JWE with compact serialization, string +* `did` - the DID that should try to decrypt the JWE, string + +##### Returns: + +The decrypted cleartext, object + +##### Recommendation: + +Implement decryption using `xchacha20poly1305` and `x25519` for key agreement. + + + +#### DecryptCWE + +Decrypt the given CWE. + +If the cleartext object contains a property `paths` that contains an array of strings and one of the paths in there are already authenticated using `did_authenticate` the decryption should happen without user confirmation. + +##### Method: + +`did_decryptCWE` + +##### Params: + +* `cwe` - a CWE encoded as base64, string +* `did` - the DID that should try to decrypt the CWE, string + +##### Returns: + +The decrypted cleartext, object + +##### Recommendation: + +Implement decryption using `xchacha20poly1305` and `x25519` for key agreement. + + + +## Rationale + +This EIP chooses to rely on DIDs and JOSE/COSE since there is already support for these standards in many places, by current systems and new systems. While most systems today rely on JOSE, support for COSE is also specified because it has growing support due to it's compact encoding of data. By using DIDs and JOSE/COSE wallet implementers can also choose which signing and encryption algorithms that they want to support, since these formats are faily agnostic to specific crypto implementations. + +### Permission system + +A simple permission system is proposed where clients can request permissions though path prefixes, e.g. `/some/permission`. When decryption of a JWE/CWE is requested the wallet should check if the decrypted payload contains a `paths` property. If this property doesn't exist the user may be prompted to confirm that the given rpc connection (app) is allowed to read the decrypted data. If the `paths` property is present in the decrypted data it should contain an array of string paths. If one of the these path prefixes matches with one of the path prefixes the user has already granted persmission for then decrytion should happen automatically without any user confirmation. + +This simple permission system was inspired by some previous comments ([1](https://github.com/ethereum/EIPs/issues/130#issuecomment-329770999), [2](https://medium.com/@wighawag/3-proposals-for-making-web3-a-better-experience-974f97765700)) but avoids data lock in around origins. + +## Implementation + + +[IdentityWallet](https://github.com/3box/identity-wallet-js/): A partial implementation of the `did_*` methods using the 3ID DID. + +[js-did](https://github.com/ceramicnetwork/js-did): A small library which consumes the `did_*` methods. + +[MinimalCipher](https://github.com/digitalbazaar/minimal-cipher): An implementation of DID related encryption for JWE. + +## Security Considerations + + +Both JOSE/COSE and DIDs are standards that have gone though a lot of scrutany. Their security will not be considered in this document. In the specification section, reccomendations are given for which algorightms to use. For signatures `secp256k1` is already used by ethereum and for decryption `xchacha20poly1305` is widely available, very performant, and already used in TLS. + +The main security consideration of this EIP is the suggested permission system. Here various threat models could be considered. However, this EIP does not go into details about how it should work other than suggesting an approach. In the end it is up to wallet implementations to choose how to ask their users for consent. + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 0979d306a9f3f71e20b0576f0ebf02a363095dbe Mon Sep 17 00:00:00 2001 From: Joel Thorstensson Date: Sat, 1 Aug 2020 11:56:20 +0200 Subject: [PATCH 2/4] chore: add discussions url --- EIPS/eip-add-did-related-methods.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-add-did-related-methods.md b/EIPS/eip-add-did-related-methods.md index 3dd5b4040c8af..cef390529aaf4 100644 --- a/EIPS/eip-add-did-related-methods.md +++ b/EIPS/eip-add-did-related-methods.md @@ -2,7 +2,7 @@ eip: title: Add DID related methods to the JSON-RPC author: Joel Thorstensson (@oed) -discussions-to: +discussions-to: https://github.com/ethereum/EIPs/issues/2845 status: Draft type: Standards Track category: Interface From 94ffb38c8bae7b20890d0562804f57de10413bd6 Mon Sep 17 00:00:00 2001 From: Joel Thorstensson Date: Sat, 1 Aug 2020 12:01:58 +0200 Subject: [PATCH 3/4] chore: fix typos --- EIPS/eip-add-did-related-methods.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-add-did-related-methods.md b/EIPS/eip-add-did-related-methods.md index cef390529aaf4..2657d65d38d90 100644 --- a/EIPS/eip-add-did-related-methods.md +++ b/EIPS/eip-add-did-related-methods.md @@ -21,7 +21,7 @@ This EIP describes five new methods to add to the JSON-RPC that enables wallets ## Motivation -There has been one main previous effort ([#130](https://github.com/ethereum/EIPs/issues/130), [#1098](https://github.com/ethereum/EIPs/pull/1098)) to add decryption to ethereum wallets in a standard way. This previous approach used a non stadard way to encode and represent data encrypted using `x25519-xsalsa20-poly1305`. While this approach does provide a functional way to add encryption support to wallets, it does not take into account similar work that has gone into standardizing the way encrypted data is represented, namely using [JOSE](https://datatracker.ietf.org/wg/jose/documents/) and [COSE](https://datatracker.ietf.org/wg/cose/documents/). Both of these are standards from IETF for representing signed and encrypted objects. Another shortcomming of the previous approach is that it's impossible to retreive the `x25519` public key from another user if only an ethereum address is known. Public key discoverability is at the core of the work that is happening with the [W3C DID standard](https://w3c.github.io/did-core), where given a DID a document which contains public keys can always be discovered. Implementations of this standard already exist and are adopted within the Ethereum community, e.g. [`did:ethr`](https://github.com/decentralized-identity/ethr-did-resolver/) and [`did:3`](https://github.com/3box/3id-resolver). Interoperability between JOSE/COSE and DIDs [already exists](https://github.com/decentralized-identity/did-jwt), and work is being done to [strengthen it](https://github.com/decentralized-identity/did-jose-extensions). Adding support for JOSE/COSE and DIDs will enable Ethereum wallets to support a wide range of new use cases such as more traditional authentication using JWTs, as well as new emerging technologies such as [Secure Data Stores](https://identity.foundation/secure-data-store/) and [encrypted data in IPFS](https://github.com/ipld/specs/pull/269). +There has been one main previous effort ([#130](https://github.com/ethereum/EIPs/issues/130), [#1098](https://github.com/ethereum/EIPs/pull/1098)) to add decryption to Ethereum wallets in a standard way. This previous approach used a non standard way to encode and represent data encrypted using `x25519-xsalsa20-poly1305`. While this approach does provide a functional way to add encryption support to wallets, it does not take into account similar work that has gone into standardizing the way encrypted data is represented, namely using [JOSE](https://datatracker.ietf.org/wg/jose/documents/) and [COSE](https://datatracker.ietf.org/wg/cose/documents/). Both of these are standards from IETF for representing signed and encrypted objects. Another shortcoming of the previous approach is that it's impossible to retrieve the `x25519` public key from another user if only an Ethereum address is known. Public key discoverability is at the core of the work that is happening with the [W3C DID standard](https://w3c.github.io/did-core), where given a DID a document which contains public keys can always be discovered. Implementations of this standard already exist and are adopted within the Ethereum community, e.g. [`did:ethr`](https://github.com/decentralized-identity/ethr-did-resolver/) and [`did:3`](https://github.com/3box/3id-resolver). Interoperability between JOSE/COSE and DIDs [already exists](https://github.com/decentralized-identity/did-jwt), and work is being done to [strengthen it](https://github.com/decentralized-identity/did-jose-extensions). Adding support for JOSE/COSE and DIDs will enable Ethereum wallets to support a wide range of new use cases such as more traditional authentication using JWTs, as well as new emerging technologies such as [Secure Data Stores](https://identity.foundation/secure-data-store/) and [encrypted data in IPFS](https://github.com/ipld/specs/pull/269). ## Specification Five new JSON-RPC methods are specified under the new `did_*` prefix. @@ -155,7 +155,7 @@ This EIP chooses to rely on DIDs and JOSE/COSE since there is already support fo ### Permission system -A simple permission system is proposed where clients can request permissions though path prefixes, e.g. `/some/permission`. When decryption of a JWE/CWE is requested the wallet should check if the decrypted payload contains a `paths` property. If this property doesn't exist the user may be prompted to confirm that the given rpc connection (app) is allowed to read the decrypted data. If the `paths` property is present in the decrypted data it should contain an array of string paths. If one of the these path prefixes matches with one of the path prefixes the user has already granted persmission for then decrytion should happen automatically without any user confirmation. +A simple permission system is proposed where clients can request permissions though path prefixes, e.g. `/some/permission`. When decryption of a JWE/CWE is requested the wallet should check if the decrypted payload contains a `paths` property. If this property doesn't exist the user may be prompted to confirm that the given rpc connection (app) is allowed to read the decrypted data. If the `paths` property is present in the decrypted data it should contain an array of string paths. If one of the these path prefixes matches with one of the path prefixes the user has already granted permission for then decryption should happen automatically without any user confirmation. This simple permission system was inspired by some previous comments ([1](https://github.com/ethereum/EIPs/issues/130#issuecomment-329770999), [2](https://medium.com/@wighawag/3-proposals-for-making-web3-a-better-experience-974f97765700)) but avoids data lock in around origins. @@ -171,7 +171,7 @@ This simple permission system was inspired by some previous comments ([1](https: ## Security Considerations -Both JOSE/COSE and DIDs are standards that have gone though a lot of scrutany. Their security will not be considered in this document. In the specification section, reccomendations are given for which algorightms to use. For signatures `secp256k1` is already used by ethereum and for decryption `xchacha20poly1305` is widely available, very performant, and already used in TLS. +Both JOSE/COSE and DIDs are standards that have gone though a lot of scrutany. Their security will not be considered in this document. In the specification section, recommendations are given for which algorithms to use. For signatures `secp256k1` is already used by ethereum and for decryption `xchacha20poly1305` is widely available, very performant, and already used in TLS. The main security consideration of this EIP is the suggested permission system. Here various threat models could be considered. However, this EIP does not go into details about how it should work other than suggesting an approach. In the end it is up to wallet implementations to choose how to ask their users for consent. From 5b9bdaebe3743f083e0a06f315db1b9c70b60bce Mon Sep 17 00:00:00 2001 From: Joel Thorstensson Date: Sat, 1 Aug 2020 17:05:38 +0200 Subject: [PATCH 4/4] chore: update eip number, small editorial fixes --- ...add-did-related-methods.md => eip-2844.md} | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) rename EIPS/{eip-add-did-related-methods.md => eip-2844.md} (89%) diff --git a/EIPS/eip-add-did-related-methods.md b/EIPS/eip-2844.md similarity index 89% rename from EIPS/eip-add-did-related-methods.md rename to EIPS/eip-2844.md index 2657d65d38d90..b4b218efcb8f2 100644 --- a/EIPS/eip-add-did-related-methods.md +++ b/EIPS/eip-2844.md @@ -1,5 +1,5 @@ --- -eip: +eip: 2844 title: Add DID related methods to the JSON-RPC author: Joel Thorstensson (@oed) discussions-to: https://github.com/ethereum/EIPs/issues/2845 @@ -17,7 +17,7 @@ Add new methods to the JSON-RPC for signing and decrypting JOSE and COSE objects ## Abstract -This EIP describes five new methods to add to the JSON-RPC that enables wallets to support DIDs as well as JOSE and COSE. These standards enables wallets to support data decryption as well as authenticated data, both in standard formats using JOSE and COSE. With these new methods apps can request the DID from a users wallet, from which a DID document can be resolved. The DID document contains public keys that can be used for encryption and signature verification. This enables Alice to discover Bobs public keys by only knowing Bobs DID. This EIP does not enforce the user of any particular DID method or JOSE/COSE algorithms, wallets are free to implement these however they wish. +This EIP describes five new methods to add to the JSON-RPC that enables wallets to support *Decentralized Identifiers* (DIDs) as well as *JSON Object Signing and Encryption* (JOSE) and *CBOR Object Signing and Encryption* (COSE). These standards enables wallets to support data decryption as well as authenticated data, both in standard formats using JOSE and COSE. With these new methods apps can request the DID from a users wallet, from which a DID document can be resolved. The DID document contains public keys that can be used for encryption and signature verification. This enables Alice to discover Bobs public keys by only knowing Bobs DID. This EIP does not enforce the user of any particular DID method or JOSE/COSE algorithms, wallets are free to implement these however they wish. ## Motivation @@ -49,18 +49,18 @@ Prompt the user to give permission to the current connection to access the user #### CreateJWS -Creates a JSON Web Signature. +Creates a JSON Web Signature (JWS). An additional property `kid` with the value which represents the DID and the key that was used to sign the JWS ([details](https://github.com/decentralized-identity/did-jose-extensions/issues/2)). -##### Method: +##### Method: `did_createJWS` ##### Params: * `payload` - the payload to sign, json object -* `protected` - the protoected header, json object +* `protected` - the protected header, json object * `did` - the DID that should sign the message, may include the key fragment, string ##### Returns: @@ -69,24 +69,24 @@ A JWS with compact serialization, string ##### Recommendation: -Use `secp256k1` for singning, alternatively `ed25519`. +Use `secp256k1` for signing, alternatively `ed25519`. #### CreateCWS -Creates a CBOR Web Signature. +Creates a CBOR Web Signature (CWS). An additional property `kid` with the value which represents the DID and the key that was used to sign the CWS. -##### Method: +##### Method: `did_createCWS` ##### Params: * `payload` - the payload to sign, json object -* `protected` - the protoected header, json object +* `protected` - the protected header, json object * `did` - the DID that should sign the message, may include the key fragment, string ##### Returns: @@ -95,7 +95,7 @@ A CWE encoded as base64, string ##### Recommendation: -Use either `secp256k1` for singning. +Use `secp256k1` for signing, alternatively `ed25519`. @@ -171,7 +171,7 @@ This simple permission system was inspired by some previous comments ([1](https: ## Security Considerations -Both JOSE/COSE and DIDs are standards that have gone though a lot of scrutany. Their security will not be considered in this document. In the specification section, recommendations are given for which algorithms to use. For signatures `secp256k1` is already used by ethereum and for decryption `xchacha20poly1305` is widely available, very performant, and already used in TLS. +Both JOSE/COSE and DIDs are standards that have gone though a lot of scrutiny. Their security will not be considered in this document. In the specification section, recommendations are given for which algorithms to use. For signatures `secp256k1` is already used by ethereum and for decryption `xchacha20poly1305` is widely available, very performant, and already used in TLS. The main security consideration of this EIP is the suggested permission system. Here various threat models could be considered. However, this EIP does not go into details about how it should work other than suggesting an approach. In the end it is up to wallet implementations to choose how to ask their users for consent.