Skip to content

Commit

Permalink
Document new didkit subcommands
Browse files Browse the repository at this point in the history
  • Loading branch information
@clehner
clehner committed Feb 16, 2022
1 parent b19892c commit 7e2190d
Showing 1 changed file with 153 additions and 0 deletions.
153 changes: 153 additions & 0 deletions cli/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -195,10 +195,153 @@ If the `-m` option is used, a JSON array is returned containing the following th

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`][didDocumentOperation] values in DIF DID registration and/or [DID State Patches][did-state-patches] in Sidetree.

- [`set-service`](#didkit-did-update-set-service-id)
- [`set-verification-method`](#didkit-did-update-set-verification-method-id)
- [`remove-service`](#didkit-did-update-remove-service-id)
- [`remove-verification-method`](#didkit-did-update-remove-verification-method-id)

#### 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][services] in a DID document.

The identified service object is created if it is 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][verification-methods] 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][verification-relationships] (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](https://www.w3.org/TR/did-core/#assertion)
- `-U, --authentication`- [Authentication](https://www.w3.org/TR/did-core/#authentication)
- `-D, --capabilityDelegation`- [Capability Delegation](https://www.w3.org/TR/did-core/#capability-delegation)
- `-I, --capabilityInvocation` - [Capability Invocation](https://www.w3.org/TR/did-core/#capability-invocation)
- `-K, --keyAgreement` - [keyAgreement](https://www.w3.org/TR/did-core/#key-agreement)

##### 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](https://w3c-ccg.github.io/security-vocab/#blockchainAccountId) (CAIP-10) value

### `didkit did-update remove-service <id>`

Construct a [DID method transaction][] to remove a [service][services] 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][verification-methods] 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][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](#didkit-did-create-did-method), [update](#didkit-did-update-subcommand), [recover](#didkit-did-recover-did), [deactivate](#didkit-did-deactivate-did)) 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][method-operations]. The transaction can be submitted, published, and/or fully performed, per the DID method, using the [did-submit-tx](#didkit-did-submit-tx-did) subcommand.

## Examples

See the included [shell script](tests/example.sh).

See also the following shell scripts demonstrating create, update, recover and deactivate operations:
- [create and update service](tests/ion-create-update-svc.sh)
- [create and update verification method](tests/ion-create-update-vm.sh)
- [create and recover](tests/ion-create-recover.sh)
- [create and deactivate](tests/ion-create-deactivate.sh)

[ssi]: https://github.com/spruceid/ssi
[JWK]: https://tools.ietf.org/html/rfc7517
[ld-proofs]: https://w3c-ccg.github.io/ld-proofs/
[vc-http-api]: https://w3c-ccg.github.io/vc-http-api/
Expand Down Expand Up @@ -234,3 +377,13 @@ See the included [shell script](tests/example.sh).
[did-url-dereferencing-metadata]: https://w3c.github.io/did-core/#did-url-dereferencing-metadata-properties
[did-url-dereferencing-input-metadata]: https://w3c.github.io/did-core/#did-url-dereferencing-input-metadata-properties
[did-resolution-https-binding]: https://w3c-ccg.github.io/did-resolution/#bindings-https
[method-operations]: https://www.w3.org/TR/did-core/#method-operations
[did-recovery]: https://www.w3.org/TR/did-core/#did-recovery
[verification-methods]: https://www.w3.org/TR/did-core/#verification-methods
[verification-relationships]: https://www.w3.org/TR/did-core/#verification-relationships
[services]: https://www.w3.org/TR/did-core/#services
[publicKeyJwk]: https://www.w3.org/TR/did-core/#dfn-publickeyjwk
[publicKeyMultibase]: https://www.w3.org/TR/did-core/#dfn-publickeymultibase
[DID method transaction]: #did-method-transaction
[didDocumentOperation]: https://identity.foundation/did-registration/#diddocumentoperation
[did-state-patches]: https://identity.foundation/sidetree/spec/v1.0.0/#did-state-patches

0 comments on commit 7e2190d

Please sign in to comment.