DIDKit CLI

DIDKit offers its functionality in a command-line program, didkit.

Build

$ cargo build

Install

$ cargo install --path .

Commands

didkit help

Output help about didkit and its subcommands.

didkit generate-ed25519-key

Generate a Ed25519 keypair and output it in JWK format.

didkit key-to-did <method_pattern>

Given a JWK and a supported DID method name or pattern, output the corresponding DID.

didkit key-to-verification-method <method_pattern>

Given a JWK and a supported DID method name or pattern, output the corresponding verificationMethod.

Options

• -k, --key-path <file> (required, conflicts with jwk) - Filename of JWK file
• -j, --jwk <jwk> (required, conflicts with key-path) - JWK.

Supported DID method names and patterns

• key - did:key (Ed25519, P-256 Secp256k1)
• tz - did:tz (Ed25519, P-256 Secp256k1)
• ethr - did:ethr (Secp256k1)
• sol - did:sol (Ed25519)
• pkh:[…] - did:pkh (Ed25519, P-256 Secp256k1)

didkit vc-issue-credential

Issue a verifiable credential. Reads credential on stdin, constructs a linked data proof to add to the credential, and outputs the resulting verifiable credential.

Corresponds to /credentials/issue in vc-http-api.

The proof type is set automatically based on the key file provided. JWK parameters besides the cryptographic components, such as kid (Key ID), are ignored currently. For an RSA key, the alg (Algorithm) parameter is ignored and RS256 is used for it, for RsaSignature2018.

Options

• -r, --did-resolver <url> - DID resolver HTTP(S) endpoint, used for DID resolution and DID URL dereferencing for non-built-in DID Methods. Equivalent to environmental variable DID_RESOLVER.
• -R, --did-resolver-override <url> - DID resolver HTTP(S) endpoint, used for DID resolution and DID URL dereferencing for all DID Methods. Equivalent to environmental variable DID_RESOLVER_OVERRIDE.
• -k, --key-path <file> - Filename of JWK file for signing. Conflicts with -j.
• -j, --jwk <jwk> - JWK for signing. Conflicts with -k.
• -S, --ssh-agent - Use SSH agent for signing instead of JWK private key. See the section on SSH Agent below for more info.

One of -k (--key-path), -j (--jwk) or -S (--ssh-agent) is required.

The following options correspond to linked data proof options as specified in ld-proofs and vc-http-api:

• -t, --type <type> - type of proof object to create.
• -C, --challenge <challenge> - challenge property of the proof
• -c, --created <created> - created property of the proof. ISO8601 datetime. Defaults to the current time. time.
• -d, --domain <domain> - domain property of the proof
• -p, --proof-purpose <proof-purpose> proofPurpose property of the proof.
• -v, --verification-method <verification-method> verificationMethod property of the proof. URI for proof verification information, e.g. a public key identifier.

Supported JWK key types

• RSA
• OKP (curve: Ed25519)

SSH Agent

DIDKit can use SSH Agent for signing, as an alternative to signing with a JWK private key. If the -S (--ssh-agent) CLI option is used, DIDKit will attempt to connect to a local instance of ssh-agent, via the UNIX socket referred to by environmental variable SSH_AUTH_SOCK, following the SSH Agent Protocol.

Key selection

When -S (--ssh-agent) is used, the JWK referred to by -k (--key-file) or -j (--jwk) is treated as a public key and used to select which key from SSH Agent to use for signing. If no JWK option is used, then the SSH Agent is expected to have only one key, and that key is used for signing.

didkit vc-verify-credential

Verify a verifiable credential. Reads verifiable credential on standard input, and outputs verification result. Returns exit status zero if credential successfully verified, or non-zero if errors were encountered.

Corresponds to /credentials/verify in vc-http-api.

Options

• -r, --did-resolver <url> - DID resolver HTTP(S) endpoint, used for DID resolution and DID URL dereferencing for non-built-in DID Methods. Equivalent to environmental variable DID_RESOLVER.
• -R, --did-resolver-override <url> - DID resolver HTTP(S) endpoint, used for DID resolution and DID URL dereferencing for all DID Methods. Equivalent to environmental variable DID_RESOLVER_OVERRIDE.

The following options are linked data proof options as specified in ld-proofs and vc-http-api. If there is more than one proof present, at least one must pass all the requirements passed in the options.

• -C, --challenge <challenge> - The challenge property of the proof must equal this value.
• -c, --created <created> - The created property of the proof must be on or after the given ISO8601 datetime. Defaults to the current time. time.
• -d, --domain <domain> - The domain property of the proof must equal the given value.
• -p, --proof-purpose <proof-purpose> - The proofPurpose property of the proof must equal this value.
• -v, --verification-method <verification-method> - The verificationMethod property of the proof must equal this value.

