Big update!Introducing GitHub Bot Commands. Learn more
Socket
Log inBook a demo

jws

Package Overview
Dependencies
2
Maintainers
3
Versions
23
Issues
File Explorer

Advanced tools

jws

Implementation of JSON Web Signatures

    4.0.0latest

Version published
Maintainers
3
Weekly downloads
16,016,008
increased by6.86%

Weekly downloads

Readme

Source

node-jws Build Status

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.

Install

$ npm install jws

Usage

jws.ALGORITHMS

Array of supported algorithms. The following algorithms are currently supported.

alg Parameter ValueDigital Signature or MAC Algorithm
HS256HMAC using SHA-256 hash algorithm
HS384HMAC using SHA-384 hash algorithm
HS512HMAC using SHA-512 hash algorithm
RS256RSASSA using SHA-256 hash algorithm
RS384RSASSA using SHA-384 hash algorithm
RS512RSASSA using SHA-512 hash algorithm
PS256RSASSA-PSS using SHA-256 hash algorithm
PS384RSASSA-PSS using SHA-384 hash algorithm
PS512RSASSA-PSS using SHA-512 hash algorithm
ES256ECDSA using P-256 curve and SHA-256 hash algorithm
ES384ECDSA using P-384 curve and SHA-384 hash algorithm
ES512ECDSA using P-521 curve and SHA-512 hash algorithm
noneNo digital signature or MAC value included

jws.sign(options)

(Synchronous) Return a JSON Web Signature for a header and a payload.

Options:

  • header
  • payload
  • secret or privateKey
  • encoding (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', });

jws.verify(signature, algorithm, secretOrKey)

(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.

jws.decode(signature)

(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' }

jws.createSign(options)

Returns a new SignStream object.

Options:

  • header (required)
  • payload
  • key || privateKey || secret
  • encoding (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) { // ... });

jws.createVerify(options)

Returns a new VerifyStream object.

Options:

  • signature
  • algorithm
  • key || publicKey || secret
  • encoding (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) { // ... });

Class: SignStream

A Readable Stream that emits a single data event (the calculated signature) when done.

Event: 'done'

function (signature) { }

signer.payload

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);

signer.secret
signer.key
signer.privateKey

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);

Class: VerifyStream

This is a Readable Stream that emits a single data event, the result of whether or not that signature was valid.

Event: 'done'

function (valid, obj) { }

valid is a boolean for whether or not the signature is valid.

verifier.signature

A Writable Stream that expects a JWS Signature. Do not use if you passed a signature option to the constructor.

verifier.secret
verifier.key
verifier.publicKey

A Writable Stream that expects a public key or secret. Do not use if you passed a key or secret option to the constructor.

TODO

  • 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

License

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.

Keywords

FAQs

What is jws?

Implementation of JSON Web Signatures

Is jws popular?

The npm package jws receives a total of 13,468,689 weekly downloads. As such, jws popularity was classified as popular.

Is jws well maintained?

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.

Last updated on 16 Dec 2019

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket
Socket

Product

Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc