did-method

module
v0.9.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 11, 2023 License: BSD-3-Clause

README

DID Method

Build Status Version Software License Go Report Card Contributor Covenant

The present document describes the "bryk" DID Method specification. The definitions, conventions and technical details included intend to provide a solid base for further developments while maintaining compliance with the work, still in progress, on the W3C Credentials Community Group.

For more information about the origin and purpose of Decentralized Identifiers please refer to the original DID Primer.

To facilitate adoption and testing, and promote open discussions about the subjects treated, this repository also includes an open source reference implementation for a CLI client and network agent. You can directly download the binary from the published releases.

1. Decentralized Identifiers

In order to access online, i.e. digital, services, we need to be electronically identifiable. It means we need an electronic profile that, with a certain level of assurance, the service provider (either another person or an entity) can trust it corresponds to our real identity.

Conventional identity management systems are based on centralized authorities. These authorities establish a process by which to entitle a user temporary access to a given identifier element. Nevertheless, the true ownership of the identifier remains on the assigner side and thus, can be removed, revoked and reassigned if deemed adequate. This creates and intrinsically asymmetric power relationship between the authority entity and the user. Some examples of this kind of identifiers include:

  • Domain names
  • Email addresses
  • Phone numbers
  • IP addresses
  • User names

Additionally, from the standpoint of cryptographic trust verification, each of these centralized authorities serves as its own Root of Trust.

An alternative model to manage digital identifiers must be open and user-centric. It should be considered as such by satisfying at least the following considerations:

  • Anyone must have access to freely register, publish and update as many identifiers as considered necessary.
  • There should be no centralized authority required for the generation and assignment of identifiers.
  • The end user must have true ownership of the assigned identifiers, i.e. no one but the user should be able to remove, revoke and/or reassign the user's identifiers.

This model is commonly referred to as Decentralized Identifiers, and allows us to build a new (3P) digital identity: Private, Permanent and Portable.

2. Access Considerations

In order to be considered open, the system must be publicly available. Any user should be able to freely register, publish and update as many identifiers as desired without the express authorization of any third party. This characteristic of the model permits us to classify it as censorship resistant.

At the same time, this level of openness makes the model vulnerable to malicious intentions and abuse. In such a way that a bad actor may prevent legitimate access to the system by consuming the available resources. This kind of cyber-attack is known as a DoS (Denial-of-Service) attack.

In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to the Internet. Denial of service is typically accomplished by flooding the targeted machine or resource with superfluous requests in an attempt to overload systems and prevent some or all legitimate requests from being fulfilled.

The "bryk" DID Method specification includes a "Request Ticket" security mechanism designed to mitigate risks of abuse while ensuring open access and censorship resistance.

3. DID Method Specification

The method specification provides all the technical considerations, guidelines and recommendations produced for the design and deployment of the DID method implementation. The document is organized in 3 main sections.

  1. DID Schema. Definitions and conventions used to generate valid identifier instances.
  2. DID Document. Considerations on how to generate and use the DID document associated with a given identifier instance.
  3. Agent Protocol. Technical specifications detailing how to perform basic network operations, and the risk mitigation mechanisms in place, for tasks such as:
    • Publish a new identifier instance.
    • Update an existing identifier instance.
    • Resolve an existing identifier and retrieve the latest published version of its DID Document.
3.1 DID Schema

A Decentralized Identifier is defined as a RFC3986 Uniform Resource Identifier, with a format based on the generic DID schema. Fore more information you can refer to the original documentation.

did                = "did:" method-name ":" method-specific-id
method-name        = 1*method-char
method-char        = %x61-7A / DIGIT
method-specific-id = *idchar *( ":" *idchar )
idchar             = ALPHA / DIGIT / "." / "-" / "_"
did-url            = did *( ";" param ) path-abempty [ "?" query ]
                     [ "#" fragment ]
param              = param-name [ "=" param-value ]
param-name         = 1*param-char
param-value        = *param-char
param-char         = ALPHA / DIGIT / "." / "-" / "_" / ":" /
                     pct-encoded

Example of a simple Decentralized Identifier (DID).

