Javascript library for generating and working with BLS12-381 (BBS) key pairs.
npm install @digitalbazaar/bls12-381-multikey

> JavaScript library for using Bls12381Multikey key pairs with BBS
- Background
- Security
- Install
- Usage
- Contribute
- Commercial Support
- License
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
As with most security- and cryptography-related tools, the overall security of
your system will largely depend on your design decisions.
- 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
To generate a new public/secret key pair for use with BBS signatures:
* {string} [algorithm] \[Required\] Algorithm to be used with the key pair:{string} [id]
\['BBS-BLS12-381-SHA-256'\].
* \[Optional\] ID for the generated key.{string} [controller]
* \[Optional\] Controller URI or DID to initialize theid
generated key. (This will be used to generate 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
});
`
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);
``
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'
}
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'
}
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});
`
Derive a proof from a BBS signature as a holder / prover.
`jssecretKey
// no needs to be present on keyPair to derive a proof, onlypublicKey
// the is required
// pass original signer's publicKey, signature, header, and messagespresentationHeader
// as well as a custom and any disclosedMessageIndexesproof
const proof = await keyPair.deriveProof({
signature, header, messages,
presentationHeader: new Uint8Array(),
disclosedMessageIndexes: [1]
});
// is a Uint8Array containing a BBS proof`
In order to verify a BBS proof, you need to create a verifier instancemultiverify()
and call 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``
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: support@digitalbazaar.com
New BSD License (3-clause) © 2023 Digital Bazaar