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


> JavaScript library for using Bls12381Multikey key pairs with BBS

Table of Contents

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

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

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

$3

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

`js
import * as Bls12381Multikey from '@digitalbazaar/bls12-381-multikey';

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

$3

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

`js
const serializedKeyPair = { ... };

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

$3

To export just the public key of a pair:

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

$3

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

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

$3

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

`js
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});
`

$3

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

`js
// 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
`

$3

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

`js
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
``

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