A JavaScript WebKMS client library.
See also related specs:
TBD
- Browsers and Node.js 18+ are supported.
- Web Crypto API required. Older browsers must use a polyfill.
To install via NPM:
npm install @digitalbazaar/webkms-client
To install locally (for development):
git clone https://github.com/digitalbazaar/webkms-client.git
cd webkms-client
npm install
- webkms
WebKMS client for Javascript.
- webkms:generateKey(options) ⇒
Promise.<object>
Generates a new cryptographic key in the keystore.
- webkms:getKeyDescription(options) ⇒
Promise.<object>
Gets the key description for the given key ID.
- webkms:revokeCapability(options) ⇒
Promise.<object>
Store a capability revocation.
- webkms:wrapKey(options) ⇒
Promise.<Uint8Array>
Wraps a cryptographic key using a key encryption key (KEK).
- webkms:unwrapKey(options) ⇒
Promise.<(Uint8Array|null)>
Unwraps a cryptographic key using a key encryption key (KEK).
- 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.
- 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.
- 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.
- webkms:createKeystore(options) ⇒
Promise.<object>
Creates a new keystore using the given configuration.
- webkms:getKeystore(options) ⇒
Promise.<object>
Gets the configuration for a keystore by its ID.
WebKMS client for Javascript.
A WebKMS Client used to interface with a KMS.
Kind: instance class of webkms
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
See the contribute file!
PRs accepted.
If editing the Readme, please conform to the standard-readme specification.
Commercial support for this library is available upon request from Digital Bazaar: [email protected]
New BSD License (3-clause) © Digital Bazaar