Sign, selectively disclose, and verify credentials/presentations with BBS signatures and JavaScript!
This library is an independent implementation of the bbs-2023 cryptosuite for verifiable credentials. The algorithms and functions are from sections 3 of BBS Cryptosuite v2023: Securing Verifiable Credentials with Selective Disclosure using BBS Signatures where they are specified and described.
- Add Base: unsigned document, key pair, mandatory pointers, generators; optional: proof configuration options, hmac key, stuff for JSON-LD document loading. Returns signed base document.
- Verify Base: signed base document, public key (rather than extracting it from document or web), generators; optional: stuff for JSON-LD document loading. Returns true/false.
- Derive Proof: signed base document, selective pointers, generators; optional: stuff for JSON-LD document loading. Returns signed derived document.
- Verify Derived: signed derived document, public key, generators; optional: stuff for JSON-LD document loading. Returns true/false.
Note: For verification functions the issuers public key as a Uint8Array without any multibase prefixes must be furnished. This library does not perform any external requests to obtain key material for verification.
See the examples directory for usage examples including JSON-LD document (context) loading and BBS generator creation. Example inputs are in the examples/input directory.
- signBase(document, keyPair, mandatoryPointers, options, gens)
sign a base document (credential) with
bbs-2023procedures. This is done by an issuer and permits the recipient, the holder, the freedom to selectively disclose "statements" extracted from the document to a verifier within the constraints of the mandatory disclosure requirements imposed by the issuer.- verifyBase(document, pubKey, options, gens)
verify a signed selective disclosure base document (credential) with
bbs-2023procedures. This is can be done by an holder on receipt of the credential.- derive(document, selectivePointers, options, gens, ph)
derive a selectively disclosed document (presentation) with ECDSA-SD procedures. This is done by a holder, who has the option to selectively disclose non-mandatory statements to a verifier.
- verifyDerived(document, pubKey, options, gens, ph)
verify a signed selective disclosure derived document (credential) with ECDSA-SD procedures. This is done by a verifier on receipt of the credential.
sign a base document (credential) with bbs-2023 procedures. This is done by an
issuer and permits the recipient, the holder, the freedom to selectively disclose
"statements" extracted from the document to a verifier within the constraints
of the mandatory disclosure requirements imposed by the issuer.
Kind: global function
| Param | Type | Description |
|---|---|---|
| document | Object |
The unsigned credential |
| keyPair | Object |
The issuers private/public key pair |
| keyPair.priv | Uint8Array |
Byte array for the BLS12-381 G1 private key without multikey prefixes |
| keyPair.pub | Uint8Array |
Byte array for the BLS12-381 G2 public key without multikey prefixes |
| mandatoryPointers | Array |
An array of mandatory pointers in JSON pointer format |
| options | Object |
A variety of options to control signing and processing |
| options.proofConfig | Object |
proof configuration options without @context field. Optional. This will be generated with current date information and did:key verification method otherwise. |
| options.hmacKey | Uint8Array |
A byte array for the HMAC key. Optional. A cryptographically secure random value will be generated if not specified. |
| options.proofKeyPair | Object |
A proof specific P256 key pair. Must be unique for each call to signBase. Optional. A unique key pair will be generated if not specified. |
| options.documentLoader | function |
A JSON-LD document loader to be passed on to JSON-LD processing functions. Optional. |
| gens | Object |
generators object from BBS prepareGenerators of sufficient size to cover the number of statements (messages) in the document. |
verify a signed selective disclosure base document (credential) with bbs-2023
procedures. This is can be done by an holder on receipt of the credential.
Kind: global function
| Param | Type | Description |
|---|---|---|
| document | Object |
The signed bbs-2023 base credential |
| pubKey | Uint8Array |
Byte array for the issuers BLS12-381 G2 public key without multikey prefixes |
| options | Object |
A variety of options to control signing and processing |
| options.documentLoader | function |
A JSON-LD document loader to be passed on to JSON-LD processing functions. Optional. |
| gens | Object |
generators object from BBS prepareGenerators of sufficient size to cover the number of statements (messages) in the document. |
derive a selectively disclosed document (presentation) with ECDSA-SD procedures. This is done by a holder, who has the option to selectively disclose non-mandatory statements to a verifier.
Kind: global function
| Param | Type | Description |
|---|---|---|
| document | Object |
The signed base credential |
| selectivePointers | Array |
An array of selective pointers in JSON pointer format |
| options | Object |
A variety of options to control signing and processing |
| options.documentLoader | function |
A JSON-LD document loader to be passed on to JSON-LD processing functions. Optional. |
| gens | Object |
generators object from BBS prepareGenerators of sufficient size to cover the number of statements (messages) in the document. |
| ph | Uint8Array |
BBS presentation header |
verify a signed selective disclosure derived document (credential) with ECDSA-SD procedures. This is done by a verifier on receipt of the credential.
Kind: global function
| Param | Type | Description |
|---|---|---|
| document | Object |
The signed SD derived credential |
| pubKey | Uint8Array |
Byte array for the issuers P256 public key without multikey prefixes |
| options | Object |
A variety of options to control signing and processing |
| options.documentLoader | function |
A JSON-LD document loader to be passed on to JSON-LD processing functions. Optional. |
| gens | Object |
generators object from BBS prepareGenerators of sufficient size to cover the number of statements (messages) in the document. |
| ph | Uint8Array |
BBS presentation header |