@digitalbazaar/bls12-381-multikey NPM

Bls12381Multikey Key Pair Library (@digitalbazaar/bls12-381-multikey)

JavaScript library for using Bls12381Multikey key pairs with BBS

Background

For use with:

@digitalbazaar/bbs-2023-cryptosuite ^1.0.0 crypto suite (with jsonld-signatures ^11.2.0)
@digitalbazaar/data-integrity ^2.0.0

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 18+ is required.

To install locally (for development):

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

Usage

Generating a new public/secret key pair for use with BBS signatures

To generate a new public/secret key pair for use with BBS signatures:

{string} [algorithm] [Required] Algorithm to be used with the key pair: ['BBS-BLS12-381-SHA-256'].
{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 Bls12381Multikey from '@digitalbazaar/bls12-381-multikey';

const keyPair = await Bls12381Multikey.generateBbsKeyPair({
  algorithm: Bls12381Multikey.ALGORITHMS.BBS_BLS12381_SHA256
});

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 Bls12381Multikey.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#zUC7GMwWWkA5UMTx7Gg6sabmpchWgq8p1xGhUXwBiDytY8BgD6eq5AmxNgjwDbAz8Rq6VFBLdNjvXR4ydEdwDEN9L4vGFfLkxs8UsU3wQj9HQGjQb7LHWdRNJv3J1kGoA3BvnBv',
  controller: 'did:example:1234',
  publicKeyMultibase: 'zUC7GMwWWkA5UMTx7Gg6sabmpchWgq8p1xGhUXwBiDytY8BgD6eq5AmxNgjwDbAz8Rq6VFBLdNjvXR4ydEdwDEN9L4vGFfLkxs8UsU3wQj9HQGjQb7LHWdRNJv3J1kGoA3BvnBv'
}

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#zUC7GMwWWkA5UMTx7Gg6sabmpchWgq8p1xGhUXwBiDytY8BgD6eq5AmxNgjwDbAz8Rq6VFBLdNjvXR4ydEdwDEN9L4vGFfLkxs8UsU3wQj9HQGjQb7LHWdRNJv3J1kGoA3BvnBv',
  controller: 'did:example:1234',
  publicKeyMultibase: 'zUC7GMwWWkA5UMTx7Gg6sabmpchWgq8p1xGhUXwBiDytY8BgD6eq5AmxNgjwDbAz8Rq6VFBLdNjvXR4ydEdwDEN9L4vGFfLkxs8UsU3wQj9HQGjQb7LHWdRNJv3J1kGoA3BvnBv',
  secretKeyMultibase: 'z488vexJQSQ2rF5GrCT8qhzGR7ASSj5rx6CtZjKNFq183woF'
}

Creating a BBS signature using a signer

In order to perform a cryptographic signature, you need to create a signer instance and call multisign() on it.

const keyPair = Bls12381Multikey.generateBbsKeyPair({
  algorithm: 'BBS-BLS12-381-SHA-256'
});

const signer = keyPair.signer();

// header is a Uint8Array
const header = new Uint8Array();
// message is an array of Uint8Arrays
const messages = [new TextEncoder().encode('test data goes here')];
// creates a BBS signature over the messages expressed in a Uint8Array
const signature = await signer.multisign({header, messages});

Deriving a BBS proof from a BBS signature

Derive a proof from a BBS signature as a holder / prover.

// no `secretKey` needs to be present on `keyPair` to derive a proof, only
// the `publicKey` is required

// pass original signer's `publicKey`, `signature`, `header`, and `messages`
// as well as a custom `presentationHeader` and any `disclosedMessageIndexes`
const proof = await keyPair.deriveProof({
  signature, header, messages,
  presentationHeader: new Uint8Array(),
  disclosedMessageIndexes: [1]
});
// `proof` is a `Uint8Array` containing a BBS proof

Verifying a BBS proof using a verifier

In order to verify a BBS proof, you need to create a verifier instance and call multiverify() on it.

const verifier = keyPair.verifier();

const verified = await verifier.multiverify({
  proof, header,
  presentationHeader,
  // leave holes for messages that were not disclosed
  messages: [undefined, messages[1]]
});
// returns `true` or `false`