Data Agreement DID Method Specification

Abstract

A Data Agreement (DA) exists between organisations and individuals in the use of personal data. This agreement can have any legal basis that is outlined according to any data protection regulation, such as the GDPR. This proposal envisions an associated Data Agreement for any personal data usage.

Status of This Document

Version 1.1

Authors

Mr. George Padayatti (iGrant.io, Sweden)
Mr. Lal Chandran (iGrant.io, Sweden)

Contributors and Reviewers

Mr. Mr. Jan Lindquist (Linaltec, Sweden)
Ms. Lotta Lundin (iGrant.io, Sweden)

1. Introduction

This document proposes a new DID method that allows different objects in iGrant.io automated data agreements (ADA) specifications to be treated as a valid identifier.

Some of the functionalities available to actors (aka the DID subjects) are:

Sign Data Agreement(s) including that of data exchange
Authenticate and verify proof chain in Data Agreement VC
Associate data exchange transactions to Data Agreement(s)

The Data Agreement could be the result of a Data Protection Impact Assessments (DPIA) or similar activity. The use of a resolvable unique identifier ensures traceability and auditability for any Data Agreement that is signed between an individual and an organisation. A signed Data Agreement can be verified by an independent auditor or any one else.

This document specifies methods for creating and editing Decentralized IDs (DIDs) suitable for use with Data Agreements. It conforms to the requirements specified in the DID specification currently published by the W3C Credentials Community Group.

For more details on Data Agreements, refer Data Agreement Specification

2. The `did:mydata` Format

The format for the did:mydata method conforms to the DID core specification [1] as outlined by W3C. It consists of the did:mydata prefix, followed by did-type-integer value, followed by the mb-value value.

The mb-value is a Multibase [2] base58-btc encoded value of the Multicodec [3] identifier for Ed25519 public key concatenated with raw Ed25519 public key bytes. The iGrant.io DID scheme is defined by the following ABNF:

mydata-did = "did:mydata" (":" did-type-integer) ":" mb-value

did-type-integer = 0 / 1 / 2 / 3 / 4
 
mb-value = z[a-km-zA-HJ-NP-Z1-9]+

did-type-integer is optional and it represents the type of the DID subject identified by the DID. Following are the available types:

0 - represents a Data Source, an organisation collecting personal data
1 - represents a Data Subject or Individual
2 - represents a Data Using Service, an organisation processing personal data from one or more data sources to deliver a service
3 - represents an Assessor who reviews the practices of an organisation, conducts a DPIA and drafts data agreements and intercompany agreements for third parties
4 - represents an Auditor who may be called in to review the data agreements and ensure they are in place in case of data breaches or regular inspection.

Example, a valid MyData/iGrant.io DID could be:

did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E

The above DID identifies a Data Source (0).

3. DID document

MyData/iGrant.io DID document conforms to DID core specification [1] and supports all core properties.

Example of MyData/iGrant.io DID document:

{
  "@context": "https://w3id.org/did/v1",
  "id": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E",
  "verificationMethod": [
    {
      "id": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E#1",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E",
      "publicKeyBase58": "z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E"
    }
  ],
  "authentication": [
    {
      "type": "Ed25519VerificationKey2018",
      "publicKey": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E#1"
    }
  ],
  "service": [
    {
      "id": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E;didcomm",
      "type": "DIDComm",
      "priority": 0,
      "recipientKeys": [
        "z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E"
      ],
      "serviceEndpoint": "https://ada-agent.example.com/service-x"
    }
  ]
}

The property service is optional. The service defined with type DIDComm describes an agent that supports DIDComm capabilities which may or may not be iGrant.io specific DIDComm protocols. For e.g. A Data Subject could trigger a revoke-notification DIDComm message to inform a Data Using Service’s service endpoint that a Data Agreement is added to the revocation list.

4. DID Operation Definitions

An ADA 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/1.0) is specified below for performing CRUD operations. The ADA 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 its extensions.

4.1 Create (Register)

Creation of the DID follows the sequence below:

The (Public key, Private key) pair is created based on Ed25519Signature2018 suite which is specified in Linked Data Cryptographic Suite Registry [5]. Ed25519 algorithm is available in common crypto libraries, for example NACL.
Multicodec [3] prefix for Ed25519 public key is concatenated to raw public key bytes and encoded using base58-btc encoding to obtain the Multibase [2] value (mb-value).
Create the DID document based on the format specified in Section 3 (DID document).
Construct a DIDComm plaintext message conforming to DIDComm message specification [4] with type - https://didcomm.org/mydata-did/1.0/create-did as given in the example is given below:

{
  "@id": "6a956d0d-b117-41d5-841e-7190ee0e5d5f",
  "@type": "https://didcomm.org/mydata-did/1.0/create-did",
  "from": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E",
  "to" : "did:mydata:z6MkpFAimMHJSwxWcm9rmt7XHjwkdLFNeZ5eRhxr6b4xK8rw",
  "created_time": "1622649143",
  "body": {
    "did": {
      "@context": "https://w3id.org/did/v1",
      ....
      Rest of the DID document
      ....
    }
  },
  "~transport": {
    "return_route": "all"
  }
}

