# @digitalbazaar/bls12-381-multikey

> Javascript library for generating and working with BLS12-381 (BBS) key pairs.

Latest version **2.2.0** (published 2026-05-25) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install @digitalbazaar/bls12-381-multikey
pnpm add @digitalbazaar/bls12-381-multikey
yarn add @digitalbazaar/bls12-381-multikey
bun add @digitalbazaar/bls12-381-multikey
```

## Health

**Score 50/100 (C)** — status: active.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2026-05-25 |
| First published | 2024-01-11 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | none |
| Module format | ESM |
| Node | >=22 |
| Dependencies | 5 |
| Unpacked size | 29.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Maintainers | dlongley, msporny, davidlehn, gannan |

## Links

- npm: https://www.npmjs.com/package/@digitalbazaar/bls12-381-multikey
- Repository: https://github.com/digitalbazaar/bls12-381-multikey
- Issues: https://github.com/digitalbazaar/bls12-381-multikey/issues
- npm.io page: https://npm.io/package/@digitalbazaar/bls12-381-multikey

## Dependencies (5)

- [cborg](https://npm.io/package/cborg.md) ^5.1.1
- [@noble/curves](https://npm.io/package/@noble/curves.md) ^2.2.0
- [base58-universal](https://npm.io/package/base58-universal.md) ^2.0.0
- [base64url-universal](https://npm.io/package/base64url-universal.md) ^2.0.0
- [@digitalbazaar/bbs-signatures](https://npm.io/package/@digitalbazaar/bbs-signatures.md) ^3.0.0

## Recent versions

- 2.2.0 (latest) — 2026-05-25
- 2.1.0 — 2024-10-02
- 2.0.0 — 2024-08-19
- 1.3.0 — 2024-04-11
- 1.2.0 — 2024-03-18
- 1.1.1 — 2024-01-12
- 1.1.0 — 2024-01-12
- 1.0.0 — 2024-01-11

## README

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

[![Node.js CI](https://github.com/digitalbazaar/bls12-381-multikey/workflows/Node.js%20CI/badge.svg)](https://github.com/digitalbazaar/bls12-381-multikey/actions?query=workflow%3A%22Node.js+CI%22)
[![NPM Version](https://img.shields.io/npm/v/@digitalbazaar/bls12-381-multikey.svg)](https://npm.im/@digitalbazaar/bls12-381-multikey)

> JavaScript library for using Bls12381Multikey key pairs with BBS

## Table of Contents

- [Background](#background)
- [Security](#security)
- [Install](#install)
- [Usage](#usage)
- [Contribute](#contribute)
- [Commercial Support](#commercial-support)
- [License](#license)

## Background

For use with:

* [`@digitalbazaar/bbs-2023-cryptosuite`](https://github.com/digitalbazaar/bbs-2023-cryptosuite) `^1.0.0`
  crypto suite (with [`jsonld-signatures`](https://github.com/digitalbazaar/jsonld-signatures) `^11.2.0`)
* [`@digitalbazaar/data-integrity`](https://github.com/digitalbazaar/data-integrity) `^2.0.0`

See also (related specs):

* [Verifiable Credential Data Integrity](https://w3c.github.io/vc-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

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

```js
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()`:

```js
const serializedKeyPair = { ... };

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

### Exporting the public key only

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'
}
```

### 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):

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

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

### Deriving a BBS proof from a BBS signature

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

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

```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](https://github.com/digitalbazaar/bedrock/blob/master/CONTRIBUTING.md)!

PRs accepted.

If editing the Readme, please conform to the
[standard-readme](https://github.com/RichardLitt/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)](LICENSE) © 2023 Digital Bazaar

---
_Source: https://npm.io/package/@digitalbazaar/bls12-381-multikey · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._