jsjws

Wraps jsjws (http://kjur.github.io/jsjws/) so it works on Node.js and uses ursa for performance

npm install jsjws
38 downloads in the last week
69 downloads in the last month

node-jsjws   Build Status Coverage Status NPM version

Node.js wrapper around jsjws (a JSON Web Signature library).

Example:

var jsjws = require('jsjws');
var key = jsjws.generatePrivateKey(2048, 65537);
var header = { alg: 'PS256' };
var payload = { foo: 'bar', wup: 90 };
var sig = new jsjws.JWS().generateJWSByKey(header, payload, key);
var jws = new jsjws.JWS();
assert(jws.verifyJWSByKey(sig, key));
assert.deepEqual(jws.getParsedHeader(), header);
assert.deepEqual(jws.getParsedPayload(), payload);

The API is described here.

Installation

npm install jsjws

Another Example

You can read and write keys from and to PEM-format strings:

var jsjws = require('jsjws');
var key = jsjws.generatePrivateKey(2048, 65537);
var priv_pem = key.toPrivatePem('utf8');
var pub_pem = key.toPublicPem('utf8');
var header = { alg: 'RS256' };
var payload = JSON.stringify('hello world!');
var priv_key = jsjws.createPrivateKey(priv_pem, 'utf8');
var pub_key = jsjws.createPublicKey(pub_pem, 'utf8');
var sig = new jsjws.JWS().generateJWSByKey(header, payload, priv_key);
var jws = new jsjws.JWS();
assert(jws.verifyJWSByKey(sig, pub_key));
assert.deepEqual(jws.getParsedHeader(), header);
assert.equal(jws.getUnparsedPayload(), payload);

Licence

MIT

Tests

grunt test

Lint

grunt lint

Code Coverage

grunt coverage

Instanbul results are available here.

Coveralls page is here.

Benchmarks

grunt bench

Here are some results on a laptop with an Intel Core i5-3210M 2.5Ghz CPU and 6Gb RAM running Ubuntu 13.04.

In the tables, jsjws-fast uses ursa (OpenSSL) for crypto whereas jsjws-slow does everything in Javascript. The algorithm used was RS256 because jwcrypto doesn't support PS256.

generate_key x10 total (ms) average (ns) diff (%)
jwcrypto 1,183 118,263,125 -
jsjws-fast 1,296 129,561,098 10
jsjws-slow 32,090 3,209,012,197 2,613
generate_signature x1,000 total (ms) average (ns) diff (%)
jsjws-fast 2,450 2,450,449 -
jwcrypto 4,786 4,786,343 95
jsjws-slow 68,589 68,588,742 2,699
load_key x1,000 total (ms) average (ns) diff (%)
jsjws-fast 46 45,996 -
jsjws-slow 232 232,481 405
verify_signature x1,000 total (ms) average (ns) diff (%)
jsjws-fast 134 134,032 -
jwcrypto 173 173,194 29
jsjws-slow 1,706 1,705,810 1,173

API

Key functions

JSON Web Signature functions

JSON Web Token functions


createPrivateKey(pem, [password], [encoding])

Create a private RSA key from a PEM-format string.

Parameters:

  • {String} pem Private key to load, in PEM Base64 format.
  • {String} [password] Password used to decrypt the key. If not specified, the key is assumed not to be encrypted.
  • {String} [encoding] How the key in pem is encoded (e.g. utf8, ascii). Defaults to utf8.

Return:

{PrivateKey} The private key object.

Go: TOC

createPublicKey(pem, [encoding])

Create a public RSA key from a PEM-format string.

Parameters:

  • {String} pem Public key to load, in PEM Base64 format.
  • {String} [encoding] How the key in pem is encoded (e.g. utf8, ascii). Defaults to utf8.

Return:

{PublicKey} The public key object.

Go: TOC

generatePrivateKey(modulusBits, exponent)

Generate a new RSA private key (keypair). The private key also contains the public key component.

Parameters:

  • {String} modulusBits Number of bits in the modulus (typically 2048).
  • {Integer} exponent Exponent value (typically 65537).

Return:

{PrivateKey} The private key (keypair) object.

Go: TOC

PrivateKey.prototype.toPrivatePem(encoding)

Convert a private RSA key to a PEM-format string.

Parameters:

  • {String} encoding How to encode the returned string. Defaults to returning a Node.js Buffer object.

Return:

{String} PEM Base64 format string.

Go: TOC | PrivateKey.prototype

PublicKey.prototype.toPublicPem(encoding)

Convert a public RSA key to a PEM-format string. Note: you can also call toPublicPem on a PrivateKey (because private keys contain the public key data too).

Parameters:

  • {String} encoding How to encode the returned string. Defaults to returning a Node.js Buffer object.

Return:

{String} PEM Base64 format string.

Go: TOC | PublicKey.prototype

JWS()

Create a new JWS object which can be used to generate or verify JSON Web Signatures.

Go: TOC

JWS.prototype.generateJWSByKey(header, payload, key)

Generate a JSON Web Signature.

Parameters:

  • {Object} header Metadata describing the payload. If you pass a string, it's assumed to be a JSON serialization of the metadata. The metadata should contain at least the following property:
  • {String} alg The algorithm to use for generating the signature. RS256, RS512, PS256, PS512, HS256, HS512 and none are supported.
  • {Object} payload The data you want included in the signature. If you pass a string, it's assumed to be a JSON serialization of the data. So if you want to include just a string, call JSON.stringify on it first.
  • {PrivateKey | String | Buffer} key The private key to be used to do the signing. For HS256 and HS512, pass a string or Buffer. For none, this argument is ignored.

Return:

{String} The JSON Web Signature. Note this includes the header, payload and cryptographic signature.

Go: TOC | JWS.prototype

JWS.prototype.verifyJWSByKey(jws, key)

Verify a JSON Web Signature.

Parameters:

  • {String} jws The JSON Web Signature to verify.
  • {PublicKey} key The public key to be used to verify the signature. For HS256 and HS512, pass a string or Buffer. Note: if you pass null then the signature will not be verified.

Return:

{Boolean} true if the signature was verified successfully using the public key or the JSON Web Signature's algorithm is none.

Throws:

  • {Error} If the signature failed to verify.

Go: TOC | JWS.prototype

JWS.prototype.getParsedHeader()

Get the header (metadata) from a JSON Web Signature. Call this after verifying the signature (with JWS.prototype.verifyJWSByKey).

Return:

{Object} The header.

Go: TOC | JWS.prototype

JWS.prototype.getUnparsedHeader()

Get the header (metadata) from a JSON Web Signature. Call this after verifying the signature (with JWS.prototype.verifyJWSByKey).

Return:

{String} The JSON-encoded header.

Go: TOC | JWS.prototype

JWS.prototype.getParsedPayload()

Get the payload (data) from a JSON Web Signature. Call this after verifying the signature (with JWS.prototype.verifyJWSByKey).

Return:

{Object} The payload.

Go: TOC | JWS.prototype

JWS.prototype.getUnparsedPayload()

Get the payload (data) from a JSON Web Signature. Call this after verifying the signature (with JWS.prototype.verifyJWSByKey).

Return:

{String} The JSON-encoded payload.

Go: TOC | JWS.prototype

JWS.prototype.processJWS(jws)

Process a JSON Web Signature without verifying it. Call this before JWS.prototype.verifyJWSByKey if you need access to the header or data in the signature before verifying it. For example, the metadata might identify the issuer such that you can retrieve the appropriate public key.

Parameters:

  • {String} jws The JSON Web Signature to process.

Go: TOC | JWS.prototype

JWT()

Create a new JWT object which can be used to generate or verify JSON Web Tokens.

Inherits from JWS.

Go: TOC

JWT.prototype.generateJWTByKey(header, claims, expires, [not_before], key)

Generate a JSON Web Token.

Parameters:

  • {Object} header Metadata describing the token's claims. Pass a map of key-value pairs. The metadata should contain at least the following property:
  • {String} alg The algorithm to use for generating the signature. RS256, RS512, PS256, PS512, HS256, HS512 and none are supported.
  • {Object} claims The claims you want included in the signature. Pass a map of key-value pairs.
  • {Date} expires When the token expires.
  • {Date} [not_before] When the token is valid from. Defaults to current time.
  • {PrivateKey | String | Buffer} key The private key to be used to sign the token. For HS256 and HS512, pass a string or Buffer. Note: if you pass null then the token will be returned with an empty cryptographic signature and header.alg will be forced to the value none.

Return:

{String} The JSON Web Token. Note this includes the header, claims and cryptographic signature. The following extra claims are added, per the JWT spec:

  • {IntDate} exp The UTC expiry date and time of the token, in number of seconds from 1970-01-01T0:0:0Z UTC.

  • {IntDate} nbf The UTC valid-from date and time of the token.

  • {IntDate} iat The UTC date and time at which the token was generated.

  • {String} jti A unique identifier for the token.

Go: TOC | JWT.prototype

JWT.prototype.verifyJWTByKey(jwt, [options], key)

Verify a JSON Web Token.

Parameters:

  • {String} jwt The JSON Web Token to verify.
  • {Object} [options] Optional parameters for the verification:
  • {Integer} iat_skew The amount of leeway (in seconds) to allow between the issuer's clock and the verifier's clock when verifiying that the token was generated in the past. Defaults to 0.

  • {Boolean} checks_optional Whether the token must contain the typ header property and the iat, nbf and exp claim properties. Defaults to false.

  • {PublicKey} key The public key to be used to verify the token. For HS256 and HS512, pass a string or Buffer. Note: if you pass null then the token's signature will not be verified.

Return:

{Boolean} true if the token was verified successfully. The token must pass the following tests:

Its signature must verify using the public key or its algorithm must be none.

If the corresponsing property is present or options.checks_optional is false:

  • Its header must contain a property typ with the value JWT.

  • Its claims must contain a property iat which represents a date in the past (taking into account options.iat_skew).

  • Its claims must contain a property nbf which represents a date in the past.

  • Its claims must contain a property exp which represents a date in the future.

Throws:

  • {Error} If the token failed to verify.

Go: TOC | JWT.prototype

—generated by apidox

npm loves you