Skip to main content

ADR-001: DID Method Specification

hackmd-github-sync-badge

Abstract

Sonr is a privacy focused blockchain built to reinvent how we handle identity and data transmission. Sonr also supports DID operations. DIDs are created and stored in the Sonr Node, and they are used with verifiable credentials.

This specification describes how DIDs are managed on the Sonr.

DID Method Name

The name-string is snr.

A DID must begin with the prefix: did:snr in lowercase.

DID Method Specific Identifier

sonr-did = "did:snr:" idstring
idstring = 32*44(base58)
base58 = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" / "A" / "B" /
"C" / "D" / "E" / "F" / "G" / "H" / "J" / "K" / "L" / "M" / "N" /
"P" / "Q" / "R" / "S" / "T" / "U" / "V" / "W" / "X" / "Y" / "Z" /
"a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" / "j" / "k" /
"m" / "n" / "o" / "p" / "q" / "r" / "s" / "t" / "u" / "v" / "w" /
"x" / "y" / "z"

The idstring is a base58-encoded SHA-256 hash of a Secp256k1 public key, otherwise known as the Sonr Blockchain Wallet address. This means that DIDs are case-sensitive, even though the prefix is always lower-case. The Sonr Highway CLI provides a tool for generating the Secp256k1 key-pair either randomly or from a BIP44 mnemonic provided by the user.

Example:

did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm

Relationship between DIDs and Sonr wallet accounts

Sonr Blockchain Wallets are integrated within every Motor powered application. The Sonr Motor is a light peer-to-peer node embedded within every decentralized application built with the Highway SDK. From here on, a Sonr Blockchain Wallet Account will be referenced as a motor.

DID Document Format (JSON-LD)

{
"@context": "https://www.w3.org/ns/did/v1",

// All connected Motor Nodes for a Sonr User
"controller":[
"did:snr:123",
],

// Address to Multisig wallet for all user motor nodes
"id": "did:snr:abc",

// Registered alias (.snr) names
"alsoKnownAs": [
"test.snr",
"example.snr"
],

// User authenticated application credentials get stored as assertionMethod
"assertionMethod": [...],

// Connected Motors webauthn credentials get stored as verificationMethod
"verificationMethod": [
{
// Set to Motor Nodes Wallet Address
"controller": "did:snr:123",

// Id of Key set to unique value and operating system/architecture
"id": "did:snr:123#ios-arm64-1",

// JWK generated from WebAuthN Credential
"publicKeyJwk": {
"crv": "P-256",
"kty": "EC",
"x": "UANQ8pgvJT33JbrnwMiu1L1JCGQFOEm1ThaNAJcFrWA=",
"y": "UWm6q5n1iXyeCJLMGDInN40bkkKr8KkoTWDqJBZQXRo="
},
"type": "JsonWebKey2020"
}
],

// User public facing services
"service": [{
// Inbound/Outbound Mailbox - Sonr Core Service
"id":"snr:123#mailbox",
"type": "EncryptedDataVault",
// MultiAddr of hosted IPFS node
"serviceEndpoint": "/ip4/159.313.1.45/tcp/57665/peer/123/snr/test"
}]
}

controller : Currently, the controller represents the set of DIDs associated with the top-level document for a User. In order for the controller to be valid an accompanying entry must be present in the verificationMethod and must conform to the **FIDO2 WebAuthn** specification.

id : The ID of the DIDDocument is created from the multisignature key address returned from the set of all PublicKey ’s present with matching controllers. The id is regenerated on every instance a controller is added or removed from the DIDDocument.

alsoKnownAs : This property is utilized to provide resolvable aliases to the associated DIDDocument. Users purchase a name alias which is suffixed by, .snr, a resolvable TLD on the Handshake Network. Motor nodes are packaged with the lightweight HNS Resolver.

assertionMethod : This property is currently being used to store authenticated application credentials. When Users first access an application, they utilize the account DID in order to authenticate their session.

verificationMethod : This property is utilized for storing the individual Motor WebAuthn credentials. This mechanism is put into place to associate users by individual devices opposed to strictly an account based structure.

CRUD Operations

Create

