An implementation of JSON Web Signatures.
This was developed against draft-ietf-jose-json-web-signature-08 and
implements the entire spec except X.509 Certificate Chain
signing/verifying (patches welcome).
There are both synchronous (jws.sign, jws.verify) and streaming
(jws.createSign, jws.createVerify) APIs.
$ npm install jws
Array of supported algorithms. The following algorithms are currently supported.
| alg Parameter Value | Digital Signature or MAC Algorithm |
|---|---|
| HS256 | HMAC using SHA-256 hash algorithm |
| HS384 | HMAC using SHA-384 hash algorithm |
| HS512 | HMAC using SHA-512 hash algorithm |
| RS256 | RSASSA using SHA-256 hash algorithm |
| RS384 | RSASSA using SHA-384 hash algorithm |
| RS512 | RSASSA using SHA-512 hash algorithm |
| PS256 | RSASSA-PSS using SHA-256 hash algorithm |
| PS384 | RSASSA-PSS using SHA-384 hash algorithm |
| PS512 | RSASSA-PSS using SHA-512 hash algorithm |
| ES256 | ECDSA using P-256 curve and SHA-256 hash algorithm |
| ES384 | ECDSA using P-384 curve and SHA-384 hash algorithm |
| ES512 | ECDSA using P-521 curve and SHA-512 hash algorithm |
| none | No digital signature or MAC value included |
(Synchronous) Return a JSON Web Signature for a header and a payload.
Options:
headerpayloadsecret or privateKeyencoding (Optional, defaults to 'utf8')header must be an object with an alg property. header.alg must be
one a value found in jws.ALGORITHMS. See above for a table of
supported algorithms.
If payload is not a buffer or a string, it will be coerced into a string
using JSON.stringify.
Example
const signature = jws.sign({
header: { alg: 'HS256' },
payload: 'h. jon benjamin',
secret: 'has a van',
});
(Synchronous) Returns true or false for whether a signature matches a
secret or key.
signature is a JWS Signature. header.alg must be a value found in jws.ALGORITHMS.
See above for a table of supported algorithms. secretOrKey is a string or
buffer containing either the secret for HMAC algorithms, or the PEM
encoded public key for RSA and ECDSA.
Note that the "alg" value from the signature header is ignored.
(Synchronous) Returns the decoded header, decoded payload, and signature parts of the JWS Signature.
Returns an object with three properties, e.g.
{ header: { alg: 'HS256' },
payload: 'h. jon benjamin',
signature: 'YOWPewyGHKu4Y_0M_vtlEnNlqmFOclqp4Hy6hVHfFT4'
}
Returns a new SignStream object.
Options:
header (required)payloadkey || privateKey || secretencoding (Optional, defaults to 'utf8')Other than header, all options expect a string or a buffer when the
value is known ahead of time, or a stream for convenience.
key/privateKey/secret may also be an object when using an encrypted
private key, see the crypto documentation.
Example:
// This...
jws.createSign({
header: { alg: 'RS256' },
privateKey: privateKeyStream,
payload: payloadStream,
}).on('done', function(signature) {
// ...
});
// is equivalent to this:
const signer = jws.createSign({
header: { alg: 'RS256' },
});
privateKeyStream.pipe(signer.privateKey);
payloadStream.pipe(signer.payload);
signer.on('done', function(signature) {
// ...
});
Returns a new VerifyStream object.
Options:
signaturealgorithmkey || publicKey || secretencoding (Optional, defaults to 'utf8')All options expect a string or a buffer when the value is known ahead of time, or a stream for convenience.
Example:
// This...
jws.createVerify({
publicKey: pubKeyStream,
signature: sigStream,
}).on('done', function(verified, obj) {
// ...
});
// is equivilant to this:
const verifier = jws.createVerify();
pubKeyStream.pipe(verifier.publicKey);
sigStream.pipe(verifier.signature);
verifier.on('done', function(verified, obj) {
// ...
});
A Readable Stream that emits a single data event (the calculated
signature) when done.
function (signature) { }
A Writable Stream that expects the JWS payload. Do not use if you
passed a payload option to the constructor.
Example:
payloadStream.pipe(signer.payload);
A Writable Stream. Expects the JWS secret for HMAC, or the privateKey
for ECDSA and RSA. Do not use if you passed a secret or key option
to the constructor.
Example:
privateKeyStream.pipe(signer.privateKey);
This is a Readable Stream that emits a single data event, the result
of whether or not that signature was valid.
function (valid, obj) { }
valid is a boolean for whether or not the signature is valid.
A Writable Stream that expects a JWS Signature. Do not use if you
passed a signature option to the constructor.
A Writable Stream that expects a public key or secret. Do not use if you
passed a key or secret option to the constructor.
It feels like there should be some convenience options/APIs for
defining the algorithm rather than having to define a header object
with { alg: 'ES512' } or whatever every time.
X.509 support, ugh
MIT
Copyright (c) 2013-2015 Brian J. Brennan
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
jsonwebtoken is a popular npm package that provides similar functionality to jws. It allows you to encode and decode JSON Web Tokens (JWTs) which are an extension of JWS. It includes additional features for handling token expiration, audience, issuer, and other JWT claims.
jose is a comprehensive library for JSON Object Signing and Encryption (JOSE). It supports JWS, JSON Web Encryption (JWE), JSON Web Key (JWK), and JSON Web Algorithms (JWA). It offers a wider range of cryptographic operations compared to jws.
node-jose is another library that provides JOSE functionalities in Node.js. It is similar to the 'jose' package but is designed specifically for Node.js environments. It supports JWS, JWE, JWK, and JWA, and it is built to work well with other Node.js modules and async patterns.
FAQs
Implementation of JSON Web Signatures
The npm package jws receives a total of 36,355,413 weekly downloads. As such, jws popularity was classified as popular.
We found that jws demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket Firewall Enterprise is now available with flexible deployment, configurable policies, and expanded language support.
Security News
Open source dashboard CNAPulse tracks CVE Numbering Authorities’ publishing activity, highlighting trends and transparency across the CVE ecosystem.
Product
Detect malware, unsafe data flows, and license issues in GitHub Actions with Socket’s new workflow scanning support.