did:example:123456789abcdefghi

Expanding on the previous definitions the bryk DID Method specification use the following format.

did                = "did:bryk:" [tag ":"] specific-idstring
tag                = 1*tagchar
specific-idstring  = depends on the particular use case
tagchar            = ALPHA / DIGIT / "." / "-"

The optional tag element provides a flexible namespace mechanism that can be used to classify identifier instances into logical groups of arbitrary complexity.

The specific-idstring field does not impose any format requirements to ensure the maximum level of flexibility to end users and implementers. The official implementation however, proposes and recommends two formal modes for id strings.

3.1.1 Mode UUID

The id string should be a randomly generated lower-case UUID v4 instance as defined by RFC4122. The formal schema for the specific-idstring field on this mode is the following.

specific-idstring      = time-low "-" time-mid "-"
                         time-high-and-version "-"
                         clock-seq-and-reserved
                         clock-seq-low "-" node
time-low               = 4hexOctet
time-mid               = 2hexOctet
time-high-and-version  = 2hexOctet
clock-seq-and-reserved = hexOctet
clock-seq-low          = hexOctet
node                   = 6hexOctet
hexOctet               = hexDigit hexDigit
hexDigit               = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" /
                         "8" / "9" / "a" / "b" / "c" / "d" / "e" / "f"

Example of a DID instance of mode UUID with a tag value of c137.

did:bryk:c137:02825c9d-6660-4f17-92db-2bd22c4ed902
3.1.2 Mode Hash

The id string should be a randomly generated 32 bytes SHA3-256 hash value, encoded in hexadecimal format as a lower-case string of 64 characters. The formal schema for the specific-idstring field on this mode is the following.

specific-idstring = 32hexOctet
hexOctet          = hexDigit hexDigit
hexDigit          = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" /
                    "8" / "9" / "a" / "b" / "c" / "d" / "e" / "f"

Example of a DID instance of mode hash with a tag value of c137.

did:bryk:c137:85d48aebe67da2fdd273d03071de663d4fdd470cff2f5f3b8b41839f8b07075c
3.2 DID Document

A Decentralized Identifier, regardless of its particular method, can be resolved to a standard resource describing the subject. This resource is called a DID Document, and typically contains, among other relevant details, cryptographic material to support authentication of the DID subject.

The document is a Linked Data structure that ensures a high degree of flexibility while facilitating the process of acquiring, parsing and using the contained information. For the moment, the suggested encoding format for the document is JSON-LD. Other formats could be used in the future.

The term Linked Data is used to describe a recommended best practice for exposing sharing, and connecting information on the Web using standards, such as URLs, to identify things and their properties. When information is presented as Linked Data, other related information can be easily discovered and new information can be easily linked to it. Linked Data is extensible in a decentralized way, greatly reducing barriers to large scale integration.

At the very least, the document must include the DID subject it's referring to under the id key.

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:bryk:c137:b616fca9-ad86-4be5-bc9c-0e3f8e27dc8d"
}

As it stands, this document is not very useful in itself. Other relevant details that are often included in a DID Document are:

  • Created: Timestamp of the original creation.
  • Updated: Timestamp of the most recent change.
  • Public Keys: Public keys are used for digital signatures, encryption and other cryptographic operations, which in turn are the basis for purposes such as authentication, secure communication, etc.
  • Authentication: List the enabled mechanisms by which the DID subject can cryptographically prove that they are, in fact, associated with a DID Document.
  • Services: In addition to publication of authentication and authorization mechanisms, the other primary purpose of a DID Document is to enable discovery of service endpoints for the subject. A service endpoint may represent any type of service the subject wishes to advertise, including decentralized identity management services for further discovery, authentication, authorization, or interaction.

Additionally, the DID Document may include any other fields deemed relevant for the particular use case or implementation.