(POST): /v1/registry/create/whois
- Owner:string
- DidDocument:[]byte
- WhoisType:Enum{ WhoisType_APP | WhoisType_USER }

This method takes a DIDDocument as an input along with the did of the account calling the TX, and verifies the signature. If successful, and there is no existing WhoIs created for the user or application. Parameters include: Signature, DIDDocument, address, and WhoIsType.

The resulting response is a WhoIs object containing the following payload body:


{
"document": {
"@context": "<https://www.w3.org/ns/did/v1>",
"id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"verificationMethod": [
{
"id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1",
"type": "Secp256k1VerificationKey2018",
"controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"publicKeyBase58": "dBuN4i7dqwCLzSX7GHBLsfUoXw5RmWQ3DwQ9Ee4bfh5Y"
}
],
"authentication": [
"did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1"
]
},
"sequence": "0"
}

CRUD Operations

All transactions TX will incur a gas fee whenever read and writes are made to the store. `fees = gas gas-prices`*

Create

(POST): /v1/registry/create/whois
- Owner:string
- DidDocument:[]byte
- WhoisType:Enum{ WhoisType_APP | WhoisType_USER }

This method takes a DIDDocument as an input along with the DID of the account calling the TX and verifies the signature. If successful, and there is no existing WhoIs created for the user or application. Parameters include: Signature, DIDDocument, address, and WhoIsType.

Read

A Sonr DID Document can be looked up with three possible queries.

// Find a DIDDocument by ID
(GET): /v1/registry/query/whois/:did
- DID:string

// Find a DIDDocument with the matching controller
(GET): /v1/registry/query/whois/controller/:did
- DID:string

// Find a DIDDocument with the matching alias
(GET): /v1/registry/query/whois/alias/:name
- Name:string

If the DID exists (not deactivated yet), the result is a WhoIs object:

{
"document": {
"@context": "<https://www.w3.org/ns/did/v1>",
"id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"verificationMethod": [
{
"id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1",
"type": "Secp256k1VerificationKey2018",
"controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"publicKeyBase58": "dBuN4i7dqwCLzSX7GHBLsfUoXw5RmWQ3DwQ9Ee4bfh5Y"
}
],
"authentication": [
"did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1"
]
},
"alias": ["a.snr", "b.snr"],
"controllers": [snr7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm],
}

The alias list and controller list for wallet addresses is returned along with the document. It must be included in the subsequent transaction (update/deactivate) for preventing transaction replay attacks.


Update

Only the DID owner can replace the DID Document using the following transaction.

(POST): /v1/registry/update/whois
- Owner:string
- DidDocument:[]byte
- Did:string

This example is for adding a new public key to the verificationMethod and adding a dedicated public key to the authentication.

{
"type": "did/MsgUpdateDID",
"value": {
"did": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"document": {
"@context": "<https://www.w3.org/ns/did/v1>",
"id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"verificationMethod": [
{
"id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1",
"type": "Secp256k1VerificationKey2018",
"controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"publicKeyBase58": "dBuN4i7dqwCLzSX7GHBLsfUoXw5RmWQ3DwQ9Ee4bfh5Y"
},
{
"id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key2",
"type": "Secp256k1VerificationKey2018",
"controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"publicKeyBase58": "2BjcxuwijyE1om4991ANiFrwZJ3Ev5YYX9KiPKgaHmGsi"
}
],
"authentication": [
"did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1",
{
"id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key3",
"type": "Secp256k1VerificationKey2018",
"controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"publicKeyBase58": "yE1om4991ANiFrwZJ3Ev5YYX9KiPKgaHmGsi2Bjcxuwij"
}
]
},
"signature": "xtsQH3D5naHe9IXmhCnohlChwHiD0dx9PI4aPkaJPGoEznYMHmg0aBerg85ai7T2WNxxlc39uFzAxKbI4sbJCA==",
"verification_method_id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1",
"from_address": "sonr1d58s72gu0mjkw0lkgyvr0eqzz3mv74awfsjslz"
}
}

Like creating DIDs, the signature must be generated from the document and the sequence returned from the Read DID operation. It must be signed with a private key which corresponds to the public key referred by the verification_method_id. The verification_method_id must be one of the key IDs specified in the authentication of the document.

Whenever submitting this transaction the user must query the current sequence by the Read DID operation. (The user can also increment the sequence manually, but the transaction can be rejected if there are the concurrent transactions with the same sequence.)

The source of the signature should look like (encoded with Amino):

{
"data": {
"@context": ...,
"id": "did:snr:...",
...
},
"sequence": "50"
}

The transaction fails if the DID has been already deactivated.


Deactivate

To deactivate the DID document, the DID owner should send the following transaction.

(POST): /v1/registry/deactivate/whois
- Owner:string
- Did:string

Sonr doesn't delete the DID document. The document is just deactivated. This strategy guarantees that malicious users cannot recreate the DID, because the DID deactivation may be appropriate when a person dies or a business is terminated.

{
"type": "did/MsgDeactivateDID",
"value": {
"did": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm",
"signature": "xtsQH3D5naHe9IXmhCnohlChwHiD0dx9PI4aPkaJPGoEznYMHmg0aBerg85ai7T2WNxxlc39uFzAxKbI4sbJCA==",
"verification_method_id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1",
"from_address": "sonr1d58s72gu0mjkw0lkgyvr0eqzz3mv74awfsjslz"
}
}

This method sets the state of a particular WhoIs to be deactivated. In order to successfully perform this request, the TX creator and signature must be the same as the WhoIs owner.

The signature must be generated from the did and the sequence returned from the Read DID operation. It must be signed with a private key which corresponds to the public key referred by the verification_method_id. The verification_method_id must be one of the key IDs specified in the authentication of the document.

The source of the signature should look like (encoded with Amino):

{
"data": "did:snr:...",
"sequence": "50"
}

The transaction fails if the DID doesn't exist or if it has been already deactivated.

Resolution of Aliases

User’s can purchase alias identifiers with the .snr domain namespace in order to have applications resolve their DIDDocument. This is how to purchase a new alias on behalf of a user.

Buying an Alias

(POST): /v1/registry/buy/alias/name
- Creator:string
- Did:string
- Amount:int32
- Name:string

This method purchases a user alias .snr domain i.e. {example}.snr, and inserts it into the alsoKnownAs field of the app's DIDDocument. Request fails when the DIDDoc type doesn’t match, wallet balance is too low, the alias has already been purchased, creator is not listed as controller of DIDDoc, or WhoIs is deactivated. The purchase of a user alias .snr domain will have a cost associated.

Selling an Alias

(POST): /v1/registry/sell/alias/name
- Creator:string
- Did:string
- Amount:int32
- Name:string

This method purchases a user alias .snr domain i.e. {example}.snr, and inserts it into the alsoKnownAs field of the app's DIDDocument. Request fails when the DIDDoc type doesn’t match, wallet balance is too low, the alias has already been purchased, creator is not listed as controller of DIDDoc, or WhoIs is deactivated. The selling of a user alias .snr domain will have a cost assocaited by the Alias Owner and will incur a fee upon sale.

Transferring Alias

In the situation that a user wants to transfer an owned alias from their DIDDocument to another peer on the network, the following method is called:

(POST): /v1/registry/transfer/alias/name
- Creator:string
- Did:string
- Alias:string
- Recipient:string

This method transfers an existing User .snr name Alias to the specified peer. The alias is removed from the current App's alsoKnownAs list and inserted into the new App's alsoKnownAs list. The transfer of an alias .snr domain will have incur a fee upon trasnfer to the specified peer.

Sequence Diagrams

erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

Privacy Considerations

This section is non-normative.

Keep Personally Identifiable Information (PII) Private

A DID Document should not include Personally Identifiable Information (PII), even if it is encrypted. All personal data should be kept behind service endpoints under the control of the DID subject. For example, if a DID Document contains a URL which contains any human-meaningful information, such as a username, some personal data can be unintentionally revealed without the DID subject's consent. For more details, please see the Decentralized Identifier Specification.

DID Correlation Risks and Pseudonymous DIDs

If DID Controllers want to mitigate the risk of correlation, they should use unique DIDs for every interaction and the corresponding DID Documents should contain a unique public key. For more details, please see the Decentralized Identifier Specification.

Reference Implementations

References