jws

What is jws?

The jws npm package is a JavaScript implementation for JSON Web Signatures (JWS). It allows you to create, verify, and work with JWSs. This package is useful for implementing security features in applications, such as token-based authentication and data integrity checks.

What are jws's main functionalities?

Signing

This feature allows you to create a JWS by providing a payload, a secret (or private key), and an algorithm. The package will generate a signature that can be used to verify the payload's integrity and authenticity.

{"alg":"HS256","typ":"JWT"}.{"name":"John Doe"}.HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), 'secret')

Verification

This feature allows you to verify a JWS signature using the provided secret (or public key) and the algorithm. It returns a boolean indicating whether the signature is valid.

jws.verify(signature, algorithm, secretOrPublicKey)

Decoding

This feature allows you to decode a JWS to extract the header and payload without verifying the signature. This is useful for cases where you need to read the payload without necessarily trusting its source.

jws.decode(signature)

Other packages similar to jws

jsonwebtoken

jsonwebtoken is a popular npm package that provides similar functionality to jws. It allows you to encode and decode JSON Web Tokens (JWTs) which are an extension of JWS. It includes additional features for handling token expiration, audience, issuer, and other JWT claims.

jose

jose is a comprehensive library for JSON Object Signing and Encryption (JOSE). It supports JWS, JSON Web Encryption (JWE), JSON Web Key (JWK), and JSON Web Algorithms (JWA). It offers a wider range of cryptographic operations compared to jws.

node-jose

node-jose is another library that provides JOSE functionalities in Node.js. It is similar to the 'jose' package but is designed specifically for Node.js environments. It supports JWS, JWE, JWK, and JWA, and it is built to work well with other Node.js modules and async patterns.

README

jws

JSON Web Signatures for node.

This was implemented against draft-ietf-jose-json-web-signature-08.

The following algorithms are supported:

• HMAC SHA-256 (HS256)
• RSA SHA-256 (RS256)

We yet support ECDSA yet (ES256/384/512) because OpenSSL doesn't support it as a message digest algorithm (it only supports ecdsa-with-sha1) which means we can't load it with crypto.createSign or crypto.createVerify. Hopefully this is forthcoming.

install

$ npm install jws

example

const jws = require('jws');

// By default we use HMAC SHA-256
var payload = 'everybody dance NOW.';
var secret = 'supersecrettech';
var jwsObject = jws.sign(payload, secret);

jws.verify(jwsObject, secret) // === true
jws.verify(jwsObject, 'hax') // === false

// If the `secret` is a RSA key, it will figure that out and sign it appropriately.
var privateKey = fs.readFileSync(process.env.HOME + '/.ssh/id_rsa');
var publicKey = fs.readFileSync(process.env.HOME + '/.ssh/id_rsa.pub');
var jwsObject = jws.sign(payload, privateKey);

jws.verify(jwsObject, publicKey) // === true

// By default, the header will just include the algorithm detected by
// the secret or key. If you want to add more info the the header, you
// can do so explicitly.

var jwsHmacObject = jws.sign({
  header: { alg: 'HS256', typ: 'JWT' },
  payload: payload,
  secret: secret,
});

var jwsRsaSignedObject = jws.sign({
  header: { alg: 'RS256', typ: 'Ham+Cheese' },
  payload: payload,
  key: privateKey,
});