Example of a more complete, and useful, DID Document.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/v1"
  ],
  "id": "did:bryk:c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683",
  "created": "2019-03-09T15:44:15Z",
  "updated": "2019-03-09T15:44:15Z",
  "publicKey": [
    {
      "id": "did:bryk:c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683#master",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:bryk:c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683",
      "publicKeyBase58": "CmTmF8kiepYmsPBXgyjdPW5dpvpW9J2RfVHGUcJJHhMg"
    },
    {
      "id": "did:bryk:c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683#backup",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:bryk:c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683",
      "publicKeyHex": "5d0b7e4efb804fdb967890ab66cd5b793db47e7a1d9692e3edd8893cc41a8d63"
    }
  ],
  "authentication": [
    "did:bryk:c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683#master",
    "did:bryk:c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683#backup"
  ],
  "service": [
    {
      "id": "did:bryk:c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683;portal.service",
      "type": "identity.bryk.io.ExternalService",
      "serviceEndpoint": "http://c137.com/path/to/user",
      "data": {
        "individual": "rick"
      }
    }
  ]
}

Is important to note that the official specifications around service endpoints are still in a very early stage at this point. Where appropriate or required the present Method specification builds on it and introduces new considerations.

3.2.1 Method Requirements

Building upon the base requirements and recommendations from the original specification, the "bryk" DID method introduces the following additional guidelines.

  • The fields created and updated are required for all generated DID Documents.
  • All service endpoints included in the DID Document may include an additional data field. Is recommended to include all extra parameters required for the particular service under this field.
  • Supported public keys and signature formats

More information on the official keys and signatures formats is available at LD Cryptographic Suite Registry.

3.2.2 Proofs

proof: Cryptographic proof of the integrity of the DID Document according its subject. Recently it was removed from the DID core document. This method still generates valid proofs for all mutations performed on the DID documents and returns it under the proof element of all resolved identifiers.

{
  "document": "...",
  "proof": {
    "@context": [
      "https://w3id.org/security/v1"
    ],
    "type": "Ed25519Signature2018",
    "created": "2020-08-08T03:12:53Z",
    "domain": "did.bryk.io",
    "nonce": "3ec84acf8b301f3d7e0bba25a24b438a",
    "proofPurpose": "authentication",
    "verificationMethod": "did:bryk:46389176-6109-4de7-bdb4-67e4fcf0230d#master",
    "proofValue": "QvVkJxTWHf6BQO5A/RzgqDoz6neKaagHWspwSeWqztWnjnt7Rlc73KKiHRs9++C2tdV3pZQtPiKDk6C7Q7nFAQ=="
  }
}

More information about this change is available here.

3.3 Agent Protocol

The method implementation introduces the concept of a network agent. A network agent is responsible for handling incoming client requests. It's very important to note that the agent itself adheres to an operational protocol. The protocol is independent of the data storage and message delivery mechanisms used. The method protocol can be implemented using a Distributed Ledger Platform, as well as any other infrastructure suitable for the particular use case.

There are two main groups of operations available, read and write. Write operations are required when a user wishes to publish a new identifier record to the network, or update the available information for an existing one. Read operations enable resolution and retrieval of DID Documents and other relevant assets published in the network.

3.3.1 Request Ticket

As described earlier, a security mechanism is required to prevent malicious and abusive activities. For these purposes, we introduce a ticket requirement for all write network operations. The mechanism is based on the original HashCash algorithm and aims to mitigate the following problems.

  • Discourage DoS Attacks. By making the user cover the “costs” of submitting a request for processing.
  • Prevent Replay Attacks. Validating the ticket was specifically generated for the request being processed.
  • Requests Authentication. Ensuring the user submitting the ticket is the owner of the DID, by incorporating a digital signature requirement that covers both the ticket details and the DID instance.

A request ticket has the following structure.

ticket {
  int64  timestamp
  int64  nonce
  string key_id
  bytes  document
  bytes  proof
  bytes  signature
}

The client generates a ticket for the request using the following algorithm.

  1. Let the "bel" function be a method to produce a deterministic binary-encoded representation of a given input value using little endian byte order.
  2. Let the "hex" function be a method to produce a deterministic hexadecimal binary-encoded representation of a given input value.
  3. "timestamp" is set to the current UNIX time at the moment of creating the ticket.
  4. "nonce" is a randomly generated integer of 64bit precision.
  5. "key_id" is set to the identifier from the cryptographic key used to generate the ticket signature, MUST be enabled as an authentication key for the DID instance.
  6. "document" is set to the JSON-encoded DID Document to process.
  7. "proof" is set to the JSON-encoded valid proof for the DID Document to process.
  8. A HashCash round is initiated for the ticket. The hash mechanism used MUST be SHA3-256 and the content submitted for each iteration of the round is a byte concatenation of the form: "bel(timestamp) | bel(nonce) | hex(key_id) | document | proof".
  9. The "nonce" value of the ticket is atomically increased by one for each iteration of the round.
  10. The ticket's "challenge" is implicitly set to the produced hash from the HashCash round.
  11. The "signature" for the ticket is generated using the selected key of the DID and the obtained challenge value: did.keys["key_id"].sign(challenge)

Upon receiving a new write request the network agent validates the request ticket using the following procedure.

  1. Verify the ticket's challenge is valid by performing a HashCash verification.
  2. Validate document are a properly encoded DID Document.
  3. Validate proof is valid for the DID Document included in the ticket.
  4. DID instance method value is properly set and supported by the agent.
  5. Ensure document don’t include any private key. For security reasons no private keys should ever be published on the network.
  6. Verify signature is valid.
    • For operations submitting a new entry, the key contents are obtained directly from the ticket contents. This ensures the user submitting the new DID instance is the one in control of the corresponding private key.
    • For operations updating an existing entry, the key contents are obtained from the previously stored record. This ensures the user submitting the request is the one in control of the original private key.
  7. If the request is valid, the entry will be created or updated accordingly.

A sample implementation of the described Request Ticket mechanism is available here.

3.3.2 DID Resolution

The simplest mechanism to resolve a particular DID instance to the latest published version of its corresponding DID Document is using the agent's HTTP interface.

The resolution and data retrieval is done by performing a GET request of the form:

https://did.bryk.io/v1/retrieve/{{method}}/{{subject}}

For example:

curl -v https://did.bryk.io/v1/retrieve/bryk/4d81bd52-2edb-4703-b8fc-b26d514a9c56

If the subject is valid, and information has been published to the network, the response will include the latest version available of its corresponding DID Document encoded in JSON-LD with a 200 status code. If no information is available the response will be a JSON encoded error message with a 404 status code.

{
  "document": "...",
  "proof": "..."
}

You can also retrieve an existing subject using the provided SDK and RPC interface. For example, using the Go client.

// Error handling omitted for brevity
sub := "c137:eeb0c865-ce21-4ad6-baf8-5ba287ba8683"
response, _ := client.Retrieve(context.TODO(), proto.Request{Subject:sub})
if response.Ok {
	id := new(did.Identifier)
	id.Decode(response.Contents)
}
3.3.3 DID Publishing and Update

To publish a new identifier instance or to update an existing one you can also use the agent's HTTP interface or the provided SDK and clients.

When using HTTP the operation should be a POST request with a properly constructed and JSON-encoded request as the request's data. Binary data should be encoded in standard Base64 when transmitted using JSON.

You can also publish and update a DID identifier instance using the provided SDK and RPC interface. For example, using the Go client.

// Error handling omitted for brevity
res, _ := client.Process(context.TODO(), request)
if res.Ok {
	// ...
}

4. Client Operations

To enable the full functionality of DIDs and DID Documents on a particular distributed ledger or network (called the target system), a DID method specification MUST specify how each of the following CRUD operations is performed by a client. Each operation MUST be specified to the level of detail necessary to build and test interoperable client implementations with the target system.

The following sections provide detailed descriptions and examples of all required CRUD base operations and some more advanced use cases. As described earlier, all supported operations can be accessed using either the agent's HTTP interface or the provided SDK and CLI client tool.

For brevity the following examples use the provided CLI client tool.

4.1 CRUD Operations

Basic operations enabling the users to create, read, update and delete identifier instances.

4.1.1 Create (Register)

To locally create a new DID instance.

didctl create [reference name]

The value provided for reference name is an easy-to-remember alias you choose for the new identifier instance, it won't have any use in the network context. The CLI also performs the following tasks for the newly generated identifier.

  • Create a new master Ed25519 private key for the identifier
  • Set the master key as an authentication mechanism for the identifier
  • Generates a cryptographic integrity proof for the identifier using the master key

If required, the master key can be recovered using the selected recovery-mode, for more information inspect the options available for the create command.

Creates a new DID locally

Usage:
  didctl register [flags]

Aliases:
  register, create, new

Examples:
didctl register [DID reference name]

Flags:
  -h, --help                    help for register
      --recovery-mode string    choose a recovery mechanism for your primary key, 'passphrase' or 'secret-sharing' (default "secret-sharing")
      --secret-sharing string   specify the number of shares and threshold value in the following format: shares,threshold (default "3,2")
      --tag string              specify a tag value for the identifier instance
4.1.2 Read (Verify)

You can retrieve a list of all your existing identifiers using the following command.

didctl list

The output produced will be something like this.

Reference Name    Recovery Mode     DID
dev               passphrase        did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56
sample            secret-sharing    did:bryk:99dc4a30-7434-42e5-ac75-5f330be0ea0a

To inspect the DID Document of your local identifiers.

didctl info [reference name]

The generated document will be something similar for the following example.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/v1"
  ],
  "id": "did:bryk:99dc4a30-7434-42e5-ac75-5f330be0ea0a",
  "created": "2019-03-14T12:02:33-04:00",
  "updated": "2019-03-14T12:02:33-04:00",
  "publicKey": [
    {
      "id": "did:bryk:99dc4a30-7434-42e5-ac75-5f330be0ea0a#master",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:bryk:99dc4a30-7434-42e5-ac75-5f330be0ea0a",
      "publicKeyHex": "e5271fa5208eedf6c95611320ed8c4300dcd04ab57207364a0909fc64c5e30d7"
    }
  ],
  "authentication": [
    "did:bryk:99dc4a30-7434-42e5-ac75-5f330be0ea0a#master"
  ],
  "proof": {
    "@context": [
      "https://w3id.org/security/v1"
    ],
    "type": "Ed25519Signature2018",
    "creator": "did:bryk:99dc4a30-7434-42e5-ac75-5f330be0ea0a#master",
    "created": "2019-03-14T16:02:34Z",
    "domain": "did.bryk.io",
    "nonce": "7e0fda2827eec4418df4513d2d6874c5",
    "proofValue": "cKDKBgNS6itQF1zDaOUd6bDo+5CIKoSN+lOb8PkZqvT+K3c2wvDUVqMYN8mKA0Om+B8wYM1qDz9mI0iWva0qBg=="
  }
}

If a certain DID identifier has previously been published to the network, you can resolve it and retrieve the latest version of its corresponding DID Document using the get command. To run a verification of the cryptographic integrity proof contained in the document you can add the --verify option.

didctl get --verify did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56

The command will perform the required network operations and verifications.

[Mar 14 12:15:23.674]  INFO establishing connection to the network with node: rpc-did.bryk.io:80
[Mar 14 12:15:23.713] DEBUG retrieving record
[Mar 14 12:15:23.721] DEBUG decoding contents
[Mar 14 12:15:23.721]  INFO verifying the received DID document
[Mar 14 12:15:24.277]  INFO integrity proof is valid
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/v1"
  ],
  "id": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56",
  "created": "2019-03-10T13:42:34-04:00",
  "updated": "2019-03-12T10:07:55-04:00",
  "publicKey": [
    {
      "id": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56#master",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56",
      "publicKeyHex": "be4db03c2f809aa79ea3055a2da8ddfd807fecd073356e337561cd0640251d9f"
    },
    {
      "id": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56#code-sign",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56",
      "publicKeyHex": "e7cc93d399e467a39fca74e32795b1ab1110a7dc94e8623830cd069c1cac72b8"
    }
  ],
  "authentication": [
    "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56#master"
  ],
  "proof": {
    "@context": [
      "https://w3id.org/security/v1"
    ],
    "type": "Ed25519Signature2018",
    "creator": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56#master",
    "created": "2019-03-12T14:07:56Z",
    "domain": "did.bryk.io",
    "nonce": "09206a2a195cd14f5a6cac70279bba35",
    "proofValue": "YdY1+GxDNwlc55alKZIJ0if55FwQsE2Gan91l+fuv+UF1UAnI10l/DelGPyBSOO2OUiTNzXC6x/jojOum/RNDg=="
  }
}
4.1.3 Update (Publish)

