node-jws

node-jws

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.

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

…