@digitalbazaar/webkms-client NPM

WebKMS Client (@digitalbazaar/webkms-client)

A JavaScript WebKMS client library.

Background

Security

TBD

Install

Browsers and Node.js 18+ are supported.
Web Crypto API required. Older browsers must use a polyfill.

NPM

To install via NPM:

npm install @digitalbazaar/webkms-client

Development

To install locally (for development):

git clone https://github.com/digitalbazaar/webkms-client.git
cd webkms-client
npm install

Usage

Modules

Functions

webkms

WebKMS client for Javascript.

webkms
- .KmsClient
  - new exports.KmsClient(options)

webkms.KmsClient

A WebKMS Client used to interface with a KMS.

Kind: instance class of webkms

new exports.KmsClient(options)

Creates a new KmsClient.

Returns: KmsClient - The new instance.

Param	Type	Description
options	object	The options to use.
options.keystore	string	The ID of the keystore that must be a URL that refers to the keystore's root storage location; if not given, then a separate capability must be given to each method called on the client instance.
options.httpsAgent	object	An optional node.js `https.Agent` instance to use when making requests.

webkms:generateKey(options) ⇒ Promise.<object>

Generates a new cryptographic key in the keystore.

Kind: global function Returns: Promise.<object> - The key description for the key.

Param	Type	Description
options	object	The options to use.
options.kmsModule	string	The KMS module to use.
options.type	string	The key type (e.g. 'AesKeyWrappingKey2019').
options.capability	string	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	object	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:getKeyDescription(options) ⇒ Promise.<object>

Gets the key description for the given key ID.

Kind: global function Returns: Promise.<object> - The key description.

Param	Type	Description
options	object	The options to use.
options.keyId	string	The ID of the key.
options.capability	string	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	object	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:revokeCapability(options) ⇒ Promise.<object>

Store a capability revocation.

Kind: global function Returns: Promise.<object> - Resolves once the operation completes.

Param	Type	Description
options	object	The options to use.
options.capabilityToRevoke	object	The capability to revoke.
options.capability	string	The zcap authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	object	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:wrapKey(options) ⇒ Promise.<Uint8Array>

Wraps a cryptographic key using a key encryption key (KEK).

Kind: global function Returns: Promise.<Uint8Array> - The wrapped key bytes.

Param	Type	Description
options	object	The options to use.
options.kekId	string	The ID of the wrapping key to use.
options.unwrappedKey	Uint8Array	The unwrapped key material as a Uint8Array.
options.capability	string	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	object	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:unwrapKey(options) ⇒ Promise.<(Uint8Array|null)>

Unwraps a cryptographic key using a key encryption key (KEK).

Kind: global function Returns: Promise.<(Uint8Array|null)> - Resolves to the unwrapped key material or null if the unwrapping failed because the key did not match.

Param	Type	Description
options	object	The options to use.
options.kekId	string	The ID of the unwrapping key to use.
options.wrappedKey	string	The wrapped key material as a base64url-encoded string.
options.capability	string	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	object	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:sign(options) ⇒ Promise.<Uint8Array>

Signs some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.

Kind: global function Returns: Promise.<Uint8Array> - The signature.

Param	Type	Description
options	object	The options to use.
options.keyId	string	The ID of the signing key to use.
options.data	Uint8Array	The data to sign as a Uint8Array.
options.capability	string	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	object	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:verify(options) ⇒ Promise.<boolean>

Verifies some data. Note that the data will be sent to the server, so if this data is intended to be secret it should be hashed first. However, hashing the data first may present interoperability issues so choose wisely.

Kind: global function Returns: Promise.<boolean> - true if verified, false if not.

Param	Type	Description
options	object	The options to use.
options.keyId	string	The ID of the signing key to use.
options.data	Uint8Array	The data to verify as a Uint8Array.
options.signature	string	The base64url-encoded signature to verify.
options.capability	string	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	object	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:deriveSecret(options) ⇒ Promise.<Uint8Array>

Derives a shared secret via the given peer public key, typically for use as one parameter for computing a shared key. It should not be used as a shared key itself, but rather input into a key derivation function (KDF) to produce a shared key.

Kind: global function Returns: Promise.<Uint8Array> - The shared secret bytes.

Param	Type	Description
options	object	The options to use.
options.keyId	string	The ID of the key agreement key to use.
options.publicKey	object	The public key to compute the shared secret against; the public key type must match the key agreement key's type.
options.capability	string	The authorization capability to use to authorize the invocation of this operation.
options.invocationSigner	object	An API with an `id` property and a `sign` function for signing a capability invocation.

webkms:createKeystore(options) ⇒ Promise.<object>

Creates a new keystore using the given configuration.

Kind: global function Returns: Promise.<object> - Resolves to the configuration for the newly created keystore.

Param	Type	Description
options	object	The options to use.
options.url	string	The url to post the configuration to.
options.config	string	The keystore's configuration.
options.httpsAgent	object	An optional node.js `https.Agent` instance to use when making requests.

webkms:getKeystore(options) ⇒ Promise.<object>

Gets the configuration for a keystore by its ID.

Kind: global function Returns: Promise.<object> - Resolves to the configuration for the keystore.

Param	Type	Description
options	object	The options to use.
options.id	string	The keystore's ID.
options.httpsAgent	object	An optional node.js `https.Agent` instance to use when making requests.

webkms:findKeystore(options) ⇒ Promise.<object>

Finds the configuration for a keystore by its controller and reference ID.

Kind: global function Returns: Promise.<object> - Resolves to the configuration for the keystore.

Param	Type	Description
options	object	The options to use.
options.url	string	The url to query.
options.controller	string	The keystore's controller.
options.httpsAgent	object	An optional node.js `https.Agent` instance to use when making requests.