Skip to content

Latest commit

 

History

History
219 lines (152 loc) · 13.9 KB

README.md

File metadata and controls

219 lines (152 loc) · 13.9 KB
Raw
eip title author discussions-to status type category created
xyz
Add Credential Provider related methods to the JSON-RPC
Oliver Terbu (@awoie)
Draft
Standards Track
Interface
2021-08-18

Simple Summary

Add new methods to the JSON-RPC for storing, creating, selectively disclosing and proving control of offchain- and onchain credentials under a new creds_* prefix.

Abstract

This EIP describes three methods to add to the JSON-RPC that enables wallets to act as a Credential Provider (CP) to support Verifiabe Credentials (VCs) storage, issuance, selective disclosure and proof of control. VCs are usually self-certifiable attestations from an issuer about the owner of the VC encoded in the credential subject. The owner of the VC can selectively disclose information from those VCs and prove control of the VC to a third-party. Please visit https://www.w3.org/TR/vc-data-model/ for a full explaination of VCs. Since the VC data model is very flexible, this EIP enforces specific rules on VCs and supported proof types to facilitate developer experience and interoperability. This is important for use cases such as sign-in, sign-up and decentralized reputation-based authorization.

This EIP is complementary to EIP-2844.

Motivation

Web3 applications like DAOs, Defi, NFT market places etc. need verifiable offchain and onchain reputation to enable certain features for their end users. Using VCs with LD-Proofs, it will be possible to find a standard representation for all types of identity assertions, and specifically with LD-Proofs, those identity attestations can contain proofs that can be consumed offchain and onchain. EIP-2844 is a good starting point but solves the problem only partially. This EIP builds on top of EIP-2844 and introduces new JSON-RPC methods that are needed to build decentralized reputation for offchain and onchain use.

Web3 is missing a coherent method for requesting identity assertions from their users, e.g. for sign-in and sign-up. The majority of Web3 projects are using an approach where they cryptographically bind a signature produced by the wallet to the identity assertion through either eth.personal.sign or EIP-712. The identity assertion becomes self-certifiable with this approach. The identifier for the user is the Ethereum address. To improve privacy it is important to introduce a mechanism that allows people to selectively disclose the linkage between their primary identifier and their Ethereum address. This can be done through VCs and DIDs.

Specification

Three new JSON-RPC methods are specified under the new creds_* prefix.

Verifiable Credential Proofs

This section provides guidance on recommended LD-Proof Suites and IANA JWS algorithm support of embedded and external proofs for VCs.

Embedded Proofs

CPs SHOULD support the following LD-Proof types for embedded proofs (i.e. VC-LDP):

External Proofs

CPs SHOULD support the following IANA JWS algorithms for external proofs (i.e. VC-JWT):

Supported Verifiable Credentials Profile

VCs that can be used with this specification MUST be valid JSON-LD. VCs and VPs SHOULD use any of the proofs recommended by Embedded Proofs or External Proofs.

Store

Stores the given VC in the CP.

Method:

creds_store

Params:
  • vc - A Verifiable Credential.
Returns:
  • error - OPTIONAL. If vc was malformed or does not comply with the Verifialbe Credentials Profile defined in this specification.

Issue

Issues a VC with the given payload using one of the CP's DIDs.

Method:

creds_issue

Params:
  • payload - REQUIRED. The payload of the Verifiable Credential to be issued.
  • preferred_proofs - OPTIONAL. An ordered array of preferred proof formats and types for the VC to be issued. Each array item is an object with two properties, format and type. format indicates the preferred proof type, which is either jwt for (External Proofs) or ldp for (Embedded Proofs). The type refers to proof type of the VC (see Verifiable Credentials Proofs for a list of valid combinations). If the wallet does not support any of the preferred proofs, the wallet can select a format and type from the list defined in Verifiable Credentials Proofs as a fallback.
Returns:
  • vc - OPTIONAL. Present if the call was successful. A Verifiable Credential that was issued by the CP.
  • error - OPTIONAL. If payload was malformed, does not comply with the Verifialbe Credentials Profile defined in this specification.

Present

Selectively discloses information from the CP. Optionally, holder binding can be requested. For the query, we will use the DIF Presentation Exchange data model.

Method:

creds_present

Params:
  • presentation_defintion - Defines the selective disclosure query with optional holder binding.
  • domain - OPTIONAL. If holder binding was requested, this parameter is mandatory.
  • challenge - OPTIONAL. If holder binding was requested, this parameter is mandatory.
Returns:
  • vp - OPTIONAL. Present if the call was successful. It contains a Verifiable Presentation (VP) that contains the requested VCs from the CP.
  • error - OPTIONAL. Present if presentation_definition was malformed, does not comply with the Verifialbe Credentials Profile defined in this specification.
