SpruceID

Command Line Interface

At a Glance

  • For setting up an HTTP server, whether for internal use, over the open internet, or both, we recommend using our dockerized HTTP server. Instructions below.

  • Instructions for building manually can be found on the main Installation page.

  • See the Examples section below for automation and testing building blocks.

Installation

Docker

The HTTP server is containerised and available under ghcr.io/spruceid/didkit-cli.

You can use the Docker image as a CLI:

docker run ghcr.io/spruceid/didkit-cli:latest --help

Note: You can pass JWKs either by sharing a volume with:

docker run --volume

or by passing the JWK directly with:

docker run -e JWK=$MY_JWK or docker run didkit-http --jwk $MY_JWK.

See the repo's Dockerfile for further details.

Syntax

Each command is called in the form: didkit help, didkit generate-ed25519-key, etc.

help

Output help about didkit and its subcommands.

generate-ed25519-key

Generate a Ed25519 keypair and output it in JWK format.

key-to-did

Given a JWK, output the corresponding did:key. Currently, this only supports Ed25519 keys.

key-to-verification-method

Given a Ed25519 JWK, output the corresponding did:key verificationMethod.

Options

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

  • -j, --jwk <jwk> (required, conflicts with key-path): JWK.

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 /issue/credentials 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

Options besides --key-path correspond to linked data proof options as specified in ld-proofs and vc-http-api.

  • -C, --challenge <challenge> - challenge property of the proof

  • -c, --created <created> - created property of the proof. ISO8601 datetime. Defaults to the current time.

  • -d, --domain <domain> - domain property of the proof

  • -k, --key-path <key> (required, conflicts with jwk): Filename of JWK for signing.

  • -j, --jwk <jwk> (required, conflicts with key-path): JWK for signing.

  • -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)

vc-verify-credential

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

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

Options

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.

  • -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

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.

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 /prove/presentations in vc-http-api.

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

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 /verify/presentations in vc-http-api.

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

Addition configuration

Outbound Proxy

You can set the environment variable HTTP_PROXY to have DIDKit use a proxy. Both HTTP and SOCKS protocols are supported. See the "proxies" section of the DIDKit docs for more details.

Examples

PreviousDIDKit PackagesNextHTTP Server

Last updated