This module is deprecated!
This module is deprecated because jsrsasign is unmaintained.For general crypto, use a libsodium wrapper such as sodium-native or sodium-plus.
For JSON Web Signatures and Tokens, use jose.
Documentation for deprecated module
Node.js wrapper around jsrsasign (a JSON Web Signature library).- Uses crypto for performance.
node-jsjws
version 3, at least Node.js version 8 is required and the dependency on ursa has been removed.
- From node-jsjws
version 6, at least Node.js version 12 is required and KeyObject
s are used internally.- Note: Versions 2.0.0 and later fix a vulnerability in JSON Web Signature and JSON Web Token verification so please upgrade if you're using this functionality. The API has changed so you will need to update your application. verifyJWSByKey and verifyJWTByKey now require you to specify which signature algorithms are allowed.
- Supports RS256, RS512, PS256, PS512, HS256, HS512 and none signature algorithms.
- Basic JSON Web Token functionality.
- Unit tests, including tests for interoperability with node-jose, node-jws, jwcrypto and jsrsasign in the browser (using PhantomJS).
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.toPublicKey(), ['PS256']));
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();
var pub_pem = key.toPublicPem();
var header = { alg: 'RS256' };
var payload = JSON.stringify('hello world!');
var priv_key = jsjws.createPrivateKey(priv_pem);
var pub_key = jsjws.createPublicKey(pub_pem);
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);
Licence
MITTests
grunt test
Lint
grunt lint
Code Coverage
grunt coverage
Istanbul results are available here.
Coverage is so low because most of the jsrsasign code included in node-jsjws is not used. To keep things simple I've included whole files rather than split out individual functions.
Benchmarks
grunt bench
Here are some results on a laptop with an Intel Core i5-4300M 2.6Ghz CPU and 8Gb RAM running Ubuntu 17.04.
In the tables, jsjws-fast uses crypto for signature generation and verification whereas jsjws-slow does everything in Javascript. The algorithm used was RS256.
generatekey x10|total (ms)|average (ns)| diff (%) :--|--:|--:|--: jsjws-fast|921|92,066,915|- jsjws-slow|22,018|2,201,816,811|2,292
generatesignature x1,000|total (ms)|average (ns)| diff (%) :--|--:|--:|--: jsjws-fast|1,447|1,447,365|- jsjws-slow|35,214|35,214,432|2,333
loadkey x1,000|total (ms)|average (ns)| diff (%) :--|--:|--:|--: jsjws-fast|4|3,584|- jsjws-slow|165|165,398|4,515
verifysignature x1,000|total (ms)|average (ns)| diff (%) :--|--:|--:|--: jsjws-fast|186|186,126|- jsjws-slow|1,177|1,176,602|532
API
Key functions
- createPrivateKey
- createPublicKey
- generatePrivateKey
- PrivateKey.prototype.toPrivatePem
- PrivateKey.prototype.toPublicKey
- PrivateKey.prototype.toPublicPem
- PublicKey.prototype.toPublicPem
JSON Web Signature functions
- JWS
- JWS.prototype.generateJWSByKey
- JWS.prototype.verifyJWSByKey
- JWS.prototype.getParsedHeader
- JWS.prototype.getUnparsedHeader
- JWS.prototype.getParsedPayload
- JWS.prototype.getUnparsedPayload
- JWS.prototype.processJWS
JSON Web Token functions
Certificate functions
createPrivateKey(pem)
Create a private RSA key from a PEM-format string.
Parameters:
{String} pem
Private key to load, in PEM Base64 format.
Return:
{PrivateKey}
The private key object.Go: TOC
createPublicKey(pem)
Create a public RSA key from a PEM-format string.
Parameters:
{String} pem
Public key to load, in PEM Base64 format.
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(importpassword, exportpassword, exportalg)
Convert a private RSA key to a PEM-format string.
Parameters:
{String} [import_password]
If the key you imported usingcreatePrivateKey
was encrypted, the password to use to decrypt it.{String} [export_password]
If you want to encrypt the PEM string, specify the password here.{String} [export_alg]
If you want to encrypt the PEM string, specify the encryption algorithm here asdes
,des3
,aes128
,aes192
oraes256
.
Return:
{String}
PEM Base64 format string (PKCS#1 unencrypted, PKCS#5 encrypted).Go: TOC | PrivateKey.prototype
PrivateKey.prototype.toPublicKey(password)
Convert a private RSA key to a PublicKey
.
Parameters:
{String} [password]
If the key you imported usingcreatePrivateKey
was encrypted, the password to use to decrypt it.
Return:
{PublicKey}
The public key.Go: TOC | PrivateKey.prototype
PrivateKey.prototype.toPublicPem(password)
Convert a private RSA key to a PEM-format string containing just the public key.
Parameters:
{String} [password]
If the key you imported usingcreatePrivateKey
was encrypted, the password to use to decrypt it.
Return:
{String}
PEM Base64 format string (PKCS#1).Go: TOC | PrivateKey.prototype
PublicKey.prototype.toPublicPem()
Convert a public RSA key to a PEM-format string.
Return:
{String}
PEM Base64 format string (PKCS#1).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, password)
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, callJSON.stringify
on it first.{PrivateKey | String | Buffer} key
The private key to be used to do the signing. ForHS256
andHS512
, pass a string orBuffer
. Fornone
, this argument is ignored.{String} [password]
Password used to decrypt the key. If not specified, the key is assumed not to be encrypted.
Return:
{String}
The JSON Web Signature. Note this includes the header, payload and cryptographic signature.Go: TOC | JWS.prototype
JWS.prototype.verifyJWSByKey(jws, key, allowedalgs)
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. ForHS256
andHS512
, pass a string orBuffer
. Note: if you passnull
andallowed_algs
containsnone
then the signature will not be verified.{Array} allowed_algs
Algorithms expected to be used to sign the signature.
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
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, notbefore, jtisize, key, password)
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. Specifynull
to omit the expiry from the token.{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 ornull
to omit the JTI from the token.{PrivateKey | String | Buffer} key
The private key to be used to sign the token. ForHS256
andHS512
, pass a string orBuffer
. Note: if you passnull
then the token will be returned with an empty cryptographic signature andheader.alg
will be forced to the valuenone
.{String} [password]
Password used to decrypt the key. If not specified, the key is assumed not to be encrypted.
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, allowedalgs)
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|Object} checks_optional
Whether to allow the typ
header property and the iat
, nbf
and exp
claim properties to be absent from the token. Defaults to false
— they must be present and valid. If you specify true
then the properties will only be validated if present in the token. You can also pass in an object specifying a boolean for each property (e.g. { exp: true }
).-
{Boolean|Object} skip_checks
Whether to skip validating the typ
header property and the iat
, nbf
and exp
claim properties even if they're present in the token. Defaults to false
. You can also pass in an object specifying a boolean for each property (e.g. { exp: true }
).{PublicKey} key
The public key to be used to verify the token. ForHS256
andHS512
, pass a string orBuffer
. Note: if you passnull
andallowed_algs
containsnone
then the token's signature will not be verified.{Array} allowed_algs
Algorithms expected to be used to sign the token.
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
, and options.skip_checks
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
X509()
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—