Supported proof types

• RsaSignature2018
• Ed25519VerificationKey2018

Output

The verification result output is a VerificationResult JSON object as specified in vc-http-api:

{
  "checks": [],
  "warnings": [],
  "errors": []
}

Verification result properties:

• checks - Array of strings indicating checks completed on the credential.
• warnings - Array of warnings encountered during validation or verification.
• errors - Array of strings indicating errors encountered during validation or verification. If errors is empty, the credential is verified.

didkit vc-issue-presentation

Issue a verifiable presentation. Reads presentation on stdin, generates proof to add to it, and outputs the resulting verifiable presentation.

Corresponds to /presentations/prove in vc-http-api.

Options are the same as for didkit vc-issue-credential.

didkit vc-verify-presentation

Verify a verifiable presentation. Reads verifiable presentation on stdin, and outputs verification result. Returns exit status zero if presentation successfully verified, or non-zero if errors were encountered.

Corresponds to /presentations/verify in vc-http-api.

Options and output format are the same as for didkit vc-verify-credential.

didkit did-resolve <did>

Resolve a DID to a DID document, according to DID Resolution.

Options

• -m, --with-metadata - Return the resolved DID document with resolution metadata and document metadata, in a DID Resolution Result object.
• -i <name=value> - A DID Resolution input metadata property. If = is omitted, boolean true is used as the value, otherwise, value is a string. May be repeated to add multiple properties. If used multiple times with the same name, the values are combined into an array value to form a single property.
• -r, --did-resolver <url> - DID resolver HTTP(S) endpoint, used for DID resolution and DID URL dereferencing for non-built-in DID Methods. Equivalent to environmental variable DID_RESOLVER.
• -R, --did-resolver-override <url> - DID resolver HTTP(S) endpoint, used for DID resolution and DID URL dereferencing for all DID Methods. Equivalent to environmental variable DID_RESOLVER_OVERRIDE.

Output

Returns the resolved DID document, optionally with metadata.

Without the -m option, a representation of the resolved DID document is returned, without document metadata or resolution metadata.

If the -m option is used, a DID Resolution Result is returned, which is a JSON object containing the following properties:

• didDocument - the resolved DID document
• didResolutionMetadata - DID resolution metadata
• didDocumentMetadata - DID document metadata
• @context - JSON-LD context, if using JSON-LD representation.

Exit status is zero on success, and nonzero on failure. On failure, a DID Resolution Result object may still be returned on standard output if the -m option is used, where the error property of the DID resolution metadata object is set to the error message. If -m is not used, the error message is returned on standard error.

didkit did-dereference <did-url>

Dereference a DID URL to a resource, as in did-core - DID URL Dereferencing.

Options

• -m, --with-metadata - Return the resulting resource with resolution metadata and document metadata, in a DID Resolution Result object.
• -i <name=value> - A DID URL Dereferencing input metadata property. If = is omitted, boolean true is used as the value, otherwise, value is a string. May be repeated to add multiple properties. If used multiple times with the same name, the values are combined into an array value to form a single property.
• -r, --did-resolver <url> - DID resolver HTTP(S) endpoint, used for DID resolution and DID URL dereferencing for non-built-in DID Methods. Equivalent to environmental variable DID_RESOLVER.
• -R, --did-resolver-override <url> - DID resolver HTTP(S) endpoint, used for DID resolution and DID URL dereferencing for all DID Methods. Equivalent to environmental variable DID_RESOLVER_OVERRIDE.

Output

Returns the resource dereferenced from the DID URL, optionally with metadata.

Without the -m option, the content resulting from dereferencing is returned, without content metadata or dereferencing metadata.

If the -m option is used, a JSON array is returned containing the following three objects:

• The resolved DID document or other resource corresponding to the dereferenced DID URL
• DID dereferencing metadata or DID resolution metadata
• Content metadata or DID document metadata

Exit status is zero on success and nonzero on error. On error, if -m is used, the error message is returned in the error property of the DID dereferencing metadata object on standard output; if -m is not used, the error is printed on standard error.

didkit did-create <did-method>

Construct a DID method transaction to create a DID with a given DID method.

Options

• -o <name=value> - Options for DID Create operation.
• -r, --recovery-key <file> - JWK file for DID recovery and/or deactivation purposes, as used in Sidetree DID methods (e.g. did:ion).
• -u, --update-key <file> - JWK file for DID update operations, as used in Sidetree DID Methods (e.g. did:ion).
• -v, --verification-key <file> - JWK file for default verification method

