EIP-2844: Add DID related methods to the JSON-RPC Ethereum Improvement Proposals AllCoreNetworkingInterfaceERCMetaInformational 🚧 Stagnant Standards Track: Interface EIP-2844: Add DID related methods to the JSON-RPC Authors Joel Thorstensson (@oed) Created 2020-08-01 Discussion Link https://github.com/ethereum/EIPs/issues/2845 Table of Contents Simple Summary Abstract Motivation Specification Auth Rationale Permission system Implementation Security Considerations Copyright Simple Summary Add new methods to the JSON-RPC for signing and decrypting JOSE objects under a new did_* prefix. Abstract This EIP describes three 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). These standards enables wallets to support data decryption as well as authenticated data, both in standard formats using JOSE. 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 algorithms, wallets are free to implement these however they wish. Motivation There has been one main previous effort (#130, #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. This is a standard 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, 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 and did:3. Interoperability between JOSE and DIDs already exists, and work is being done to strengthen it. Adding support for JOSE 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 and encrypted data in IPFS. Specification Three 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: nonce - a random string used as a challenge aud - the intended audience of the authentication response paths - an array of strings Returns: A JWS with general serialization containing the following properties: nonce - the random string which was given as a challenge did - the DID which authentication was given for paths - the paths which was given permission for exp - a unix timestamp after which the JWS should be considered invalid aud - optional audience for the JWS, should match the domain which made the request An additional property kid with the value which represents the DID, and the keyFragment that was used to sign the JWS should be added to the protected header (details). CreateJWS Creates a JSON Web Signature (JWS). An additional property kid with the value which represents the DID, and the keyFragment that was used to sign the JWS should be added to the protected header (details). When revocable is set to false the JWS signature should not be possible to revoke. For some DID methods like. did:key this is always the case. For other methods which support key revocation it is necessary to include the version-id in the kid to refer to a specific version of the DID document. When revocable is set to true version-id must not be included in the kid for DID methods that support key revocation. Method: did_createJWS Params: payload - the payload to sign, json object or base64url encoded string protected - the protected header, json object did - the DID that should sign the message, may include the key fragment, string revocable - makes the JWS revocable when rotating keys, boolean default to false Returns: An object containing a JWS with general serialization on the jws property. Recommendation: Use secp256k1 for signing, alternatively ed25519. 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 general serialization, string did - the DID that should try to decrypt the JWE, string Returns: An object containing the cleartext, encoded using base64pad, assigned to the cleartext property. Recommendation: Implement decryption using xchacha20poly1305 and x25519 for key agreement. Rationale This EIP chooses to rely on DIDs and JOSE since there is already support for these standards in many places, by current systems and new systems. By using DIDs and JOSE wallet implementers can also choose which signing and encryption algorithms that they want to support, since these formats are fairly 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 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, 2) but avoids data lock in around origins. Implementation IdentityWallet: An implementation of the wallet side did_* methods using the 3ID DID. key-did-provider-ed25519: An implementation of the wallet side did_* methods using the did:key method. js-did: A small library which consumes the did_* methods. MinimalCipher: An implementation of DID related encryption for JWE. Security Considerations Both JOSE 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. Copyright Copyright and related rights waived via CC0. Citation Please cite this document as: Joel Thorstensson (@oed), "EIP-2844: Add DID related methods to the JSON-RPC [DRAFT]," Ethereum Improvement Proposals, no. 2844, August 2020. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2844. Ethereum Improvement Proposals Ethereum Improvement Proposals ethereum/EIPs Ethereum Improvement Proposals (EIPs) describe standards for the Ethereum platform, including core protocol specifications, client APIs, and contract standards.