jsjws

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

node-jsjws   

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, ['PS256']));
assert.deepEqual(jws.getParsedHeader(), header);
assert.deepEqual(jws.getParsedPayload(), payload);

The API is described here.

npm install jsjws

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, ['RS256']));
assert.deepEqual(jws.getParsedHeader(), header);
assert.equal(jws.getUnparsedPayload(), payload);

MIT

grunt test
grunt lint
grunt coverage

Instanbul results are available here.

Coverage is so low because most of the jsjws code included in node-jsjws is not used. To keep things simple I've included whole files rather than split out individual functions.

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.

generate_key x10total (ms)average (ns)diff (%)
jsjws-fast79279,152,022-
jsjws-slow17,1111,711,099,9252,062
generate_signature x1,000total (ms)average (ns)diff (%)
jsjws-fast1,1841,184,491-
jsjws-slow31,71231,712,2012,577
load_key x1,000total (ms)average (ns)diff (%)
jsjws-fast3130,536-
jsjws-slow202202,147562
verify_signature x1,000total (ms)average (ns)diff (%)
jsjws-fast8484,004-
jsjws-slow1,1441,144,4881,262

API


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

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

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

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

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

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

Go: TOC

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

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 and allowed_algs contains none then the signature will not be verified.
  • {Array | Object} allowed_algs Algorithms expected to be used to sign the signature. If you pass an Object then its properties define the set of algorithms expected.

Return:

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

  • Its header must contain a property alg with a value in allowed_algs.

  • Its signature must verify using key (unless its algorithm is none and none is in allowed_algs).

Throws:

  • {Error} If the signature failed to verify.

Go: TOC | JWS.prototype

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

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

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

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

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

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

Inherits from JWS.

Go: TOC

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.

  • {Integer} [jti_size] Size in bytes of a unique token ID to put into the token (can be used to detect replay attacks). Defaults to 16 (128 bits). Specify 0 or null to omit the JTI from the token.

  • {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

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 and allowed_algs contains none then the token's signature will not be verified.

  • {Array | Object} allowed_algs Algorithms expected to be used to sign the token. If you pass an Object then its properties define the set of algorithms expected.

Return:

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

  • Its header must contain a property alg with a value in allowed_algs.

  • Its signature must verify using key (unless its algorithm is none and none is in allowed_algs).

  • If the corresponding 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

A class for handling X509 certificates. This is included as a utility for extracting public keys and information from a certificate.

Please see the jsjws reference for full details of the static and instance methods available on X509.

See this unit test for an example of extracting the public key from a certificate in order to verify a JSON Web Signature.

Go: TOC

—generated by apidox