# 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