DIDs that target a distributed ledger face significant practical challenges in bootstrapping enough meaningful trusted data around identities to incentivize mass adoption. We propose using a new DID method that allows them to bootstrap trust using a Tor Hidden Service's existing reputation.

Introduction

Preface

The Onion DID method specification conforms to the requirements specified in the Decentralized Identifiers v1.0 Specification [[DID-CORE]]. For more information about DIDs and DID method specifications, please also see the [[?DID-PRIMER]]

Example 

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:onion:fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid",
  "verificationMethod": [{
    "id": "#g7r2t9G8dBBnG7yZkD8sly3ImDlrntB25s2pGuaD97E",
    "type": "JsonWebKey2020",
    "controller": "did:onion:fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid",
    "publicKeyJwk": {
      "crv": "Ed25519",
      "x": "LIUp9Jdi2R17QcZnbPFZOYyV5oyotNHU2J5dQUdTUa4",
      "kty": "OKP"
    }
  }]
}

The id of the verification method SHOULD be the JWK thumbprint calculated from the publicKeyJwk property value according to [[RFC7638]] or did:key Multicodec identifier for the publicKeyBase58 property.

DID Onion Method

Target system

The target system of the Onion DID method is the Tor Hidden Service that the identifier described by the DID resolves to when queried through Tor.

Method name

The namestring that shall identify this DID method is: onion. A DID that uses this method MUST begin with the following prefix: did:onion. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is specified below.

Method-specific identifier

The method specific identifier is a Tor Hidden Service identifier with an optional path to the DID document. The formal rules describing valid onion address syntax are described in [[RFC7686]].

The method specific identifier MUST match the Tor Hidden Service, and it MUST NOT include IP addresses or port numbers. Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes. 

onion-did = "did:onion:" onion-address
onion-did = "did:onion:" onion-address * (":" path)
        
did:onion:fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid

did:onion:fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid:user:alice

DID Method Operations

Create (Register)

Creating a DID is done by:

  1. generating and operating a Tor Hidden Service that serves a filesystem directory.
  2. storing the location of a hosting service.
  3. creating the DID document JSON-LD file including a suitable keypair, e.g., using the Ed25519 Curve, and storing the did.json file under the well-known URL to represent the entire domain, or under the specified path if many DIDs will be resolved in this domain.

For example, for the domain name `fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid.onion`, the `did.json` will be available under the following URL: 

did:onion:fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid
 -> http://fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid.onion/.well-known/did.json

If an optional path is specified rather the bare origin, the did.json will be available under the specified path: 

did:onion:fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid:user:alice
 -> http://fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid.onion/user/alice/did.json

Read (Resolve)

The following steps MUST be executed to resolve the DID document from an Onion DID:

  1. Replace ":" with "/" in the method specific identifier to obtain the fully qualified domain name and optional path.
  2. Generate an HTTP URL to the expected location of the DID document by prepending http:// and ending in .onion.
  3. If no path has been specified in the URL, append /.well-known.
  4. Append /did.json to complete the URL.
  5. Perform an HTTP GET request to the URL using an agent that can successfully negotiate a secure HTTP connection to a Tor Hidden Service, which enforces the security requirements as described in .

The read mechanism does not provide any sort of auditability on the DID, which leaves this DID Method open to insider-threat attacks in scenarios where the DID Controller is not the service operator.

Update

To update the DID document, the did.json has to be updated. Please note that the DID will remain the same, but the contents of the DID document could change, e.g., by including a new verification key or adding service endpoints.

There is no HTTP API specified for the update process leaving programmatic registrations and management to be defined by each implementation.

Deactivate (Revoke)

To delete the DID document, the did.json has to be removed or has to be no longer publicly available due to any other means.

Security and Privacy Considerations

Because Tor Hidden services already provide end to end encryption, a second layer of TLS is redundantt. However, implenters should be familiar with [[OWASP-TRANSPORT]], and related industry best practices for securing web services.

Tor Considerations

The security properties of the Tor network, and related Tor software are relied on by did:onion.

Implementers are cautioned to follow all best practices associated with operating a Tor Hidden service.

See RFC 7686 for security considerations associated aith .onion.

See torproject.org for the latest documentation on th Tor Project.

Optional Path Considerations

When optional paths to DID documents are used to resolve documents rather than bare domains, verification with signed data proves that the entity in control of the file indicated in the path has the private keys. It does not prove that the domain operator has the private keys.

This example: 

did:onion:fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid:u:bob

resolves to the DID document at: 

http://fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid.onion/u/bob/did.json

In this scenario, it is probable that fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid.onion has given user Bob control over the DID in question, and proofs of control refer to Bob rather than all of fscst5exmlmr262byztwz4kzhggjlzumvc2ndvgytzoucr2tkgxf7mid.onion.

Reference Implementations