From 14c984e0589a9d013a2286cb2eeeb5f23d4622f2 Mon Sep 17 00:00:00 2001 From: George J Padayatti Date: Mon, 22 Aug 2022 14:00:32 +0530 Subject: [PATCH] Add read, update and deactivate operations Signed-off-by: George J Padayatti --- docs/did/spec.md | 192 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 182 insertions(+), 10 deletions(-) diff --git a/docs/did/spec.md b/docs/did/spec.md index 97a6336..4322887 100644 --- a/docs/did/spec.md +++ b/docs/did/spec.md @@ -6,15 +6,15 @@ A Data Agreement (DA) exists between organisations and individuals in the use of ## Status of This Document -Version 2.0 (Supersedes [Version 1.1](https://github.com/decentralised-dataexchange/automated-data-agreements/blob/main/docs/did-spec.md)) +Version 2.0 (Supersedes Version 1.1 - [https://github.com/decentralised-dataexchange/automated-data-agreements/blob/main/docs/did-spec.md](https://github.com/decentralised-dataexchange/automated-data-agreements/blob/main/docs/did-spec.md)) -## **Authors** +## Authors Mr. George Padayatti (iGrant.io, Sweden) Mr. Lal Chandran (iGrant.io, Sweden) -## **Contributors and Reviewers** +## Contributors and Reviewers Mr. Mr. Jan Lindquist (Linaltec, Sweden) @@ -66,11 +66,28 @@ did:mydata:zJ53MfXX934iYwx6hdQRKonWkVj22t9NczBmwe7To2Yh2sTnS7W32ocTYgvwtQRB3K ## Operations +Each DID registry service will be exposing a DIDComm agent. CRUD operations on DID can then be performed using available DIDComm messages. A new DIDComm protocol ([https://didcomm.org/mydata-did/2.0](https://didcomm.org/mydata-did/2.0)) is specified below for performing CRUD operations. The DID registry service itself will be allocated a DID and an associated DID document will be publicly available at a well-known DID configuration endpoint (`"/.well-known/did-configuration.json"`) of the web server. The audience of this document is expected to be familiar with DIDComm message specification [4] and it’s extensions. + ### Create -The did:mydata identifier corresponds to an agreement in MyData ecosystem. Creation of the identifier assumes that through an out-of-band/didcomm interaction actors involved in the agreement has arrived at terms, i.e both (if 2 actors are involved) parties holds an agreement document with a proof chain ([Data Integrity Model](https://w3c.github.io/vc-data-integrity/)) in it. The agreement document must conform to JSONLD context matching the agreement type, for e.g. A Data Disclosure Agreement must conform to JSONLD context defined [here](https://github.com/decentralised-dataexchange/data-exchange-agreements/blob/main/interface-specs/data-disclosure-agreement-schema/data-disclosure-agreement-schema-context.jsonld). +The did:mydata identifier corresponds to an artefact in MyData ecosystem. Support artefacts are: + +- Agreements - Records the conditions under which 2 parties have come to agreement. Meaning both parties are getting “informed” about the terms. + - [Data Disclosure Agreement (DDA)](https://github.com/decentralised-dataexchange/data-exchange-agreements/blob/main/interface-specs/data-disclosure-agreement-schema/data-disclosure-agreement-schema-context.jsonld) + - Data Agreement (DA) +- Consents - Records the granular “consent” for personal data described in the data agreement. + +Each artefact must conform to a JSONLD context. For e.g. a Data Disclosure Agreement (DDA) must conform to JSONLD context defined [here](https://github.com/decentralised-dataexchange/data-exchange-agreements/blob/main/interface-specs/data-disclosure-agreement-schema/data-disclosure-agreement-schema-context.jsonld). A genesis artefact must be created and did:mydata identifier is generated by embedding artefact as payload in the DID document. Each artefact will have cryptographic material associated to it. Cryptographic material represented as decentralised identifiers will be listed in the controllers property of the DID document. Controllers can make changes to the underlying artefact. Artefact should contains proofs that CONFORMS to W3C [Data Integrity Model](https://w3c.github.io/vc-data-integrity/) and number of proofs should match the number of controllers. Creation of did:mydata identifiers occurs as result of [DDA protocols](https://dda.igrant.io/protocol/#smart-contracts) (To be elaborated further). + +~~Creation of the identifier assumes that through an out-of-band/didcomm interaction actors involved in the agreement has arrived at terms, i.e both (if 2 actors are involved) parties holds an agreement document with a proof chain ([Data Integrity Model](https://w3c.github.io/vc-data-integrity/)) in it~~. + +***~~The approach propose the creation of the did:mydata identifier after the negotiation, that doesn’t make sense considering, the document will have constant updates. Therefore the controller can create the Genesis Agreement and generate the identifier out of it. Subject can then propose changes.~~*** -Specification also assumes the parties involved in the agreement has created the cryptographic material to sign the agreement. The cryptographic material represented as decentralised identifiers based on the DID method chosen by the party. These DIDs then act as the controller for the DID document associated with did:mydata identifier. The DID document associated with the did:mydata identifier contains the agreement as payload. An example DID document is given below. +~~The agreement document must conform to JSONLD context matching the agreement type, for e.g.~~ + +~~Specification also assumes the parties involved in the agreement has created the cryptographic material to sign the agreement. The cryptographic material represented as decentralised identifiers based on the DID method chosen by the party. These DIDs then act as the controller for the DID document associated with did:mydata identifier. The DID document associated with the did:mydata identifier contains the agreement as payload.~~ + +An example DID document is given below. @@ -89,7 +106,7 @@ Specification also assumes the parties involved in the agreement has created the } ``` -In the above document, controller property contains 2 did:key identifiers. These identifiers belong to the parties involved in the agreement. The payload property is an unregistered DID property extension used to contain the base64 encoded JCS canonicalised agreement document. An example payload base64 decoded in given below. +In the above document, controller property contains 2 did:key identifiers. These identifiers belong to the parties involved in the agreement. The payload property is an *unregistered DID property extension* used to contain the base64 encoded JCS canonicalised agreement document. An example payload base64 decoded in given below. ```json { @@ -168,7 +185,7 @@ In the above document, controller property contains 2 did:key identifiers. These The controllers should match the `verificationMethod` specified in the `proofChain`. -#### The did:mydata identifier creation algorithm +#### did:mydata identifier creation algorithm Following algorithm is used to create the did:mydata identifier, if an agreement document is available. @@ -201,15 +218,170 @@ If the did:mydata identifier is anchored to a blockchain, a did with hashlink sh ### Read -To be elaborated. +To resolve a did:mydata identifier, an identifier with following DID parameters must be available: + +- `registryUrl` : Encoded URL for a remote DID registry. *(mandatory)* +- `versionId`: Identifies a specific version of a DID document to be resolved (the version ID is the merkle root of the specific artefact). If present, the associated value MUST be an ASCII string. *(optional, if not present, will return the latest version)* +- `token`: JWT token signed by the controller. This acts as the proof of possession of the private key associated with controller decentralised identifier ***(optional, if not present, then confidential payload won’t be present in the diddoc)*** +- `blink`: Blockchain link conforming to [W3C Blockchain Links](https://w3c-ccg.github.io/blockchain-links/) *(optional, if present, the did registry would check artefact merkle root in transaction, to be elaborated further)* + +An example identifier with parameters is given below: + +```bash +did:mydata:zJ53MfXX934iYwx6hdQRKonWkVj22t9NczBmwe7To2Yh2sTnS7W32ocTYgvwtQRB3K?registryUrl=https%3A%2F%2Fagent.igrant.io&token= +``` + +To resolve a DID and fetch the associated DID document from the DID registry, a DIDComm plaintext message of type - [https://didcomm.org/mydata-did/2.0/read-did](https://didcomm.org/mydata-did/2.0/read-did) must be constructed. An example is given below: + +```json +{ + "@id": "3e914e45-28f0-4009-b9c2-e2df2ba165b8", + "@type": "https://didcomm.org/mydata-did/2.0/read-did", + "to": "", + "created_time": "1622649143", + "did": "did:mydata:zJ53MfXX934iYwx6hdQRKonWkVj22t9NczBmwe7To2Yh2sTnS7W32ocTYgvwtQRB3K", + "token": "", + "~transport": { + "return_route": "all" + } +} +``` + +The `did` attribute in the message body represents the DID that will be resolved. + +The above example requests DID registry service to resolve `did:mydata:zJ53MfXX934iYwx6hdQRKonWkVj22t9NczBmwe7To2Yh2sTnS7W32ocTYgvwtQRB3K` + +Notice the message json+ld doesn’t contain a **from** key, since the read operation can be performed without owning a DID. The packing algorithm used for constructing the DIDComm encryption envelope should be anoncrypt. + +DID registry will check the merkle root in the deactivation tree and make sure it is not deactivated. DID registry service will respond to the above DIDComm message with an encryption envelope (JWE) which when unpacked will contain a DIDComm plaintext message of type - [https://didcomm.org/mydata-did/2.0/read-did-response](https://didcomm.org/mydata-did/2.0/read-did-response). An example is given below: + +```json +{ + "@type": "https://didcomm.org/mydata-did/2.0/read-did-response", + "@id": "4f4fbc78-be45-4029-ad18-a808c3a36ac2", + "from": "", + "created_time": "1622649143", + "~thread": { + "thid": "3e914e45-28f0-4009-b9c2-e2df2ba165b8" + }, + "body": { + "diddoc": {}, + "merkleRoot": "", + "merkleInclusionProof": [], + "blink": "", + "created": "", + "updated": "", + "deactivated": "", + "nextUpdate": "", + "versionId": "", + "nextVersionId": "" + } +} + +``` + +If a problem arises while handling the `read-did` message, DID registry service will respond with a problem report message. An example is given below: + +```json +{ + "@type": "https://didcomm.org/mydata-did/2.0/problem-report", + "@id": "2c8579d3-ecdd-4427-9e2f-7f911917de6c", + "~thread": { + "thid": "3e914e45-28f0-4009-b9c2-e2df2ba165b8" + }, + "description": "did:mydata identifier not found" +} +``` ### Update -To be elaborated. +To update a DID document associated with a did:mydata identifier, a DIDComm plaintext message of type - [https://didcomm.org/mydata-did/2.0/update-did](https://didcomm.org/mydata-did/2.0/update-did) must be constructed by the controller. An example is given below: + +```json +{ + "@id": "3e914e45-28f0-4009-b9c2-e2df2ba165b8", + "@type": "https://didcomm.org/mydata-did/2.0/update-did", + "to": "", + "created_time": "1622649143", + "did": "did:mydata:zJ53MfXX934iYwx6hdQRKonWkVj22t9NczBmwe7To2Yh2sTnS7W32ocTYgvwtQRB3K", + "token": "", + "payload": "", + "~transport": { + "return_route": "all" + } +} +``` + +DID registry on receiving the message validates the payload against the JSONLD context of the artefact type. Once the data is validated against the schema, the data integrity is verified using [W3C DATA INTEGRITY MODEL](https://w3c.github.io/vc-data-integrity/). The new payload, is then added to the merkle tree and a merkle inclusion proof is provided in the response. + +DID registry service will respond to the above DIDComm message with an encryption envelope (JWE) which when unpacked will contain a DIDComm plaintext message of type - [https://didcomm.org/mydata-did/2.0/update-did-response](https://didcomm.org/mydata-did/2.0/update-did-response). An example is given below: + +```json +{ + "@type": "https://didcomm.org/mydata-did/2.0/update-did-response", + "@id": "4f4fbc78-be45-4029-ad18-a808c3a36ac2", + "from": "", + "created_time": "1622649143", + "~thread": { + "thid": "3e914e45-28f0-4009-b9c2-e2df2ba165b8" + }, + "body": { + "diddoc": {}, + "merkleRoot": "", + "merkleInclusionProof": [], + "blink": "", + "created": "", + "updated": "", + "deactivated": "", + "nextUpdate": "", + "versionId": "", + "nextVersionId": "" + } +} + +``` + +If a problem arises while handling the `update-did` message, DID registry service will respond with a problem report message. ### Deactivate -To be elaborated. +To deactivate a did:mydata identifier, a DIDComm plaintext message of type - [https://didcomm.org/mydata-did/2.0/deactivate-did](https://didcomm.org/mydata-did/2.0/deactivate-did) must be constructed by the controller. An example is given below: + +```json +{ + "@id": "3e914e45-28f0-4009-b9c2-e2df2ba165b8", + "@type": "https://didcomm.org/mydata-did/2.0/deactivate-did", + "to": "", + "created_time": "1622649143", + "did": "did:mydata:zJ53MfXX934iYwx6hdQRKonWkVj22t9NczBmwe7To2Yh2sTnS7W32ocTYgvwtQRB3K", + "token": "", + "~transport": { + "return_route": "all" + } +} +``` + +DID registry on receiving the message validates the token and proceed to deactivate the did:mydata identifier. The did:mydata is deactivated by including in the revocation tree. + +DID registry service will respond to the above DIDComm message with an encryption envelope (JWE) which when unpacked will contain a DIDComm plaintext message of type - [https://didcomm.org/mydata-did/2.0/deactivate-did-response](https://didcomm.org/mydata-did/2.0/deactivate-did-response). An example is given below: + +```json +{ + "@type": "https://didcomm.org/mydata-did/2.0/deactivate-did-response", + "@id": "4f4fbc78-be45-4029-ad18-a808c3a36ac2", + "from": "", + "created_time": "1622649143", + "~thread": { + "thid": "3e914e45-28f0-4009-b9c2-e2df2ba165b8" + }, + "body": { + "deactivated": "" + } +} + +``` + +If a problem arises while handling the `deactivate-did` message, DID registry service will respond with a problem report message. ## Resources