JSON-LD Signatures (jsonld-signatures)
An implementation of the Linked Data Signatures specification for JSON-LD, for Node.js and browsers.
Table of Contents
jsonld-signaturesv9.0 is compatible with the following signature suites:
and the following related libraries:
>= 5.0.0(and related key crypto suites such as
>= 7.0(currently, branch
BackgroundA Linked Data Signature proof is created (or verified) by specifying a signature suite and a proof purpose.
The signature suite performs the cryptographic operation required to sign (or verify) a digital signature and includes information in a proof such as the
verificationMethodidentifier, the proof's
controller, and the date the proof was created.
The proof purpose indicates why the proof was created and what its intended use is. This information can also be used to make sure that the
verificationMethodwas authorized for the stated purpose in the proof. Using a proof purpose helps to encourage people to authorize certain cryptographic keys (verification methods) for explicit purposes rather than granting them ambient authority. This approach can help prevent people from accidentally signing documents for reasons they did not intend.
This library provides base classes for signature suites and proof purposes so that custom extensions can be written. It also provides some commonly used proof purposes.
Relationship to Verifiable Credentials
jsonld-signaturesis a low-level library that is meant to sign any JSON-LD document.
One common use case for creating these signatures is for use with Verifiable Credentials (VCs). If you're working with those, you should use a higher-level library that's specifically made for that purpose, such as
vc-jsuses this library,
jsonld-signatures, under the hood.)
SecurityAs with most security- and cryptography-related tools, the overall security of your system will largely depend on your design decisions (which key types you will use, where you'll store the private keys, what you put into your credentials, and so on).
Document LoaderDuring verification, the key and key controller information must be discovered. This library allows for the key and key controller information to be looked up via a
documentLoaderor it can be provided directly to the API via the signature suite or proof purpose, respectively.
This library's default
documentLoaderis very strict for security and content integrity purposes. It will only load locally available copies of the context documents that define the terms it uses internally. Any attempt to load any other documents (including other contexts) will throw an error. If other documents such as verification methods (e.g., public key documents), cannot be provided directly to the API and thus need to be loaded, a custom document loader must be passed. For the sake of clarity, the default document loader will only load locally available copies of the following documents:
If you require other documents to be loaded then you will need to provide a
documentLoaderthat can provide them. jsonld.js provides both a node and browser
documentLoaderyou can use, however, depending on your use case, you may increase security by using a custom
documentLoaderthat is similarly strict and will only load a subset of documents that is constrained by some technical, security, or business rules.
- Browsers and Node.js 14+ are supported.
To install from NPM:
npm install jsonld-signatures
To install locally (for development):
git clone https://github.com/digitalbazaar/jsonld-signatures.git cd jsonld-signatures npm install
8.xand above) is not meant for standalone use. Instead, it's generally used through an individual crypto suite. For detailed usage instructions, see the READMEs of the supported suites:
Most of the usages with individual suites and key types will have elements in common. You'll need to:
- Generate or import cryptographic keys to sign with (see
@digitalbazaar/crypto-ld >=v5.0) library), or use a secure
signer()function provided by your secure cryptographic module.
- Authorize those keys for the specific purpose you're using
- Pair those keys with a corresponding cryptographic Signature Suite.
Ed25519Signature2020suite, and for legacy/compatibility work, you can use
Ed25519Signature2018suite. See also the Choosing a Key Type section of
- Set up your
documentLoaderto fetch contexts and documents securely.
- Lastly, perform the
Node.js Native Canonize BindingsSpecialized use cases may wish to use the native canonize bindings. This mode can be enabled by setting the
true. See the jsonld.js notes on this feature and note you should benchmark performance before using it.
ContributeSee the contribute file!
If editing the Readme, please conform to the standard-readme specification.