Examples:
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://identity.foundation/presentation-exchange/submission/v1"
  ],
  "type": ["VerifiablePresentation", "PresentationSubmission"],
  "holder": "did:example:123",
  "presentation_submission": {
    "id": "1d257c50-454f-4c96-a273-c5368e01fe63",
    "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0654",
    "descriptor_map": [
      {
        "id": "vaccination_input",
        "format": "ldp_vp",
        "path": "$.verifiableCredential[0]"
      }
    ]
  },
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://w3id.org/vaccination/v1",
        "https://w3id.org/security/bbs/v1"
      ],
      "id": "urn:uvci:af5vshde843jf831j128fj",
      "type": ["VaccinationCertificate", "VerifiableCredential"],
      "description": "COVID-19 Vaccination Certificate",
      "name": "COVID-19 Vaccination Certificate",
      "expirationDate": "2029-12-03T12:19:52Z",
      "issuanceDate": "2019-12-03T12:19:52Z",
      "issuer": "did:example:456",
      "credentialSubject": {
        "id": "urn:bnid:_:c14n2",
        "type": "VaccinationEvent",
        "batchNumber": "1183738569",
        "countryOfVaccination": "NZ"
      },
      "proof": {
        "type": "BbsBlsSignatureProof2020",
        "created": "2021-02-18T23:04:28Z",
        "nonce": "JNGovx4GGoi341v/YCTcZq7aLWtBtz8UhoxEeCxZFevEGzfh94WUSg8Ly/q+2jLqzzY=",
        "proofPurpose": "assertionMethod",
        "proofValue": "AB0GQA//jbDwMgaIIJeqP3fRyMYi6WDGhk0JlGJc/sk4ycuYGmyN7CbO4bA7yhIW/YQbHEkOgeMy0QM+usBgZad8x5FRePxfo4v1dSzAbJwWjx87G9F1lAIRgijlD4sYni1LhSo6svptDUmIrCAOwS2raV3G02mVejbwltMOo4+cyKcGlj9CzfjCgCuS1SqAxveDiMKGAAAAdJJF1pO6hBUGkebu/SMmiFafVdLvFgpMFUFEHTvElUQhwNSp6vxJp6Rs7pOVc9zHqAAAAAI7TJuDCf7ramzTo+syb7Njf6ExD11UKNcChaeblzegRBIkg3HoWgwR0hhd4z4D5/obSjGPKpGuD+1DoyTZhC/wqOjUZ03J1EtryZrC+y1DD14b4+khQVLgOBJ9+uvshrGDbu8+7anGezOa+qWT0FopAAAAEG6p07ghODpi8DVeDQyPwMY/iu2Lh7x3JShWniQrewY2GbsACBYOPlkNNm/qSExPRMe2X7UPpdsxpUDwqbObye4EXfAabgKd9gCmj2PNdvcOQAi5rIuJSGa4Vj7AtKoW/2vpmboPoOu4IEM1YviupomCKOzhjEuOof2/y5Adfb8JUVidWqf9Ye/HtxnzTu0HbaXL7jbwsMNn5wYfZuzpmVQgEXss2KePMSkHcfScAQNglnI90YgugHGuU+/DQcfMoA0+JviFcJy13yERAueVuzrDemzc+wJaEuNDn8UiTjAdVhLcgnHqUai+4F6ONbCfH2B3ohB3hSiGB6C7hDnEyXFOO9BijCTHrxPv3yKWNkks+3JfY28m+3NO0e2tlyH71yDX0+F6U388/bvWod/u5s3MpaCibTZEYoAc4sm4jW03HFYMmvYBuWOY6rGGOgIrXxQjx98D0macJJR7Hkh7KJhMkwvtyI4MaTPJsdJGfv8I+RFROxtRM7RcFpa4J5wF/wQnpyorqchwo6xAOKYFqCqKvI9B6Y7Da7/0iOiWsjs8a4zDiYynfYavnz6SdxCMpHLgplEQlnntqCb8C3qly2s5Ko3PGWu4M8Dlfcn4TT8YenkJDJicA91nlLaE8TJbBgsvgyT+zlTsRSXlFzQc+3KfWoODKZIZqTBaRZMft3S/",
        "verificationMethod": "did:example:123#key-1"
      }
    }
  ],
  "proof": {
    "type": "Ed25519Signature2018",
    "verificationMethod": "did:example:123#key-0",
    "created": "2021-05-14T20:16:29.565377",
    "proofPurpose": "authentication",
    "challenge": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
    "jws": "eyJhbGciOiAiRWREU0EiLCAiYjY0IjogZmFsc2UsICJjcml0IjogWyJiNjQiXX0..7M9LwdJR1_SQayHIWVHF5eSSRhbVsrjQHKUrfRhRRrlbuKlggm8mm_4EI_kTPeBpalQWiGiyCb_0OWFPtn2wAQ"
  }
}

Rationale

The VC Data Model define Verifiable Presentation but does not provide detail on how to express the constraints that a relying party has on a presentation. The Presentation Exchange Data Model defines a definition and submission format for among other things, verifiable presentations.

The Universal Wallet Interop Spec describes how to use concrete protocols such as Wallet Connect and WACI Presentation Exchange with DID Comm Messaging.

In cases where a holder is directly connected to a verifier over a secure transport, encryption and messaging related standards such as DIDComm are not required, however interoperable data models for expressing presentation requirements and submissions are still needed to support interoperability with existing standards.

This proposal defines a set of API extensions that would enable web3 wallet providers to offer wallet and credential interactions to web origins that already support web3 wallet providers.

This functionality is similar to the interfaces supported by the credential handler api, which does not support the Presentation Exchange Data Model specification.

Implementation

  • TBD
  • TBD
  • TBD

Security Considerations

User consent must be obtained prior to accessing wallet apis.

The relying party MUST ensure that the challenge required by the verifiable presentation are is sufficiently random, and used only once, or that it is some form of expiring verifiable credential encoded as a string.

TODO: The domain must match the web origin requesting or providing credentials or presentations?

In the case that no holder binding is required, the submission details can be tampered with.

TBD

Copyright

Copyright and related rights waived via CC0.