Whenever you wish to make one of your identifiers, in its current state, accessible to the world, you can publish it to the network.

didctl sync sample

The CLI tool will generate the Request Ticket, submit the operation for processing to the network and present the final result.

[Mar 14 12:26:30.435] DEBUG key selected for the operation: did:bryk:99dc4a30-7434-42e5-ac75-5f330be0ea0a#master
[Mar 14 12:26:30.435]  INFO updating record proof
[Mar 14 12:26:31.075]  INFO publishing: sample
[Mar 14 12:26:31.075]  INFO generating request ticket
[Mar 14 12:28:00.230] DEBUG ticket obtained: 00000042186234bab7d3e39207a9fcde7c8e71c2b4e84cf528f0328b3d6e8a32
[Mar 14 12:28:00.230] DEBUG time: 1m29.154355394s (rounds completed 21723044)
[Mar 14 12:28:00.231]  INFO establishing connection to the network with node: rpc-did.bryk.io:80
[Mar 14 12:28:00.232]  INFO submitting request to the network
[Mar 14 12:28:00.234] DEBUG request status: true

Once an identifier is published any user can retrieve and validate your DID document. If you make local changes to your identifier, like adding a new cryptographic key or service endpoint, and you wish these adjustments to be accessible to the rest of the users, you'll need to publish it again.

4.1.4 Delete (Deactivate)

If at some point you wish to prevent other users to resolve one of yours previously published identifiers you may submit a deactivation request by adding the --deactivate option to the sync command.

didctl sync sample --deactivate

No information is destroyed or lost with these operations, the identifier and all its related data is safely stored on your local machine. This will only prevent other users from retrieving your DID Document from the network.

4.2 DID Instance Management

The CLI client also facilitates some tasks required to manage a DID instance.

4.2.1 Key Management

A DID Document list all public keys in use for the referenced DID instance. Public keys are used for digital signatures, encryption and other cryptographic operations, which in turn are the basis for purposes such as authentication, secure communication, etc.

Manage cryptographic keys associated with the DID

Usage:
  didctl edit key [command]

Available Commands:
  add         Add a new cryptographic key for the DID
  recover     Recover a previously generated Ed25519 cryptographic key
  remove      Remove an existing cryptographic key for the DID
  sign        Produce a linked digital signature

Flags:
  -h, --help   help for key

Global Flags:
      --config string   config file ($HOME/.didctl/config.yaml)
      --home string     home directory ($HOME/.didctl)

Use "didctl edit key [command] --help" for more information about a command.

To add a new cryptographic key to one of your identifiers you can use the did key add command.

Add a new cryptographic key for the DID

Usage:
  didctl edit key add [flags]

Examples:
didctl edit key add [DID reference name] --name my-new-key --type ed --authentication

Flags:
      --authentication   enable this key for authentication purposes
  -h, --help             help for add
      --name string      name to be assigned to the newly added key (default "key-#")
      --type string      type of cryptographic key, either RSA (rsa) or Ed25519 (ed) (default "ed")

It will produce and properly add a public key entry. The cryptographic integrity proof on the DID Document will also be updated accordingly.

{
  "id": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56#code-sign",
  "type": "Ed25519VerificationKey2018",
  "controller": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56",
  "publicKeyHex": "e7cc93d399e467a39fca74e32795b1ab1110a7dc94e8623830cd069c1cac72b8"
}

You can also safely remove an existing key from your identifier using the edit key remove command.

edit key remove [DID reference name] [key name]
4.2.2 Linked Data Signatures

The CLI client also facilitates the process of generating and validating Linked Data Signatures. For example, to create a new signature document from an existing file you can run the following command.

cat file_to_sign | didctl sign dev

The output produced will be a valid JSON-LD document containing the signature details.

