EcdsaMultikey Key Pair Library for Linked Data (@digitalbazaar/ecdsa-multikey)

Javascript library for generating and working with EcdsaMultikey key pairs.

Table of Contents

• Background
• Security
• Install
• Usage
• Contribute
• Commercial Support
• License

Background

For use with:

• @digitalbazaar/ecdsa-2019-cryptosuite ^1.0.0 crypto suite (with jsonld-signatures ^11.0.0)
• @digitalbazaar/data-integrity ^1.0.0

See also (related specs):

• Verifiable Credential Data Integrity

Security

As with most security- and cryptography-related tools, the overall security of your system will largely depend on your design decisions.

Install

• Node.js 16+ is required.

To install locally (for development):

git clone https://github.com/digitalbazaar/ecdsa-multikey.git
cd ecdsa-multikey
npm install

Usage

Generating a new public/secret key pair

To generate a new public/secret key pair:

• {string} [curve] [Required] ECDSA curve used to generate the key: ['P-256', 'P-384', 'P-521'].
• {string} [id] [Optional] ID for the generated key.
• {string} [controller] [Optional] Controller URI or DID to initialize the generated key. (This will be used to generate id if it is not explicitly defined.)

import * as EcdsaMultikey from '@digitalbazaar/ecdsa-multikey';

const keyPair = await EcdsaMultikey.generate({curve: 'P-384'});

Importing a key pair from storage

To create an instance of a public/secret key pair from data imported from storage, use .from():

const serializedKeyPair = { ... };

const keyPair = await EcdsaMultikey.from(serializedKeyPair);
`

Exporting the public key only

To export just the public key of a pair:

await keyPair.export({publicKey: true});
// ->
{
  type: 'Multikey',
  id: 'did:example:1234#zDnaeSMnptAKpH4AD41vTkwzjznW7yNetdRh9FJn8bJsbsdbw',
  controller: 'did:example:1234',
  publicKeyMultibase: 'zDnaeSMnptAKpH4AD41vTkwzjznW7yNetdRh9FJn8bJsbsdbw'
}

Exporting the full public-secret key pair

To export the full key pair, including secret key (warning: this should be a carefully considered operation, best left to dedicated Key Management Systems):

await keyPair.export({publicKey: true, secretKey: true});
// ->
{
  type: 'Multikey',
  id: 'did:example:1234#zDnaeSMnptAKpH4AD41vTkwzjznW7yNetdRh9FJn8bJsbsdbw',
  controller: 'did:example:1234',
  publicKeyMultibase: 'zDnaeSMnptAKpH4AD41vTkwzjznW7yNetdRh9FJn8bJsbsdbw',
  secretKeyMultibase: 'z42twirSb1PULt5Sg6gjgNMsdiLycu6fbA83aX1vVb8e3ncP'
}

Creating a signer function

In order to perform a cryptographic signature, you need to create a sign function, and then invoke it.

const keyPair = EcdsaMultikey.generate({curve: 'P-256'});

const {sign} = keyPair.signer();

// data is a Uint8Array of bytes
const data = (new TextEncoder()).encode('test data goes here');
// Signing also outputs a Uint8Array, which you can serialize to text etc.
const signature = await sign({data});

Creating a verifier function

In order to verify a cryptographic signature, you need to create a verify function, and then invoke it (passing it the data to verify, and the signature).

const keyPair = EcdsaMultikey.generate({curve: 'P-521'});

const {verify} = keyPair.verifier();

const valid = await verify({data, signature});
// true

Contribute

See the contribute file!

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

Commercial Support

Commercial support for this library is available upon request from Digital Bazaar: support@digitalbazaar.com

License

New BSD License (3-clause) © 2023 Digital Bazaar

@digitalbazaar/ecdsa-multikey ChangeLog

1.8.0 - 2024-10-02

Added

• Include id and controller properties when importing key types of JsonWebKey or JsonWebKey2020.

1.7.0 - 2024-03-17

Added

• Add conversion from publicKeyJwk feature via from().

Changed

• Expect >= node 18 via package.json.

Fixed

• Allow @context array values in multikeys.

1.6.0 - 2023-11-07

Added

• Add fromRaw() to import a key pair from a named curve, secretKey, and publicKey.
• Reformat keyAgreement param in from() to options to enable named usage ({keyAgreement: true|false}) for better API.

1.5.0 - 2023-11-05

Added

• Rename remotePublicKey param to publicKey for deriveSecret() to get better compatibility with WebKMS Client KeyAgreementKey interface. The param can still be passed as remotePublicKey but this is considered deprecated.

1.4.0 - 2023-11-05

Added

• Add raw option to key pair export(). Based on the requested public/secret key, the output will include the raw bytes for the public/secret key using the properties publicKey and/or secretKey, respectively. The public key will be output using the compressed format.

1.3.0 - 2023-10-31

Added

• Add keyAgreement option to generate() to generate ECDH keys instead of ECDSA keys. This module needs a better name than ecdsa-multikey as it also supports key agreement keys, but only for keys based on curves that are also compatible with ECDSA. Note that a key should only be used for ECDSA or ECDH (key agreement), not both, so calling this module ecdsa-multikey is a bit misleading as you can also generate a key that is to only be used for key agreement.
• Add deriveSecret() API for keyAgreement enabled keys.

1.2.1 - 2023-10-30

Fixed

• Do not include ext or key_ops in output JWK.

1.2.0 - 2023-10-30

Added

• Add fromJwk() and toJwk() for importing / exporting key pairs using JWK.

1.1.3 - 2023-05-19

Fixed

• Support Node.js 20.x.

1.1.2 - 2023-04-14

Fixed

• Update .from() method to not modify key input.

1.1.1 - 2023-03-11

Fixed

• Fix data format alignment issues with ecdsa-2019-cryptosuite.
• Use constant strings in tests.

1.1.0 - 2023-03-06

Changed

• Ensure public and secret multikey headers match.
• Change exported algorithm from "ECDSA" to curve name.

1.0.0 - 2023-02-27

Added

• Initial version.