id is a unique value to the sender which indicates the message ID.
type indicates the message type. Message type decides how the message contents must be processed.
from is a valid DID which identifies the sender. This can be the same as the DID that is getting created.
to is a valid DID which identifies the recipient. It is the value of ADA service’s DID. This is obtained from the DID document available at the root endpoint of ADA service.
created_time indicates message created time. This is represented in UTC epoch seconds.
body contains the actual message body. In this case it contains the DID document that is getting created and stored in the DID registry.
~transport decorator is optional. This decorator conforms to ARIES RFC 0092 [6]. If it’s specified and the value of return_route is all, then it means ADA service must respond to the respective DIDComm message using the same HTTP connection. This is useful when the client sending a DIDComm message doesn’t have any inbound route available.

A DIDComm encryption envelope is constructed according to the steps documented in ARIES RFC 0019 [7] to wrap the above plaintext message. Encryption envelope uses a standard format built on JSON Web Encryption (JWE) [8]. The public key used is fetched from the DID document available at the well-known DID configuration endpoint of the ADA service. Mode of encryption when creating JWE is anoncrypt.
The encryption envelope is transmitted to ADA service by performing HTTP POST operation. For ADA service to process the incoming message, the content-type HTTP header provided is application/didcomm-encrypted+json.
The ADA 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/1.0/create-did-response. An example is given below:

{
  "@type": "https://didcomm.org/mydata-did/1.0/create-did-response",
  "@id": "4f4fbc78-be45-4029-ad18-a808c3a36ac2",
  "from": "did:mydata:z6MkpFAimMHJSwxWcm9rmt7XHjwkdLFNeZ5eRhxr6b4xK8rw",
  "to": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E",
  "created_time": "1622649143",
  "~thread": {
    "thid": "6a956d0d-b117-41d5-841e-7190ee0e5d5f"
  },
  "body": {
    "did": {
      "@context": "https://w3id.org/did/v1",
      ....
      Rest of the DID document
      ....
    },
    "version": "1.0"
  }
}

If a problem arises while handling the create-did message, ADA service will respond with a problem report message that conforms to ARIES RFC 0035 [9]. An example is given below:

{
  "@type": "https://didcomm.org/mydata-did/1.0/problem-report",
  "@id": "2c8579d3-ecdd-4427-9e2f-7f911917de6c",
  "~thread": {
    "thid": "6a956d0d-b117-41d5-841e-7190ee0e5d5f"
  },
  "description": "Chosen DID exists, try again with a different one",
  "description~l10n": {
    "code": "did-exists"
  },
  "problem_items": [
    {
      "did": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E"
    }
  ]
}

4.2 Read (Resolve)

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/1.0/read-did must be constructed. An example is given below:

{
  "@id": "3e914e45-28f0-4009-b9c2-e2df2ba165b8",
  "@type": "https://didcomm.org/mydata-did/1.0/read-did",
  "to" : "did:mydata:z6MkpFAimMHJSwxWcm9rmt7XHjwkdLFNeZ5eRhxr6b4xK8rw",
  "created_time": "1622649143",
  "body": {
    "did": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E"
  },
  "~transport": {
    "return_route": "all"
  }
}

The did attribute in the message body represents the DID that will be resolved.

The above example requests ADA service to resolve did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E 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.

The ADA 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/1.0/read-did-response. An example is given below:

{
  "@type": "https://didcomm.org/mydata-did/1.0/read-did-response",
  "@id": "4f4fbc78-be45-4029-ad18-a808c3a36ac2",
  "from": "did:mydata:z6MkpFAimMHJSwxWcm9rmt7XHjwkdLFNeZ5eRhxr6b4xK8rw",
  "created_time": "1622649143",
  "~thread": {
    "thid": "3e914e45-28f0-4009-b9c2-e2df2ba165b8"
  },
  "body": {
    "did": {
      "@context": "https://w3id.org/did/v1",
      ....
      Rest of the DID document
      ....
    },
    "version": "1.0"
  }
}

If a problem arises while handling the read-did message, ADA service will respond with a problem report message that conforms to ARIES RFC 0035 [9]. An example is given below:

{
  "@type": "https://didcomm.org/mydata-did/1.0/problem-report",
  "@id": "2c8579d3-ecdd-4427-9e2f-7f911917de6c",
  "~thread": {
    "thid": "3e914e45-28f0-4009-b9c2-e2df2ba165b8"
  },
  "description": "DID not found",
  "description~l10n": {
    "code": "did-not-found"
  },
  "problem_items": [
    {
      "did": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E"
    }
  ]
}

4.3 Update

In the current version of this specification, Update operation on DID documents is not permitted.

4.4 Delete

