Sign, selectively disclose, and verify credentials/presentations with ECDSA signatures and JavaScript!
This library is an independent implementation of the ecdsa-sd-2023 cryptosuite for verifiable credentials. The algorithms and functions are from sections 3.3-3.5 of Data Integrity ECDSA Cryptosuites v1.0 where they are specified and described.
- Add Base: unsigned document, key pair, mandatory pointers; optional: proof configuration options, hmac key, proof key pair, 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),; optional: stuff for JSON-LD document loading. Returns true/false.
- Derive Proof: signed base document, selective pointers; optional: stuff for JSON-LD document loading. Returns signed derived document.
- Verify Derived: signed derived document, public key; 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. Example inputs are in the examples/input directory.
- signBase(document, keyPair, mandatoryPointers, options)
sign a base document (credential) with ECDSA-SD 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.
- verifyBase(document, pubKey, options)
verify a signed selective disclosure base document (credential) with ECDSA-SD procedures. This is done by an holder on receipt of the credential.
- derive(document, selectivePointers, options)
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)
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 ECDSA-SD 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 P256 private key without multikey prefixes |
| keyPair.pub | Uint8Array |
Byte array for the P256 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. |
verify a signed selective disclosure base document (credential) with ECDSA-SD procedures. This is done by an holder on receipt of the credential.
Kind: global function
| Param | Type | Description |
|---|---|---|
| document | Object |
The signed SD base 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. |
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. |
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. |
- skolemizeExpandedJsonLd(expanded, options)
Replaces all blank node identifiers in an expanded JSON-LD document with custom-scheme URNs. Nodes without and id or blank node identifier will be assigned one.
- createInitialSelection(source)
Helper function for selectJsonLd
- jsonPointerToPaths(pointer) ⇒
Array Helper function for selectionJsonLd. Converts a JSON Pointer into an array of paths in a JSON tree.
- selectPaths(paths, document, selectionDocument, arrays)
Selects a portion of a compact JSON-LD document using paths parsed from a parsed JSON Pointer. This is a helper function used within the algorithm selectJsonLd.
- selectJsonLd(document, pointers) ⇒
The following algorithm selects a portion of a compact JSON-LD document using an array of JSON Pointers. The required inputs are an array of JSON Pointers (pointers) and a compact JSON-LD document (document). The document is assumed to use a JSON-LD context that aliases '@id' and '@type' to id and type, respectively, and to use only one '@context' property at the top level of the document.
- createHmacIdLabelMapFunction(hmacFunc) ⇒
The following algorithm creates a label map factory function that uses an HMAC to replace canonical blank node identifiers with their encoded HMAC digests. The required input is an HMAC (previously initialized with a secret key), HMAC. A function, labelMapFactoryFunction, is produced as output.
- selectCanonicalNQuads(pointers, skolemizedCompactDocument, labelMap, options) ⇒
The following algorithm selects a portion of a skolemized compact JSON-LD document using an array of JSON Pointers, and outputs the resulting canonical N-Quads with any blank node labels replaced using the given label map
- canonicalizeAndGroup(document, labelMapFactoryFunction, groupDefinitions, options) ⇒
The following algorithm is used to output canonical N-Quad strings that match custom selections of a compact JSON-LD document. It does this by canonicalizing a compact JSON-LD document (replacing any blank node identifiers using a label map) and grouping the resulting canonical N-Quad strings according to the selection associated with each group. Each group will be defined using an assigned name and array of JSON pointers. The JSON pointers will be used to select portions of the skolemized document, such that the output can be converted to canonical N-Quads to perform group matching.
- createLabelMapFunction(labelMap) ⇒
The following algorithm creates a label map factory function that uses an input label map to replace canonical blank node identifiers with another value.
- labelReplacementCanonicalizeJsonLd(document, labelMapFactoryFunction, options) ⇒
The following algorithm canonicalizes a JSON-LD document and replaces any blank node identifiers in the canonicalized result using a label map factory function, labelMapFactoryFunction.
Replaces all blank node identifiers in an expanded JSON-LD document with custom-scheme URNs. Nodes without and id or blank node identifier will be assigned one.
Kind: global function
| Param | Type | Description |
|---|---|---|
| expanded | Array |
an expanded JSON-LD array/object |
| options | Object |
options to control the blank node labels assigned |
| options.bnPrefix | Object |
a custom blank node prefix |
| options.randString | Object |
a UUID string or other comparably random string |
| options.count | Object |
blank node id counter |
Helper function for selectJsonLd
Kind: global function
| Param | Type | Description |
|---|---|---|
| source | Object |
a JSON-LD object |
Helper function for selectionJsonLd. Converts a JSON Pointer into an array of paths in a JSON tree.
Kind: global function
Returns: Array - paths
| Param | Type | Description |
|---|---|---|
| pointer | String |
a JSON pointer string per RFC6901 |
Selects a portion of a compact JSON-LD document using paths parsed from a parsed JSON Pointer. This is a helper function used within the algorithm selectJsonLd.
Kind: global function
| Param | Type | Description |
|---|---|---|
| paths | Array |
array of paths parsed from a JSON pointer |
| document | Object |
a compact JSON-LD document |
| selectionDocument | Object |
a selection document to be populated |
| arrays | Array |
an array of arrays for tracking selected arrays |
The following algorithm selects a portion of a compact JSON-LD document using an array of JSON Pointers. The required inputs are an array of JSON Pointers (pointers) and a compact JSON-LD document (document). The document is assumed to use a JSON-LD context that aliases '@id' and '@type' to id and type, respectively, and to use only one '@context' property at the top level of the document.
Kind: global function Returns: A new JSON-LD document that represents a selection (selectionDocument) of the original JSON-LD document is produced as output.
| Param | Type |
|---|---|
| document | Object |
| pointers | Array |
The following algorithm creates a label map factory function that uses an HMAC to replace canonical blank node identifiers with their encoded HMAC digests. The required input is an HMAC (previously initialized with a secret key), HMAC. A function, labelMapFactoryFunction, is produced as output.
Kind: global function Returns: a labelMapFactoryFunction
| Param | Type | Description |
|---|---|---|
| hmacFunc | function |
an initialized (with key) function to compute HMACs |
The following algorithm selects a portion of a skolemized compact JSON-LD document using an array of JSON Pointers, and outputs the resulting canonical N-Quads with any blank node labels replaced using the given label map
Kind: global function Returns: An object containing the new JSON-LD document that represents a selection of the original JSON-LD document (selectionDocument), an array of deskolemized N-Quad strings (deskolemizedNQuads), and an array of canonical N-Quads with replacement blank node labels (nquads).
| Param | Type | Description |
|---|---|---|
| pointers | Array |
an array of JSON Pointers |
| skolemizedCompactDocument | Object |
a skolemized compact JSON-LD document |
| labelMap | Map |
a blank node label map |
| options | * |
|
| options.documentLoader | function |
A JSON-LD document loader to be passed on to JSON-LD processing functions. Optional. |
The following algorithm is used to output canonical N-Quad strings that match custom selections of a compact JSON-LD document. It does this by canonicalizing a compact JSON-LD document (replacing any blank node identifiers using a label map) and grouping the resulting canonical N-Quad strings according to the selection associated with each group. Each group will be defined using an assigned name and array of JSON pointers. The JSON pointers will be used to select portions of the skolemized document, such that the output can be converted to canonical N-Quads to perform group matching.
Kind: global function Returns: An object containing the created groups (groups), the skolemized compact JSON-LD document (skolemizedCompactDocument), the skolemized expanded JSON-LD document (skolemizedExpandedDocument), the deskolemized N-Quad strings (deskolemizedNQuads), the blank node label map (labelMap), and the canonical N-Quad strings nquads.
| Param | Type | Description |
|---|---|---|
| document | Object |
a compact JSON-LD document. The document is assumed to use a JSON-LD context that aliases "@id" and "@type" to id and type, respectively, and to use only one "@context" property at the top level of the document. |
| labelMapFactoryFunction | function |
a function that maps blank node ids to a "urn:" scheme |
| groupDefinitions | Object |
a map of group names to corresponding arrays of JSON pointers |
| options | Object |
|
| options.documentLoader | function |
A JSON-LD document loader to be passed on to JSON-LD processing functions. Optional. |
The following algorithm creates a label map factory function that uses an input label map to replace canonical blank node identifiers with another value.
Kind: global function Returns: A function, labelMapFactoryFunction
| Param | Type |
|---|---|
| labelMap | Map |
The following algorithm canonicalizes a JSON-LD document and replaces any blank node identifiers in the canonicalized result using a label map factory function, labelMapFactoryFunction.
Kind: global function Returns: An N-Quads representation of the canonicalNQuads as an array of N-Quad strings, with the replaced blank node labels, and a map from the old blank node IDs to the new blank node IDs, labelMap.
| Param | Type | Description |
|---|---|---|
| document | Object |
a JSON-LD document |
| labelMapFactoryFunction | function |
a label map factory function |
| options | Object |
|
| options.documentLoader | function |
A JSON-LD document loader to be passed on to JSON-LD processing functions. Optional. |