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.
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
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.
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.
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. BrennanPermission is hereby granted, free of charge, to any person obtaining acopy of this software and associated documentation files (the"Software"), to deal in the Software without restriction, includingwithout limitation the rights to use, copy, modify, merge, publish,distribute, sublicense, and/or sell copies of the Software, and topermit persons to whom the Software is furnished to do so, subject tothe following conditions:The above copyright notice and this permission notice shall be includedin all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESSOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE ANDNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BELIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTIONOF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTIONWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.