In the current version of this specification, delete is relevant only when triggered by a DID controller to renew the existing DID to a new one. In this case, the old DID is marked as revoked. It could then be replaced with the newly created DID. To delete a DID, a DIDComm plaintext message of type - https://didcomm.org/mydata-did/1.0/delete-did must be constructed. An example is given below:

{
  "@id": "6a956d0d-b117-41d5-841e-7190ee0e5d5f",
  "@type": "https://didcomm.org/mydata-did/1.0/delete-did",
  "from": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E",
  "to" : "did:mydata:z6MkpFAimMHJSwxWcm9rmt7XHjwkdLFNeZ5eRhxr6b4xK8rw",
  "created_time": "1622649143",
  "body": {
    "did": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E"
  },
  "~transport": {
    "return_route": "all"
  }
}

The did attribute in the message body represents the DID that will be marked as revoked.

The packing algorithm used for constructing the DIDComm encryption envelope should be authcrypt.

The ADA 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/1.0/delete-did-response. An example is given below:

{
  "@type": "https://didcomm.org/mydata-did/1.0/delete-did-response",
  "@id": "4f4fbc78-be45-4029-ad18-a808c3a36ac2",
  "from": "did:mydata:z6MkpFAimMHJSwxWcm9rmt7XHjwkdLFNeZ5eRhxr6b4xK8rw",
  "to": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E",
  "created_time": "1622649143",
  "~thread": {
    "thid": "6a956d0d-b117-41d5-841e-7190ee0e5d5f"
  },
  "body": {
    "status": "revoked"
  }
}

If a problem arises while handling the delete-did message, ADA service will respond with a problem report message that conforms to ARIES RFC 0035 [9]. An example is given below:

{
  "@type": "https://didcomm.org/mydata-did/1.0/problem-report",
  "@id": "2c8579d3-ecdd-4427-9e2f-7f911917de6c",
  "~thread": {
    "thid": "6a956d0d-b117-41d5-841e-7190ee0e5d5f"
  },
"from": "did:mydata:z6MkpFAimMHJSwxWcm9rmt7XHjwkdLFNeZ5eRhxr6b4xK8rw",
  "to": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E",
  "description": "DID not found",
  "description~l10n": {
    "code": "did-not-found"
  },
  "problem_items": [
    {
      "did": "did:mydata:0:z6MkfiSdYhnLnS6jfwSf2yS2CiwwjZGmFUFL5QbyL2Xu8z2E"
    }
  ]
}

5. Security Considerations

Conforms to security considerations as documented in DID core specification [1].

Following security considerations are taken up:

Stolen DID keys
Stolen private keys
Loss of device in which the DID agent is running.

6. Privacy Considerations

DID documents in did:mydata does not include any PII, as required by the DID core specification [1], and recommended for privacy reasons.

7. Reference Implementation

Work in progress as part of NGI-Trust eSSIF-Lab ADA Project.

8. Resources

DID core specification: https://www.w3.org/TR/did-core/
IETF Multibase Data Format specification: https://tools.ietf.org/html/draft-multiformats-multibase
Multicodec - Compact self-describing codecs: https://github.com/multiformats/multicodec
DIDComm message specification: https://identity.foundation/didcomm-messaging/spec/
Linked Data Cryptographic Suit Registry: https://w3c-ccg.github.io/ld-cryptosuite-registry/
Aries RFC 0092 - Transports Return Route: https://github.com/hyperledger/aries-rfcs/tree/master/features/0092-transport-return-route
Aries RFC 0019: Encryption Envelope: https://github.com/hyperledger/aries-rfcs/tree/master/features/0019-encryption-envelope
IETF RFC 7516 - JSON Web Encryption: https://datatracker.ietf.org/doc/html/rfc7516
Aries RFC 0035 - Report Problem Protocol 1.0: https://github.com/hyperledger/aries-rfcs/tree/master/features/0035-report-problem
Data Agreement Specification, ADA Project, eSSIF-Lab Infrastructure

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

did-spec.md

did-spec.md

Data Agreement DID Method Specification

Abstract

Status of This Document

Authors

Contributors and Reviewers

Table of Contents

1. Introduction

2. The `did:mydata` Format

3. DID document

4. DID Operation Definitions

4.1 Create (Register)

4.2 Read (Resolve)

4.3 Update

4.4 Delete

5. Security Considerations

6. Privacy Considerations

7. Reference Implementation

8. Resources

Files

did-spec.md

Latest commit

History

did-spec.md

File metadata and controls

Data Agreement DID Method Specification

Abstract

Status of This Document

Authors

Contributors and Reviewers

Table of Contents

1. Introduction

2. The did:mydata Format

3. DID document

4. DID Operation Definitions

4.1 Create (Register)

4.2 Read (Resolve)

4.3 Update

4.4 Delete

5. Security Considerations

6. Privacy Considerations

7. Reference Implementation

8. Resources

2. The `did:mydata` Format