Output

A DID method transaction for a DID Create operation.

didkit did-update <subcommand>

Construct a DID method transaction to update a DID.

Options

• -o <name=value> - Options for DID Update operation.
• -u, --new-update-key <file> - New JWK file for next DID update operations, as used in Sidetree DID Methods (e.g. did:ion).
• -U, --update-key <file> - JWK file for performing this DID update operation

Subcommands

Updates to a DID document may be done using these did-update subcommands. These correspond roughly to didDocumentOperation values in DIF DID registration and/or DID State Patches in Sidetree.

• set-service
• set-verification-method
• remove-service
• remove-verification-method

Output

A DID method transaction for a DID Update operation.

didkit did-update set-service <id>

Construct a DID method transaction to add or modify a service in a DID document.

The identified service object is created if it exists, or reset if it does not exist, to contain the properties corresponding to the options passed, i.e. the type and serviceEndpoint properties.

Options

• -d, --did <did> - DID whose DID document to update. Default: implied from <id>
• -t, --type <type>... - Service type
• -e, --endpoint <endpoint>... - serviceEndpoint URI or JSON object

didkit did-update set-verification-method <id>

Construct a DID method transaction to add or modify a verification method in a DID document.

The identified verification method is created if it does not exist, or reset if it already exists. The verification method is constructed to contain properties as passed in the options.

Options

• -c, --controller <did> - Verification method controller property
• -d, --did <did> - DID whose DID document to update. Default: implied from <id>
• -t, --type <type> - Verification method type (required)

Verification relationship options

At least one verification relationship (proof purpose) must be provided. Each of these options creates the respective verification relationship in the DID document for the verification method object.

• -S, --assertionMethod - Assertion
• -U, --authentication- Authentication
• -D, --capabilityDelegation- Capability Delegation
• -I, --capabilityInvocation - Capability Invocation
• -K, --keyAgreement - keyAgreement

Public key options

Exactly one public key property must be provided. Which properties are allowed depends on the verification method type.

• -j, --publicKeyJwk <JWK> - publicKeyJwk value
• -k, --publicKeyJwkPath <filename> - publicKeyJwk value read from file
• -m, --publicKeyMultibase <string> - Multibase-encoded public key (publicKeyMultibase value)
• -b, --blockchainAccountId <account> - blockchainAccountId (CAIP-10) value

didkit did-update remove-service <id>

Construct a DID method transaction to remove a service from a DID document.

Options

• -d, --did <did> - DID whose DID document to update. Default: implied from <id>

didkit did-update remove-verification-method <id>

Construct a DID method transaction to remove a verification method from a DID document.

Options

• -d, --did <did> - DID whose DID document to update. Default: implied from <id>

didkit did-recover <did>

Construct a DID method transaction to perform a DID recover operation (DID recovery), if supported by the DID method.

Options

• -o <name=value> - Options for DID Recover operation.
• -r, --new-recovery-key <file> - New JWK file for DID recovery and/or deactivation purposes, as used in Sidetree DID methods (e.g. did:ion).
• -u, --new-update-key <file> - New JWK file for next DID update operation, as used in Sidetree DID Methods (e.g. did:ion).
• -v, --new-verification-key <file> - New JWK file for default verification method
• -R, --recovery-key <file> - JWK file for performing this DID recover operation

Output

A DID method transaction for a DID Recover operation.

didkit did-deactivate <did>

Construct a DID method transaction to deactivate a DID, if supported by the DID method.

Options

• -k, --key <key> - JWK file to perform the DID Deactivate operation
• -o <name=value> - Options for DID deactivate operation.

Output

A DID method transaction for a DID Deactivate operation.

didkit did-from-tx

Reads a DID method transaction on standard input, and extracts or derives its DID.

Output

The DID corresponding to the input transaction.

didkit did-submit-tx <did>

Reads a DID method transaction on standard input, and submits it in a method-specific way. Returns exit status zero if the transaction was successfully submitted.

Output

A method-specific data structure.

Concepts

DID method transaction

DIDKit's DID method operation commands (create, update, recover, deactivate) do not fully perform the respective operation; instead, they return a data structure representing the partially applied operation, called a DID method transaction. The transaction is a verifiable message created by a DID controller to perform a DID method operation. The transaction can be submitted, published, and/or fully performed, per the DID method, using the did-submit-tx subcommand.

Examples

See the included shell script.

See also the following shell scripts demonstrating create, update, recover and deactivate operations:

• create and update service
• create and update verification method
• create and recover
• create and deactivate