{
  "@context": [
    "https://w3id.org/security/v1"
  ],
  "type": "Ed25519Signature2018",
  "creator": "did:bryk:4d81bd52-2edb-4703-b8fc-b26d514a9c56#master",
  "created": "2019-03-15T14:05:54Z",
  "domain": "did.bryk.io",
  "nonce": "f14d4619a39f7deb5a382bf32b220726",
  "signatureValue": "khqsBcnCViYm/3QFjgAQX2iOGDbNpsD5rPWsokWNLsBxhtRf79A+qV1f+9sphjVCxNP02jesOOni3t9zMCZbBw=="
}

You can save and share the produced JSON output. Other users will be able to verify the integrity and authenticity of the signature using the verify command.

cat file_to_sign | didctl verify signature.json

The CLI will inspect the signature file, retrieve the DID Document for the creator and use the public key to verify the integrity and authenticity of the signature.

[Mar 15 10:10:22.286]  INFO verifying LD signature
[Mar 15 10:10:22.286] DEBUG load signature file
[Mar 15 10:10:22.286] DEBUG decoding contents
[Mar 15 10:10:22.286] DEBUG validating signature creator
[Mar 15 10:10:22.287]  INFO establishing connection to the network with node: rpc-did.bryk.io:80
[Mar 15 10:10:22.458] DEBUG retrieving record
[Mar 15 10:10:22.471] DEBUG decoding contents
[Mar 15 10:10:22.973]  INFO signature is valid
4.2.3 Service Management

As mentioned in earlier sections, one of the more relevant aspects of a DID Document is its capability to list interaction mechanisms available for a particular subject. This is done by including information of Service Endpoints in the document. Using the CLI client you can manage the services enabled for any of your identifiers.

Manage services enabled for the identifier

Usage:
  didctl edit service [command]

Available Commands:
  add         Register a new service entry for the DID
  remove      Remove an existing service entry for the DID

Flags:
  -h, --help   help for service

Global Flags:
      --config string   config file ($HOME/.didctl/config.yaml)
      --home string     home directory ($HOME/.didctl)

Use "didctl edit service [command] --help" for more information about a command.

To add a new service you can use the did service add command.

Register a new service entry for the DID

Usage:
  didctl edit service add [flags]

Examples:
didctl edit service add [DID reference name] --name "service name" --endpoint https://www.agency.com/user_id

Flags:
      --endpoint string   main URL to access the service
  -h, --help              help for add
      --name string       service's reference name (default "external-service-#")
      --type string       type identifier for the service handler (default "identity.bryk.io.ExternalService")

It will produce and properly add a service endpoint entry. The cryptographic integrity proof on the DID Document will also be updated accordingly.

{
  "id": "did:bryk:99dc4a30-7434-42e5-ac75-5f330be0ea0a;iadb-bonds",
  "type": "identity.bryk.io.ExternalService",
  "serviceEndpoint": "https://www.iadb.org/bonds"
}

You can also safely remove a service from your identifier using the edit service remove command.

edit service remove [DID reference name] [service name]

5. Cryptography Notice

This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.

The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.

Directories

Path Synopsis
Package agent provides a reference implementation for a DID network management process.
Package agent provides a reference implementation for a DID network management process.
storage
Package storage includes sample implementations of different store mechanisms.
Package storage includes sample implementations of different store mechanisms.
client
cli
Package main provides the Command Line Interface application "didctl".
Package main provides the Command Line Interface application "didctl".
cli/cmd
Package cmd provides a CLI application to manage DIDs.
Package cmd provides a CLI application to manage DIDs.
internal
Package internal provide private utilities for the CLI didctl application.
Package internal provide private utilities for the CLI didctl application.
store
Package store provides a sample storage handler based on local-disk.
Package store provides a sample storage handler based on local-disk.
Package info provides global parameters for the application.
Package info provides global parameters for the application.
proto
did/v1
Package didv1 provides the version 1.0 of the protocol buffers definitions for the project.
Package didv1 provides the version 1.0 of the protocol buffers definitions for the project.
Package resolver introduces a simple interface for interoperability with other DID methods.
Package resolver introduces a simple interface for interoperability with other DID methods.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL