Adding W3C Standard Verifiable Credentials support to ACA-Py

--- tags: CWU --- # Adding W3C Standard Verifiable Credentials support to ACA-Py [![hackmd-github-sync-badge](https://hackmd.io/AtgNvApsQ1OAlhnn3Xfetw/badge)](https://hackmd.io/AtgNvApsQ1OAlhnn3Xfetw) - [Digital Marketplace Opportunity](https://digital.gov.bc.ca/marketplace/opportunities/code-with-us/3f9f0e86-b8bf-47ee-9f3d-5b272f9ec845) - [BCGov Design Document](https://docs.google.com/document/d/1YamSGM2FX34uXp4otWeHH976pyxN4Jaz59llypOf_kY/edit#) - [ACA-Py working branch](https://github.com/animo/aries-cloudagent-python/tree/cwu-bbs) ## Table Of Contents [TOC] ## What we're looking for - AATH Issue Credential video. - AATH JSON-LD Issue Credential - AATH BBS+ Issue Credential - Standalone non-Aries proof with JSON-LD + BBS - Merge into separate ACA-Py branch - Documentation has been implemented in code for the API to use the new credential types, and a summary markdown file with API documentation will be added ## Status - VC / Linked Data Proofs - Sign document / Verify document - Issue credentail / Verify credentail - Create presentation / verify presentation - Ed25519Signature2018 Suite - Still needed - BbsBlsSignature2020 - BbsBlsSignatureProof2020 - Issue Credential - API finished - Initial AATH test working - AATH needs some restructure to work nicely with the new format - Credentials stored in memory or using indy-sdk (Andrew) - Still needed - Some consistency checks (e.g. issuer sends credential that doesn't match request) - Unit tests - Issuing BBS signatures (however this is mostly lower level stuff) - [Opt.] Issue and receive `did:sov` credentials. - Wont do this until the SICPA resolver is merged - Records can be queried from the admin API (SKlump) - DID Key support - Ed25519 DID key resolver added - Admin API extendend to support creating did:key dids - Still needed - Creating and retrieving Bls did keys - BBS - Basic FFI wrapper done - Still needs - Python idiomatic layer on top of ffi wrapper - Bls key management - Present Proof - Presentation Exchange PR open (Shaanjot) - No AATH work yet - V2 missing in AATH - Still needs Aries integration ## Scope & Requirements The goal of this opportunity is to add full JSON-LD VC support to ACA-Py. ACA-Py already includes a, by default disabled, admin interface to sign and verify JSON-LD documents (and thus credentials). This support is limited to the `Ed25519` signature type, and doesn't integrate with the credential exchange protocols. The work will include: - Issue JSON-LD credentials using the Issue Credential v2 protocol - Present JSON-LD credentials using the Present Proof v2 protocol - Support `Ed25519Signature2018` signature suite to issue and verify non-zkp credentials - Support `BbsBlsSignature2020` / `BbsBlsSignatureProof2020` signature suites to issue and verify zkp credentials - Extend `did:key` support to the admin api, adding BBS BLS key types - Leverage ACA-Py storage to store, query and retrieve JSON-LD credentials - Extend AATH to test credential exchange between different ACA-Py (and other) agents ### Out of scope #### Interoperability testing with Aries Framework Go using AATH The backchannel for Aries Framework Go (AFGO) only supports DID exchange at the moment, therefore we cannot test JSON-LD based credential exchange with AFGO. Extending the test harness and ACA-Py backchannel to support JSON-LD based credentials is in scope. If AFGO makes enough progress on their backchannel during the time span of this oppurtunity, we will make our best efforts to complete interoperability testing with AFGO using AATH. In addition to the AFGO backchannel supporting the issue-credential and present-proof protocols, the following features can have an impact on the scope of interoperability testing: - Support for Presentation Exchange in ACA-Py (see [Presentation Exchange attachment format](#Presentation-Exchange-attachment-format)) - Support for BBS+ signatures in Presentation Exchange in AFGO (see [Interop with Aries Framework Go](#Interop-with-Aries-Framework-Go)) #### Presentation Exchange attachment format The goal is to integrate with the presentation exchange format. However, as the work on presentation exchange has not started yet and because of the lack of a clear timeline, we're unsure we'll be able to accomplish this task in the given time frame. If presentation exchange isn't ready in the course of this project, a very simple workaround will be implemented to show agent-to-agent communication regarding JSON-LD credentials. #### Indy Storage Because only Aries Askar has support for multiple tag values, the Indy non-secrets storage requires a different implementation. In order to complete the project in the given time frame the Indy implementation will be omitted for now. Andrew will look into this further. #### Unified Admin API Because it's hard to foresee the possible barriers when it comes to providing a unified issuance and verification API for both Indy and JSON-LD credentials, our implementation will initially focus on separate payload formats for the credential types. However, we will investigate this topic as part of this opportunity. #### Credential Manifest attachment format At the moment, interoperability with AFGO is more important than supporting the [Credential Manifest](https://identity.foundation/credential-manifest) standard. Therefore we will implement the issue credential format AFGO implemented. #### BBS+ Features Below a table is given showing what BBS+ related features are in scope for this project. ZKP and selective disclosure are definitely in the scope of this project. Revocation and ZKP predicates are definitely out of scope because these are still under development. Domain proof and required disclosure are to be determined based on the availability of these features in the BBS+ library. The table will be updated accordingly. | Capability | In scope | | ---------------------- | ------------------- | | ZKP | YES | | Selective Disclosure | YES | | Domain Proof | MAYBE? | | Revocation | NO | | Required Disclosure | MAYBE? | | Integer ZKP Predicates | NO |  ### Related Projects Projects related to this opportunity - Issue Credential / Present Proof V2: Stephen Klump - Presentation Exchange Format: Shaanjot Gill - Aries Agent Test Harness: Sheldon Regular - JSON-LD Credential Storage / Search: Andrew Whitehead ### Interop with Aries Framework Go Part of this opportunity is to show interop with at least one other framework. Aries Framework Go doesn't support the BBS+ signature suite for the credential exchange protocols yet. ACA-Py also doesn't support the presentation exchange attachment format yet. This means interop can only be partly shown, based on the progress of these features. | Feature | Interop | | -------- | -------- | | Presentation Exchange in ACA-Py | Ed25519 based credential issuance and verification between ACA-Py and AFGO | | BBS+ support for Presentation Exchange in AFGO | BBS+ based credential issuance and verification between ACA-Py and AFGO | ## Requirements - Credential Storage - AATH Issue Credential / Present Proof v2 - Presentation Exchange - Present Proof v2 ## Phases The four phases can be divided into two main groups which focus on non-ZKP and ZKP credential support. Below are the tasks that will be executed for each of the phases. Tasks will be described in greater detail before starting on the task at hand. ### Non-ZKP JSON-LD credential support for ACA-Py **Phase 2 / 3** - Implement issue credential attachment format as implemented in AFGO - Add pluggable JSON-LD signature module to ACA-Py - Add Ed25519 signatue suite to JSON-LD signature module - Add present proof attachment format. Either by integrating with presentation exchange, or creating a simple workaround format. - Extend support for did:key in ACA-Py - Extend AATH to support new credential format - Documentation ### BBS+ based JSON-LD credential support for ACA-Py **Phase 4 / 5** - Add Python wrapper to ffi-bbs-signatures repo - Add BBS signature suite to JSON-LD signature module - Extend JSON-LD signature module to support selective disclosure using JSON-LD framing - Support BBSBLS keys for did:key - Extend AATH to support JSON-LD credentials using BBS+ signatures - Documentation ## Present Proof Present Proof still needs to be implemented in ACA-Py, however a lot of the work of the opportunity can be done in parallel to this work. The indy credential format and exchange protocol can only accommodate indy based credentials. To support the exchange of JSON-LD based credentials with support for predicates and selective disclosure the [DIF Presentation Exchange](https://identity.foundation/presentation-exchange) will be used as described in [RFC 0510: Presentation-Exchange Attachment format for requesting and presenting proofs](https://github.com/hyperledger/aries-rfcs/blob/master/features/0510-dif-pres-exch-attach/README.md) As part of the V2 version of the present proof protocol, the Admin API will extendend to support the new `dif` (Presentation Exchange) format. This will mostly be in line with the presentation exchange format, removing fields that can be provided by ACA-Py, simplifying parts that can be abstracted in ACA-Py. By providing mulitple formats in the Admin API a proposal/request for multiple proof formats can be provided. This allows the prover/verifier to select the preferred format to use. ## Issue Credential  - Credential Manifest - Presentation Submission OR separate Present Proof protocol - AFGO doesn't support credential manifest yet, uses own implementation. - [Issue Credential V2](https://github.com/hyperledger/aries-cloudagent-python/pull/930) - Support for multiple formats - Format specific data is stored in separate record - Credential Preview is only one layer. Credential Manifest is also limited - DIF Format: Select keyType / DID to use ## Credential Querying / Storage With the addition for a new credential format some way to query and store JSON-LD based credentials need to be added to ACA-Py. We can make use of tags to filter for credentials. Tags can include: - Schemas (Json Schema / JSON-LD Context) - Attribute values (Normalize for nested values, ) - Algorithm used Multiple tag values can be used in Aries Askar, however not in the Indy non-secrets storage. This means the exact implementation of the query method / tag storage used is dependent on the underlying storage method. ## JSON-LD VCs To handle JSON-LD based credentials, we plan to create a few artifacts. The diagram below shows these components (shown in red) and how they relate to other, preexisting components (shown in green). A description of the components is given below. <iframe style="border:none" width="800" height="450" src="https://whimsical.com/embed/ELssJc9qCjiz2zuzZXN1ju@2Ux7TurymNKpMZw7SxHx"></iframe> ### Verifiable Credentials - Linked Data Proofs Module This component holds the linked data proofs related functionality. Because ZKP requires additional functionality (e.g. framing), we've decided to split the functionalities of this component into two groups: ZKP and NON-ZKP (e.g. Ed25119). ### Signature Suite We plan to make the architecture in a way that it allows for pluggable signature suites. These suites can then vary in the canonicalization, digest and proof algorithms they use. ### ffi-bss-signatures Python Wrapper This component wraps Ursa's BBS+ related functionality so its accessible from withing Python. There is a repository [ursa-bbs-py](https://github.com/andrewwhitehead/ursa-bbs-py) created by Andrew that wraps Ursa's BBS+ functionality, but it's slightly outdated and uses [PyO3](https://github.com/PyO3/pyo3) to generate the Python bindings. MATTR Global has an [ffi-bbs-signatures](https://github.com/mattrglobal/ffi-bbs-signatures) repository that currently holds fast-forward interface wrappers for both .NET and Objective-C. We think it would be best to add a Python wrapper to this repository and use that instead of the `ursa-bbs-py` repository.   ### The gap between JSON-LD Proofs and Verifiable Credentials Whats missing: - Context URLS - Credentials: https://www.w3.org/2018/credentials/v1 - BBS+ https://w3id.org/security/bbs/v1 #### Issue Credential The issue credential method issues a credential by adding a linked data proof to the credential document. The steps include: - Verifying if all properties are present (credential, suite, document loader, verification method, purpose) - check credential method (port from [`vc.js`](https://github.com/transmute-industries/vc.js/blob/6292bd2cef0490b226014d187cbfa8c003699d55/packages/vc.js/src/vc-ld/checkCredential.ts#L26) and [`vc-js`](https://github.com/digitalbazaar/vc-js/blob/44ca660f62ad3569f338eaaaecb11a7b09949bd2/lib/vc.js#L496)) - Check if any properties are present that are not defined in the context (port from [`jsonld-checker`](https://github.com/gjgd/jsonld-checker)) - Sign Additional tasks: - [CredentialIssuancePurpose](https://github.com/transmute-industries/vc.js/blob/6292bd2cef0490b226014d187cbfa8c003699d55/packages/vc.js/src/vc-ld/purposes/CredentialIssuancePurpose.ts) #### Verify Presentation The verify presentation method verifies a verifiable presentation and its credentials. The steps include: - Verifying if all top level properties are present (document loader, presentation) - check presentation method (port from `vc.js` and `vc-js`) - verify all credentials - verify presentation - basic subject authentication? ##### Derive Proof This is TBD. The derive proof will be used for BBS+ signatures. Important to note that no private key is needed to derive proof (at least for the unbound signature proof) Input: - VC - Frame - Suite #### Create Presentation - ... ## AATH - Focus on ACA-Py for now - Discussion: Multiple test suites vs same suites different inputs - Multiple test-suites to make implementation easier ## DID:Key - Extend API to support multiple did methods - Keep sov default and without prefix? - `{"method": "key", "options": {"keyType": "ed25519"}}` - `{"method": "key", "options": {"keyType": "bls12381g2"}}` - `{"method": "sov"}` (default) - Add generic interface to map key to document and document to key - Integrate with SICPA uniresolver project? - https://hackmd.io/@dbluhm/uniresolver-acapy ## Todo - Verify BBS+ flow (w/ Tobias) - Check w/ AFGO about: - Issue credential attachment format - BBS+ presentation exchange timeline - Aries attachment testing limitation - Task management platform  ## Resources - [Mattr.global API reference](https://learn.mattr.global/api-ref) - https://medium.com/swlh/json-web-signature-jws-and-jws-detached-for-a-five-year-old-88729b7b1a68 - https://w3c-ccg.github.io/lds-jws2020/ - https://lists.w3.org/Archives/Public/public-credentials/2020Jun/0100.html - [VC-HTTP-API](https://github.com/w3c-ccg/vc-http-api) - [Aries Agent Test Harness](https://github.com/hyperledger/aries-agent-test-harness) - [Aries Cloud Agent Python](https://github.com/hyperledger/aries-cloudagent-python) - [JWT vs Linked Data Proofs: comparing Verifiable Credentials](https://medium.com/mattr-global/jwt-vs-linked-data-proofs-comparing-vc-assertion-formats-a2a4e6671d57) - [VC Data Model](https://www.w3.org/TR/vc-data-model/) - [Verifiable Credentials Implementation Guidelines 1.0](https://w3c.github.io/vc-imp-guide/) - [Linked Data Cryptograhpic Suite Registry](https://w3c-ccg.github.io/ld-cryptosuite-registry/) ### DID Key - [Python Multicodec](https://github.com/multiformats/py-multicodec) - [Multicodec](https://github.com/multiformats/multicodec) - [The `did:key` Method](https://w3c-ccg.github.io/did-method-key/) ### Protocols - [Issue Credential Protocol 1.0](https://github.com/hyperledger/aries-rfcs/blob/master/features/0036-issue-credential/README.md) - [Issue Credential Protocol 2.0](https://github.com/hyperledger/aries-rfcs/blob/master/features/0453-issue-credential-v2/README.md) - [Present Proof Protocol 1.0](https://github.com/hyperledger/aries-rfcs/blob/master/features/0037-present-proof/README.md) - [Present Proof Protocol 2.0](https://github.com/hyperledger/aries-rfcs/blob/master/features/0454-present-proof-v2/README.md) - [Credential-Manifest Attachment format for requesting and presenting credentials](https://github.com/hyperledger/aries-rfcs/blob/master/features/0511-dif-cred-manifest-attach/README.md) - [Presentation Exchange Attachment format for requesting and presenting proofs](https://github.com/hyperledger/aries-rfcs/blob/master/features/0510-dif-pres-exch-attach/README.md) - [DIF Presentation Exchange](https://identity.foundation/presentation-exchange/) - [DIF Credential Manifest](https://identity.foundation/credential-manifest/) - [Verifiable Presentation Request Specification v0.1](https://w3c-ccg.github.io/vp-request-spec/) - [Aries Framework Go Presentation Exchange Example](https://github.com/hyperledger/aries-framework-go/tree/main/pkg/doc/presexch) ### JSON-LD - [Orie Steele - Mental Models of JSON-LD and what a "Document Loader" really does](https://www.youtube.com/watch?v=-yUbMDft5O0) - [PyLD](https://github.com/digitalbazaar/pyld) - [JSON-LD Framing](https://w3c.github.io/json-ld-framing) - [JSON-LD Signatures NodeJS](https://github.com/digitalbazaar/jsonld-signatures) - [JSON-LD Normalization](https://json-ld.github.io/normalization/spec/index.html) - [LD Proofs .NET](https://github.com/trinsic-id/ld-proofs-dotnet) - [Linked Data Proofs](https://w3c-ccg.github.io/ld-proofs/) ### BBS - [Ursa BBS+](https://github.com/hyperledger/ursa/tree/master/libzmix/bbs) - [FFI BBS Signatures](https://github.com/mattrglobal/ffi-bbs-signatures) - [BBS+ Signatures 2020](https://w3c-ccg.github.io/ldp-bbs2020/) - [BBS+ Signature Scheme](https://mattrglobal.github.io/bbs-signatures-spec/) - [A solution for privacy-preserving Verifiable Credentials](https://medium.com/mattr-global/a-solution-for-privacy-preserving-verifiable-credentials-f1650aa16093) - [Using privacy-preserving ZKP credentials on the MATTR Platform](https://mattr.global/using-privacy-preserving-zkp-credentials-on-the-mattr-platform) - [Tobias Looker on BBS+ use cases, DIF Interop WG 25Nov2020](https://www.youtube.com/watch?v=slkbFW6imUk) - [Intro to ZKPs using BBS+ signatures](https://www.youtube.com/watch?v=hXxQqQLBVZ8) - [BBS+ Signatures - Part 2](https://www.youtube.com/watch?v=AVnCVzW0rkI) - [BLS12-381 For The Rest Of Us](https://hackmd.io/@benjaminion/bls12-381) Path for BBS inside AFGO: pkg/doc/signature/suite/{bbsblssignature2020, bbsblssignatureproof2020} https://github.com/hyperledger/aries-framework-go/blob/1a3d640d581227fe5f6c629e71b66d12c365c0d0/pkg/doc/signature/suite/bbsblssignatureproof2020/signer_test.go ### Ed25519 - [Plugfest 2020 Test Suite](https://github.com/w3c-ccg/vc-http-api/tree/master/packages/plugfest-2020) - [Ed25519 Signature 2018](https://w3c-ccg.github.io/lds-ed25519-2018) - [Plugfest Artifacts / Information](https://lists.w3.org/Archives/Public/public-credentials/2020Jun/0100.html)