IPID DID Method

1. Introduction

The Interplanetary Identifiers DID method (did:ipid:) supports DIDs on the public and private Interplanetary File System (IPFS) networks. IPFS is the distributed content addressable permanent web. More specifically, the IPID DID method utilizes the Interplanetary Linked Data (IPLD) suite of tools. The IPID DID method has minimal design goals: a DID trust anchor based on the IPFS and Libp2p protocol. In and of itself, this is not a blockchain solution. However, blockchains and other distributed ledger technologies could be utilized to anchor the artifacts of this DID methods for further enhanced security.

2. Terminology

block: A data structure that contains one or more ledger events.

blockchain: A ledger containing a series of blocks where the ordering of the blocks can be mathematically proven to be correct.

consensus algorithm: An algorithm that enables multiple nodes in a network to make a decision in a deterministic fashion.

Content Indentifier (CID): A Content Identifer (CID) is a cyptographic identifer that self describes the content-hash itself. The CID includes, a Multibase prefix, the CID version and the multicodec identifer which indicatees the format of the target content.

cryptographic ledger: A method of recording changes in a state machine where the accuracy of the ledger can be mathematically proven to be correct.

micro-ledger: An append only tamper-resistent ledger that shares the hashed linked list characteristics of fully deployed distributed ledger technologies, but without the full overhead of consensus algorithms.

DID: a distributed identitfier.

decentralized system: A system in which lower level components operate on local information to accomplish global goals. For example, an ant colony is a decentralized system as there is no central control determining when food must be collected or how new tunnels should be excavated.

decentralized ledger: A cryptographic ledger that uses a consensus algorithm that enables a network of ledger nodes to come to consensus in a decentralized yet deterministic fashion.

3. Basic Concepts

3.1. Interplanetary Linked Data (IPLD)

IPLD uses an abstract model for linking data via cryptographic hashes, which enables the ability to traverse this link to the referenced data via path "/" notation. This path notation has its roots in the Linux Filesystem Hierarchy Standard. A link in IPLD is represented in JSON as a “link object” and uses the path syntax "/" as the key to the object that is followed by the CID (see below) of the link.

IPLD relies on Content Identifiers (CIDs) for content addressing. CIDs are a self-describing, flexible, and interoperable way of expressing cryptographic hashes. It uses several multiformats to achieve flexible self-description, namely multihash for hashes, multicodec for data content types, and multibase to represent the base encoding of the CID itself. This interoperability makes IPLD a valuable structure for the DID document that can be used across a variety of DID methods or distributed ledgers and ensures cryptographic validity of the DID document.

JSON-LD is a syntax to serialize Linked Data in JSON and provide semantics without the overhead of a large rdf model [2]. Since both IPLD and JSON-LD are 100% compatible with JSON, the large number of JSON parsers and libraries are already available.

However, when using JSON-LD in a browser, it is impossible to discover the Base IRI after an http redirect (see #316), and the content of the @context can potentially change over time [3]. Finally, since a URI depends upon the security of DNS, DNS spoofing/DNS poisoning could offer a simple attack vector. Essentially, without much effort, an attacker can adjust the cache of a DNS server and begin pointing traffic from ‘schema.org’ (or any other desired host) to anywhere else on the internet or local LAN. Given the critical nature of the JSON-LD @context resource, the attacker can make a fraudulent signature pass as being valid.

Using IPLD, we can use the entire JSON data model and we can layer any JSON-LD on top of IPLD [4]. This will enable cryptographic guarantees to the authenticity of the JSON-LD schema and mitigate such an attack.

One additional point to emphasize is that the content loaded into IPLD is serialized using Concise Binary Object Representation (CBOR), allowing for deterministic representation and retrieval.

Content stored on IPLD is cryptographically retrievable regardless of the domain. The content can be retrieved via numerous http gateways including: ipfs.io, ipfs.infura.io, and cloudflare-ipfs.com, as well as a locally hosted gateway or via the command-line with the ipfs application.

EXAMPLE of linked data in IPLD:

{ "@context" : 
    { "/" : "zdpuAmoZixxJjvosviGeYcqduzDhSwGV2bL6ZTTXo1hbEJHfq" }
}

IPID uses `/` to reference links to other content on IPLD ipid-method-spec issue # 1

IPID does not conform to JSON-LD @context syntax ipid-method-spec issue # 2

3.2. Interplanetary Naming System (IPNS)

Inter-Planetary Name System (IPNS) is a system for creating and updating mutable links to IPFS content. Since objects in IPFS are content-addressed, their address changes every time their content does. That’s useful for a variety of things, but it makes it hard to get the latest version of something. A name in IPNS is the hash of a public key. It is associated with a record containing information about the hash it links to that and that record is cryptographically signed by the corresponding private key. New records can be signed and published at any time. In the IPID DID method, the CID is cyptographically associated with the IPNS public key by publishing a record to the distributed hash table.

Example of cryptographically associating a CID with default IPNS public key using the ipfs command line application:

> ipfs name publish /ipld/zdpuAyyen4DeAzm2pvc3h9TP3qkCnYUYN1sa9kSu9Tcub1XoY

Publishing to IPNS can be slow ipid-method-spec issue # 3

3.3. Linking to previous DID documents in IPID

In addition to linking to the @context attibute definitions for sematic interoperability, the syntax for representing linked data can expanded and used for pointing to the previous version the DID document. This approach is often called a micro-ledger.

3.4. Authentication

Authentication is the process the ledger uses to determine if an entity is associated with a DID.

EXAMPLE: Expressing authentication credentials

{
  "@context": {
    "/": "zdpuAmoZixxJjvosviGeYcqduzDhSwGV2bL6ZTTXo1hbEJHfq"
  },
  "authentication": {
    "publicKey": [
      "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew"
    ],
    "type": "EdDsaSASignatureAuthentication2018"
  }
}

4. Operations

4.1. Creating a DID

At initialization of the DID document in the IPID DID method, the public/private keys pairs associated with the DID method specific identifier may or may not also have been generated. Additionally, the public/private key pair may or may not be the same as the master publishing key associated with the DID. The DID method specific identifier for the IPID DID method is the self-describing cryptographic multihash of the public key of an IPFS node and may be different from the public/private key pair represented in the DID document. At present, RSA and Ed25519 elliptic curves are supported and there are plans to support secp256k1.

Since the DID document needs to contain information about where to discover the latest version of the DID document (which is a requirement of DID resolution), in IPID the id field corresponds to the DID method specific identifier (i.e. did:ipid: ).

Example 1 shows the beginning of the IPLD data before publishing it IPNS and thereby associating it with a DID method specific identifer.

EXAMPLE 1: Initial structure of DID docuement before associating with IPID method specific identifier

{
  "@context": {
    "/": "zdpuAmoZixxJjvosviGeYcqduzDhSwGV2bL6ZTTXo1hbEJHfq"
  },
  "created": "2018-12-01T03:00:00Z",
  "publicKey": [
    {
      "curve": "ed25519",
      "expires": "2019-12-01T03:00:00Z",
      "publicKeyBase64": "qmz7tpLNKKKdl7cD7PbejDiBVp7ONpmZbfmc7cEK9mg=",
      "type": "EdDsaPublicKey"
    }
  ],
  "updated": "2018-12-01T03:00:01Z"
}

The resulting CID of this content is zdpuAqiExr6k4AbWF6BuGkgUbVMZ7jbJyNvRz9z9yyRBxosPi and will be used in subsequent updates to the DID document below.

EXAMPLE 2: Intermediate structure of IPID DID docuement after association with IPID method specific identifier.

{
  "@context": {
    "/": "zdpuAmoZixxJjvosviGeYcqduzDhSwGV2bL6ZTTXo1hbEJHfq"
  },
  "authentication": {
    "publicKey": [
      "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew"
    ],
    "type": "EdDsaSASignatureAuthentication2018"
  },
  "created": "2018-12-01T03:00:00Z",
  "id": "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew",
  "previous": {
    "/": "zdpuAqiExr6k4AbWF6BuGkgUbVMZ7jbJyNvRz9z9yyRBxosPi"
  },
  "proof": {
    "/": "z43AaGF42R2DXsU65bNnHRCypLPr9sg6D7CUws5raiqATVaB1jj"
  },
  "publicKey": [
    {
      "curve": "ed25519",
      "expires": "2019-12-01T03:00:00Z",
      "publicKeyBase64": "qmz7tpLNKKKdl7cD7PbejDiBVp7ONpmZbfmc7cEK9mg=",
      "type": "EdDsaPublicKey"
    }
  ],
  "updated": "2018-12-01T03:00:02Z"
}

Example 2 shows the addition of the id field with the previous field linking to the hash of Example 1 as defined in the previous field as a CID embedded link.

EXAMPLE 3: PLD DID document updated with the addition of the signature field

{
  "@context": {
    "/": "zdpuAmoZixxJjvosviGeYcqduzDhSwGV2bL6ZTTXo1hbEJHfq"
  },
  "authentication": {
    "type": "EdDsaSASignatureAuthentication2018",
    "publicKey": [
      "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew"
    ]
  },
  "created": "2018-12-01T03:00:00Z",
  "id": "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew",
  "previous": {
    "/": "zdpuAosm9NYNW5kG2h3SBoCZz5DYqyTgf6qopkxpih5cFhqmU"
  },
  "proof": {
    "/": "z43AaGF42R2DXsU65bNnHRCypLPr9sg6D7CUws5raiqATVaB1jj"
  },
  "publicKey": [
    {
      "curve": "ed25519",
      "expires": "2019-12-01T03:00:00Z",
      "publicKeyBase64": "qmz7tpLNKKKdl7cD7PbejDiBVp7ONpmZbfmc7cEK9mg=",
      "type": "EdDsaPublicKey"
    }
  ],
  "signature": {
    "created": "2018-12-01T03:00:02Z",
    "creator": "zdpuAohuM1RWMpzwQgWz5jXFCdPtz1rhD82fuZBauUDuRzknt/publicKey/0",
    "message": {
      "/": "zdpuAohuM1RWMpzwQgWz5jXFCdPtz1rhD82fuZBauUDuRzknt"
    },
    "signatureValue": "o9r6LxgoGN8FoaeeUA6EdDcv12GvDzFEmCgjWzvpur2YSQyA8W2r0SSWUK+nH5tMqzaFLun6wwZ1Eot37amGDg==",
    "type": "ed25519Signature2018"
  },
  "updated": "2018-12-01T03:00:00Z"
}

Example 3 shows the final DID document with CID of zdpuB1oR3vjYmkDc9ALfY7o6hSt1Hrg2ApXaYAFyiAW5E4NJP after it is associated with the IPID DID method specific identifier and signed with the identicated private key. This document is then published to the IPNS namespace. Notice the signature includes a CID as a link from the message that was signed. In this case the previous version (intermediate) document (above). The creator of the signature can be reteived with the following command:

`Proof` in the DID specification illustrates a Linked-Data Signature where here the `Signature` attribute was used. ipid-method-spec issue # 4

EXAMPLE 4: Retrieval of public key of creator of signature from above

> ipfs dag get zdpuAohuM1RWMpzwQgWz5jXFCdPtz1rhD82fuZBauUDuRzknt/publicKey/0

result:

{"curve":"ed25519","expires":"2019-12-01T03:00:00Z","publicKeyBase64":"qmz7tpLNKKKdl7cD7PbejDiBVp7ONpmZbfmc7cEK9mg=","type":"EdDsaPublicKey"}

4.2. Reading a DID

EXAMPLE 4: Retrieval of IPID DID document using an IPFS gateway

> CID=`curl -s "https://ipfs.io/api/v0/name/resolve?arg=12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew"` | jq -r .Path  
> curl -s "https://ipfs.io/api/v0/dag/get?arg=${CID}"

4.3. Updating a DID

EXAMPLE 5: Updating DID document followed by re-publishing

{
  "@context": {
    "/": "zdpuAmoZixxJjvosviGeYcqduzDhSwGV2bL6ZTTXo1hbEJHfq"
  },
  "authentication": {
    "type": "EdDsaSASignatureAuthentication2018",
    "publicKey": [
      "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew"
    ]
  },
  "created": "2018-12-01T03:00:00Z",
  "id": "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew",
  "previous": {
    "/": "zdpuB1oR3vjYmkDc9ALfY7o6hSt1Hrg2ApXaYAFyiAW5E4NJP"
  },
  "proof": {
    "/": "z43AaGF42R2DXsU65bNnHRCypLPr9sg6D7CUws5raiqATVaB1jj"
  },
  "publicKey": [
    {
      "curve": "ed25519",
      "publicKeyBase64": "qmz7tpLNKKKdl7cD7PbejDiBVp7ONpmZbfmc7cEK9mg=",
      "type": "EdDsaPublicKey",
      "status": "revoked"
    },
    {
      "curve": "ed25519",
      "expires": "2021-07-08T16:02:20Z",
      "publicKeyBase64": "jGp4OT1GktrZMdrkOM+zj8iE1IqCiqg2iH+rUZ93jhE=",
      "type": "EdDsaPublicKey"
    }
  ],
  "signature": {
    "created": "2018-12-01T03:00:04Z",
    "creator": "zdpuAt99xoa8i2BrcjwpY2H6ksXeaE28upionw2VuxRamBs6H/publicKey/1",
    "message": {
      "/": "zdpuAyvreXzQHqwv3rL8MaVPjNJjpLLa5Du3HcbpQL41XS35G"
    },
    "signatureValue": "WDA3Dx7c+UWR37oglhkLNwxAbxXM4YbT7TpgmaCQ/rSqbtXgM3EpQ4mpkPXT5OBLH6bDai12Ank8SUHW47JxCQ==",
    "type": "ed25519Signature2018"
  },
  "updated": "2018-12-01T03:00:04Z"
}

In example 5 the IPID did document is updated with the public key in position zero has been revoked. The resulting CID of this docuement is: zdpuAtrP6ZSDZj6izYQEbuUjuDRGHSa5L59BZDa1deRwAAZRQ and the new document is updated with a pointer to the previous document as zdpuB1oR3vjYmkDc9ALfY7o6hSt1Hrg2ApXaYAFyiAW5E4NJP and then published to IPNS

Revoking a particular key requires storage of it's position ipid-method-spec issue # 4

4.4. Deleting a DID

In general deleting a DID document is frowned upon, however should this be required the following code can perform this function:

EXAMPLE 5: Deleting the IPID DID

> ipfs name publish zdpuAyTBnYSugBZhqJuLsNpzjmAjSmxDqBbtAqXMtsvxiN2v3

This command effectively publishes the literal '{}' as a value to the IPNS store.

5. Versioning

Version of this Specification

[Define how this spec will be versioned. This SHOULD be by using the bikeshed versioning mechanism.]

Version of the JSON-LD Context

[Define how your JSON-LD context will be versioned. This MUST use the mechanism defined in the DID spec.]

6. Security Considerations

Requirements from Method Spec Template definition:

At least the following forms of attack MUST be considered:
eavesdropping, replay, message insertion, deletion, modification,
impersonation, and man-in-the-middle.

Potential denial of service attacks MUST be identified as well.

If the protocol incorporates cryptographic protection mechanisms, it
should be clearly indicated which portions of the data are protected and
what the protections are (i.e., integrity only, confidentiality, and/or
endpoint authentication, etc.).

Some indication should also be given to what sorts of attacks the
cryptographic protection is susceptible.

Data which should be held secret (keying material, random seeds, etc.)
should be clearly labeled.

If the technology involves authentication, particularly user-host
authentication, the security of the authentication method MUST be
clearly specified.

Residual risks (such as the risks from compromise in a related protocol,
incorrect implementation, or cipher) after threat mitigation has been
deployed.

This section MUST provide integrity protection and update authentication
for all operations required by Section 7 of this specification (DID
Operations).

6.1. Binding of Identity

6.2. Authentication Service Endpoints

6.3. Non-Repudiation

6.4. Notification of DID Document Changes

6.5. Key and Signature Expiration

6.6. Key Revocation and Recovery

7. Privacy Considerations

7.1. Keep Personally-Identifiable Information (PII) Off-Ledger

7.2. Correlation Risks

7.3. Herd Privacy

Appendix A: Examples

Typical DID Document

The following is a complete example of a typical IPID DID Document:

EXAMPLE: Typical IPID DID Document

{
  "@context": {
    "/": "zdpuAmoZixxJjvosviGeYcqduzDhSwGV2bL6ZTTXo1hbEJHfq"
  },
  "authentication": {
    "type": "EdDsaSASignatureAuthentication2018",
    "publicKey": [
      "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew"
    ]
  },
  "created": "2018-12-01T03:00:00Z" ,
  "id": "did:ipid:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew",
  "previous": {
    "/": "zdpuB1oR3vjYmkDc9ALfY7o6hSt1Hrg2ApXaYAFyiAW5E4NJP"
  },
  "proof": {
    "/": "z43AaGF42R2DXsU65bNnHRCypLPr9sg6D7CUws5raiqATVaB1jj"
  },
  "publicKey": [
    {
      "curve": "ed25519",
      "publicKeyBase64": "qmz7tpLNKKKdl7cD7PbejDiBVp7ONpmZbfmc7cEK9mg=",
      "type": "EdDsaPublicKey",
      "status": "revoked"
    },
    {
      "curve": "ed25519",
      "expires": "2021-07-08T16:02:20Z",
      "publicKeyBase64": "jGp4OT1GktrZMdrkOM+zj8iE1IqCiqg2iH+rUZ93jhE=",
      "type": "EdDsaPublicKey"
    }
  ],
  "signature": {
    "created": "2018-12-01T03:00:04Z" ,
    "creator": "zdpuAt99xoa8i2BrcjwpY2H6ksXeaE28upionw2VuxRamBs6H/publicKey/1",
    "message": {
      "/": "zdpuAyvreXzQHqwv3rL8MaVPjNJjpLLa5Du3HcbpQL41XS35G"
    },
    "signatureValue": "WDA3Dx7c+UWR37oglhkLNwxAbxXM4YbT7TpgmaCQ/rSqbtXgM3EpQ4mpkPXT5OBLH6bDai12Ank8SUHW47JxCQ==",
    "type": "ed25519Signature2018"
  },
  "updated": "2018-12-01T03:00:04Z" 
}