jose module

The jose module provides APIs to encrypt and decrypt messages and to sign and verify messages. Encryption and decryption use JSON Web Encryption (JWE) specifications. Signing and verifying messages use JSON Web Signature (JWS) specifications.

To access the functions in the jose module, use the require('jose') statement.

APIs to encrypt messages according to the JWE specifications.
APIs to decrypt messages according to the JWE specifications.
APIs to sign messages according to the JWS specifications.
APIs to verify messages according to the JWS specifications.

jose.createJWEEncrypter()

Creates a JWEEncrypter object.

Syntax

jose.createJWEEncrypter(jweHdr[, iv])

Parameters

jweHdr
A JWEHeader object. This parameter is mandatory.
iv
The initialization vector (IV). The iv must be the correct length according to the encryption algorithm in jweHdr. If it does not present, an auto-generated IV is used.

jose.createJWEHeader()

Creates a JWEHeader object.

Syntax

jose.createJWEHeader(enc)

Parameters

enc
A supported algorithm for encryption. This parameter is mandatory. The following values for the enc are supported.
  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM

jose.getJWEAlg()

Returns a supported algorithm list for JWE key management.

Syntax

jose.getJWEAlg()

Guidelines

The following values for JWE key management algorithms are supported.
  • RSA1_5
  • RSA-OAEP
  • RSA-OAEP-256
  • A128KW
  • A192KW
  • A256KW
  • dir

RSA1_5, RSA-OAEP, and RSA-OAEP-256 are key encryption algorithms.

A128KW, A192KW, and A256KW are key wrapping algorithms.

dir is direct encryption with a shared symmetric key.

jose.getJWEEnc()

Returns a supported algorithm list for JWE encryption.

Syntax

jose.getJWEEnc()

Guidelines

The following values for JWE encryption algorithms are supported.
  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM

jose.isJWEHeader()

Verifies whether an object is a JWEHeader.

Syntax

jose.isJWEHeader(obj)

Parameters

obj
A JavaScript object.

JWEEncrypter class

The JWEEncrypter class is used to encrypt a message and generate a JWE message.

The JWEEncrypter class provides the following class methods.

JWEEncrypter.update()

Populates the payload into a JWE encryption object.

Syntax

JWEEncrypter.update(payload, encoding)

Parameters

payload
The data that is being encrypted.
encoding
The encoding of the data.

Guidelines

The payload must be string, Buffer, or Buffers.

The encoding is only used when payload is a string. It must be'utf8' or 'ascii'.

JWEEncrypter.getAAD()

Gets the value that is used for the additional authenticated data (AAD) input parameter, which is set by JWEEncrypter.setAAD() method.

Syntax

JWEEncrypter.getAAD()

JWEEncrypter.setAAD()

Sets the value that is used for the additional authenticated data (AAD) input parameter.

Syntax

JWEEncrypter.setAAD(buffer)

Guidelines

This method works only in JavaScript Object Notation (JSON) serialization and is used before the encrypt() method. The data type is a Buffer.

JWEEncrypter.encrypt()

Encrypts the JWE encryption object.

Syntax

JWEEncrypter.encrypt([output_format], function(error,jweObj))

Parameters

output_format
The serialization format.
function
A callback function that is run when JWE encryption is done.
error
The error information if an error occurs.
jweObj
A string or object.

Guidelines

The output_format is a string that can be 'compact', 'json', or 'json_flat'. The default value is 'compact'.
  • 'compact' indicates the compact serialization.
  • 'json' indicates the general JSON serialization.
  • 'json_flat' indicates the flattened JOSN serialization. Flattened JSON serialization is available when only one recipient exists.

If an error happens, error is an error object that contains an error message. If encryption completes without any error, jweObj is a string or JSON object based on the serialization format.

Examples

  • Compact serialization.
    var jose = require('jose');
var jweHdr = jose.createJWEHeader('A128CBC-HS256');
jweHdr.setProtected('alg', 'RSA1_5');
jweHdr.setKey('Alice');
jose.createJWEEncrypter(jweHdr).update("test").encrypt('compact', function(error, jweObj) {
   if (error) {
    session.output.write(error);
  } else {
    session.output.write(jweObj);
  }
});
  • General JSON serialization.
    var jose = require('jose');
var jweHdr = jose.createJWEHeader('A128CBC-HS256');
jweHdr.addRecipient('Alice', 'RSA1_5', {'kid': 'Alice'});
jweHdr.addRecipient('Bob', 'RSA1_5', {'kid': 'Bob'});
jose.createJWEEncrypter(jweHdr).update("test").encrypt('json', function(error, jweObj) {
  if (error) {
    session.output.write(error);
  } else {
    session.output.write(jweObj);
  }
});
  • Flattened JSON serialization.
    var jose = require('jose');
var jweHdr = jose.createJWEHeader('A128CBC-HS256');
jweHdr.setProtected('alg', 'RSA1_5');
jweHdr.setKey('Alice');
jose.createJWEEncrypter(jweHdr).update("test").encrypt('json_flat', function(error, jweObj) {
  if (error) {
    session.output.write(error);
  } else {
    session.output.write(jweObj);
  }
});

JWEHeader class

The JWEHeader class is used to wrap a JSON serialization JWE message. It provides API to set a protected header, an unprotected header, and recipient.

The JWEHeader class provides the following class methods.

JWEHeader.setProtected()

Sets a protected header name.

Syntax

JWEHeader.setProtected(name, value)

JWEHeader.setProtected(JSON_object)

Parameters

name
The protected header parameter name. This parameter is mandatory.
The name can be a registered header parameter name, a public header parameter name, or a private header parameter name and must be a string.
value
The protected header value. This parameter is mandatory.
The value is generally a string except for the following registered headers. Validation is done for specific headers.
  • b64 that is a Boolean.
  • exp that is a number.
  • http://openbanking.org.uk/iat that is a number.
  • iat that is a number.
  • nbf that is a number.
  • x5c that is an array.
JSON_object
A set of headers and values. This parameter is mandatory.
The headers parameter in the JSON object is merged into the protected header. New headers are added and existing headers are updated.

Guidelines

If the header parameter name or JSON object contain duplicate headers in either the shared unprotected header or recipient's unprotected header, an exception is issued.

JWEHeader.setUnprotected()

Sets an unprotected header name.

Syntax

JWEHeader.setUnprotected(name, value)

JWEHeader.setUnprotected(JSON_object)

Parameters

name
The protected header parameter name. This parameter is mandatory.
The header parameter name can be a registered header parameter name, a public header parameter name, or a private header parameter name and must be a string.
value
The protected header value. This parameter is mandatory.
The value must be a string and validation is done for specific headers.
JSON_object
A set of headers and values. This parameter is mandatory.
The headers parameter in the JSON object is merged into the unprotected header. New headers are added and existing headers are updated.

Guidelines

If header parameter name or JSON object contain duplicate headers in either the protected header or recipient's unprotected header, an exception is issued.

JWEHeader.addRecipient()

Adds a recipient with key management algorithm, key and unprotected headers.

Syntax

JWEHeader.addRecipient(key, algorithm, headers)

Parameters

key
The shared secret key or public key that is used by the algorithm to encrypt text.
The key must be.
  • A String object that refers to a configured object that also supports prefix usage in XSLT.
  • A Buffer or Buffers object that contains the base64 encoded data of a key.
  • An Object.
  • An RSA public key in JWK form or symmetric key in JWK form. For JWK requirements or limitations, see jwk.isJWK().
  • A JWK set. The 'kid' and 'alg' JOSE headers are used to find a proper JWK inside the JWK set. The 'kid' header is an optional string that the verifier can use to find the correct key to verify the signature.
For more information about formats when defining a key object, see Key object usage.
algorithm
The name of the algorithm to use. The following values are supported.
  • RSA1_5
  • RSA-OAEP
  • RSA-OAEP-256
  • A128KW
  • A192KW
  • A256KW
  • dir

RSA1_5, RSA-OAEP, and RSA-OAEP-256 are key encryption algorithms.

A128KW, A192KW, and A256KW are key wrapping algorithms.

dir is direct encryption with a shared symmetric key.

headers
The JSON object that contains the unprotected headers. The value cannot be an empty JSON object.

Guidelines

This method supports different usages.
Set the key for a recipient.
JWEHeader.addRecipient(key)
Set the key and algorithm for a recipient.
JWEHeader.addRecipient(key, algorithm)
Set the key, algorithm, and unprotected headers for a recipient.
JWEHeader.addRecipient(key, algorithm, headers)
Set the key and unprotected headers for a recipient.
JWEHeader.addRecipient(key, headers)
Set unprotected headers for a recipient.
JWEHeader.addRecipient(headers)

JWEHeader.setKey()

Sets a key object to process the Content Encryption Key (CEK) and output as a JWE Encrypted Key.

Syntax

JWEHeader.setKey(key)

Parameters

key
  • For all algorithms except the 'dir' algorithm, the agreed upon key to process the CEK.
  • For the 'dir' algorithm, the key to be used as the CEK.
The key must be.
  • A String object that refers to a configured object that also supports prefix usage in XSLT.
  • A Buffer or Buffers object that contains the base64 encoded data of a key.
  • An Object.
  • An RSA public key in JWK form or symmetric key in JWK form. For JWK requirements or limitations, see jwk.isJWK().
  • A JWK set. The 'kid' and 'alg' JOSE headers are used to find a proper JWK inside the JWK set. The 'kid' header is an optional string that the verifier can use to find the correct key to verify the signature.
For more information about formats when defining a key object, see Key object usage.

JWEHeader.getProtected()

Returns the JSON object of all name-value pairs.

Syntax

JWEHeader.getProtected(name)

Guidelines

If name is specified, the value of the named Header Parameter in the Protected Header is returned or 'undefined'. Otherwise, a JSON Object that contains all the Protected Header's Header Parameters is returned.

JWEHeader.getUnprotected()

Returns the JSON object of all name-value pairs

Syntax

JWEHeader.getUnprotected(name)

Guidelines

If name is specified, the value of the named Header Parameter in the Unprotected Header is returned or 'undefined'. Otherwise, a JSON Object that contains all the Protected Header's Header Parameters is returned.

JWEHeader.get()

Returns the shared JOSE Header or the value that is assigned to the named Header Parameter in the shared JOSE Header.

Syntax

JWEHeader.get([name])

Guidelines

If name is specified, the value of the name in the JOSE Header is returned. This JOSE Header Object represents only shared Header Parameters. It is a union of the shared Protected Header and shared Unprotected Header Parameters.

JWEHeader.getKey()

Returns the key value.

Syntax

JWEHeader.getKey()

JWEHeader.getRecipients()

Returns a JSON object of all defined recipients.

Syntax

JWEHeader.getRecipients()

jose.createJWEDecrypter()

Returns an instance of JWEDecrypter.

Syntax

jose.createJWEDecrypter(object)

Parameters

object
A JWEObject object that is returned.

jose.isJWEObject()

Verifies whether an object is a JWEObject.

Syntax

jose.isJWEObject(object)

Parameters

object
A JavaScript object.

jose.parse()

Parses a JWE representation and returns an instance of JWEObject.

Syntax

jose.parse(representation)

Parameters

representation
The representation that contains the serialized values for the JWE components. The representation can be a String, Buffer, Buffers, or a JSON object.

Guidelines

When you use compact serialization, the JWE components are base64url-encoded representations. If the representation is a Buffer or Buffers, it is converted to a String with the default encoding (UTF-8).

Parsing fails if the representation is formatted incorrectly.

JWEDecrypter class

The JWEDecrypter class does JWE decryption against the passed in JWE object.

The JWEDecrypter class provides the following class method.

JWEDecrypter.decrypt()

Decrypts and returns plaintext.

Syntax

JWEDecrypter.decrypt([,] function(error, plaintext) {...})

Parameters

output_encoding
The encoding of the plaintext. The value can be 'ascii' or 'utf8'. If no encoding is provided, then a Buffer is returned.

Examples

  • Compact serialization.
    var jose = require('jose');
// jwe object, compact serialization.
var compact_serialization = session.INPUT.getVar("compact_serialization");
var jweobj = jose.parse(compact_serialization);
jweobj.setKey("Alice");
jose.createJWEDecrypter(jweobj).decrypt(function(error, plaintext) {
    if (error) {
         session.output.write("jwe decrypt fail: "+error);
     } else {
         session.output.write(plaintext);
     }
});
  • JSON Serialization.
    var jose = require('jose');
session.input.readAsJSON(function(error, json) {
  if (error) {
    session.output.write("readAsJSON error: "+error);
  } else {
    var jweobj = jose.parse(json);
    var recipients = jweobj.getRecipients();
    for (var i = 0; i < recipients.length; i++) {
      if (recipients[i].get("alg") === 'RSA1_5') {
        recipients[i].setKey("Alice");
      }
    }
    jose.createJWEDecrypter(jweobj).decrypt(function(error, plaintext) {
      if (error) {
        session.output.write("jwe decrypt fail: "+error);
      } else {
        session.output.write(plaintext);
      }
    });
  }
});

JWEObject class

The JWEObject class contains all information that is processed from JWE JSON Serialization object.

The JWEObject class provides the following class methods.

JWEObject.get()

Returns the shared JOSE Header or the value that is assigned to the named Header Parameter in the shared JOSE Header.

Syntax

JWEObject.get([name])

Guidelines

If name is specified, the value of the name in the JOSE Header is returned. This JOSE Header Object represents only shared Header Parameters. It is a union of the shared Protected Header and shared Unprotected Header Parameters.

JWEObject.getProtected()

Returns the shared protected header as a JSON object.

Syntax

JWEObject.getProtected([name])

Guidelines

If name is specified, the value of the named Header Parameter in the Protected Header is returned or 'undefined'. Otherwise, a JSON Object that contains all the Protected Header's Header Parameters is returned.

JWEObject.getUnprotected()

Returns the shared unprotected header as a JSON object.

Syntax

JWEObject.getUnprotected([name])

Guidelines

If name is specified, the value of the named Header Parameter in the Unprotected Header is returned or 'undefined'. Otherwise, a JSON Object that contains all the Protected Header's Header Parameters is returned.

JWEObject.getRecipients()

Returns an array of recipient header objects.

Syntax

JWEObject.getRecipients()

Guidelines

Each JWERecipient header object presents each recipient's information.

JWEObject.getType()

Returns the serialization type of the JWE object.

Syntax

JWEObject.getType()

Guidelines

The serialization format can be 'compact' or 'json'.

JWEObject.setDirectKey()

Sets at shared secret key that is used for Direct Encryption.

Syntax

JWEObject.setDirectKey(key)

Parameters

key
A shared secret key that is used for Direct Encryption.
The key must be.
  • A String object that refers to a configured object that also supports prefix usage in XSLT.
  • A Buffer or Buffers object that contains the base64 encoded data of a key.
  • An Object.
  • A Symmetric key in JWK form. For JWK requirements or limitations, see jwk.isJWK().
  • A JWK set. The 'kid' and 'alg' JOSE headers are used to find a proper JWK inside the JWK set. The 'kid' header is an optional string that the verifier can use to find the correct key to verify the signature.
For more information about formats when defining a key object, see Key object usage.

Guidelines

This method works only when the Direct Encryption key management algorithm is employed.

JWEObject.setKey()

Sets a key object to process the Encrypted Key that determines the CEK.

Syntax

JWEObject.setKey(key)

Parameters

key
The agreed upon key to process the Encrypted Key.
The key must be.
  • A String object that refers to a configured object that also supports prefix usage in XSLT.
  • A Buffer or Buffers object that contains the base64 encoded data of the key.
  • An Object.
  • An RSA private key in JWK form or symmetric key in JWK form. For JWK requirements or limitations, see jwk.isJWK().
  • A JWK set. The 'kid' and 'alg' JOSE headers are used to find a proper JWK inside the JWK set. The 'kid' header is an optional string that the verifier can use to find the correct key to verify the signature.
For more information about formats when defining a key object, see Key object usage.

JWERecipient class

The JWERecipient class presents each recipient's information and settings.

The JWERecipient class provides the following class methods.

JWERecipient.get()

Returns the recipients Unprotected Header or the value that is assigned to the named Header Parameter in the recipients Unprotected Header or 'undefined'.

Syntax

JWERecipient.get([name])

Guidelines

If name is specified, the value of the name in the header object is returned.

JWERecipient.setKey()

Sets a key object to process the Encrypted Key that determines the CEK.

Syntax

JWERecipient.setKey(key)

Parameters

key
The agreed upon key to process the Encrypted Key.
The key must be.
  • A String object that refers to a configured object that also supports prefix usage in XSLT.
  • A Buffer or Buffers object that contains the base64 encoded data of the key.
  • An Object.
  • An RSA private key in JWK form or symmetric key in JWK form. For JWK requirements or limitations, see jwk.isJWK().
  • A JWK set. The 'kid' and 'alg' JOSE headers are used to find a proper JWK inside the JWK set. The 'kid' header is an optional string that the verifier can use to find the correct key to verify the signature.
For more information about formats when defining a key object, see Key object usage.

jose.createJWSHeader()

Creates a JWSHeader object.

Syntax

jose.createJWSHeader(key[, algorithm])

Parameters

key
The shared secret key or private key that is used by the algorithm to sign text. This parameter is mandatory. For information about key requirements, see RFC 7518: JSON Web Algorithms (JWA).
The key must be.
  • A String object that refers to a configured object that also supports prefix usage in XSLT.
  • A Buffer or Buffers object that contains the base64 encoded data of the key.
  • An Object.
  • An RSA private key in JWK form or symmetric key in JWK form. For JWK requirements or limitations, see jwk.isJWK().
  • A JWK set. The 'kid' and 'alg' JOSE headers are used to find a proper JWK inside the JWK set. The 'kid' header is an optional string that the verifier can use to find the correct key to verify the signature.
For more information about formats when defining a key object, see Key object usage.

The key can also be assigned by using JWSHeader.setKey().

algorithm
The name of the algorithm to use. This parameter is optional. The following values are supported.
  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • ES256
  • ES384
  • ES512
  • PS256
  • PS384
  • PS512

Although you can use PSxxx algorithms, HSM acceleration for these algorithms applies to only appliances with the HSM 3 (hsm3) accelerator.

Guidelines

When the algorithm parameter is not specified in the jose.createJWSHeader() API, a header parameter value for the algorithm must be added to the JWSHeader object when you call the jose.createJWSSigner() API.

jose.createJWSSigner()

Returns a JWSSigner object.

Syntax

jose.createJWSSigner(header1, [header2...headerN)

Parameters

header
A JWSHeader object. This parameter is mandatory.

Guidelines

Multiple header parameters are only supported in JSON serialization. This function accepts an array of JWSHeader objects and a single JWSHeader object for any parameters that are passed in.

The algorithm header parameters and key object must be set in the JWS header before it is passed into jose.createJWSSigner().

jose.getJWSAlg()

Returns a supported algorithm list for JWS signing.

Syntax

jose.getJWSAlg()

jose.isJWSHeader()

Syntax

jose.isJWSHeader(object)

Parameters

object
A JavaScript object.

JWSHeader class

The JWSHeader class is used to create a single JWS signature. It provides API to set a protected header, an unprotected header, headers parameters, an algorithm, and a key.

The JWSHeader class provides the following class methods.

JWSHeader.setProtected()

Sets the header parameters of the protected header object.

Syntax

JWSHeader.setProtected(name, value)

JWSHeader.setProtected(object)

Parameters

name
The protected header parameter name. This parameter is mandatory.
value
The protected header value. This parameter is mandatory.
object
A set of headers and values. This parameter is mandatory.

Guidelines

The value is generally a string except for the following registered headers. Validation is done for specific headers.
  • b64 that is a Boolean.
  • exp that is a number.
  • http://openbanking.org.uk/iat that is a number.
  • iat that is a number.
  • nbf that is a number.
  • x5c that is an array.

The call fails if the name parameter is already set in JWSHeader.setUnprotected().

JWSHeader.setUnprotected()

Sets the header parameters of the unprotected header object.

Syntax

JWSHeader.setUnprotected(name, value)

JWSHeader.setUnprotected(object)

Parameters

name
The protected header parameter name. This parameter is mandatory.
value
The protected header value. This parameter is mandatory.
object
A set of headers and values. This parameter is mandatory.

Guidelines

The name can be a registered header parameter name, a public header parameter name, or a private header parameter name.

The call fails if the name parameter is already set in JWSHeader.setProtected().

JWSHeader.getProtected()

Returns the protected header as a JSON object.

Syntax

JWSHeader.getProtected([name])

Guidelines

If name is specified, the value of the named Header Parameter in the Protected Header is returned or 'undefined'. Otherwise, a JSON Object that contains all the Protected Header's Header Parameters is returned.

JWSHeader.getUnprotected()

Returns the shared unprotected header as a JSON object.

Syntax

JWSHeader.getUnprotected([name])

Guidelines

If name is specified, the value of the named Header Parameter in the Unprotected Header is returned or 'undefined'. Otherwise, a JSON Object that contains all the Protected Header's Header Parameters is returned.

JWSHeader.setKey()

Sets the key value.

Syntax

JWSHeader.setKey([key])

Parameters

key
The shared secret key that is used by the algorithm to encrypt text. This parameter is mandatory.
The key must be.
  • A String object that refers to a configured object that also supports prefix usage in XSLT.
  • A Buffer or Buffers object that contains the base64 encoded data of the key.
  • An Object.
  • An RSA private key in JWK form or symmetric key in JWK form. For JWK requirements or limitations, see jwk.isJWK().
  • A JWK set. The 'kid' and 'alg' JOSE headers are used to find a proper JWK inside the JWK set. The 'kid' header is an optional string that the verifier can use to find the correct key to verify the signature.
For more information about formats when defining a key object, see Key object usage.

JWSHeader.getJOSEHeader()

Returns the JOSE header.

Syntax

JWSHeader.getJOSEHeader()

JWSHeader.get()

Returns the shared JOSE Header or the value that is assigned to the named Header Parameter in the shared JOSE Header.

Syntax

JWSHeader.get([name])

Guidelines

If name is specified, the value of the name in the JOSE Header is returned. This JOSE Header Object represents only shared Header Parameters. It is a union of the shared Protected Header and shared Unprotected Header Parameters.

JWSHeader.getKey()

Returns the key value.

Syntax

JWSHeader.getKey()

JWSSigner class

The JWSSigner class is used for the digital sign or MAC operation.

The JWSSigner class provides the following class methods.

JWSSigner.update()

Populates the payload into a JWS signature object.

Syntax

JWSSigner.update(payload)

Parameters

payload
A sequence of octets to be secured. The payload must be String, Buffer, or Buffers. Call JSON.stringify() before you pass the payload into this function if needed.

JWSSigner.sign()

Signs the JWS content.

Syntax

JWSSigner.sign([format], function(error, JWS))

Parameters

format
The serialization format, which is a string that is 'compact', 'json', or 'json_flat'. The default value is 'compact'.
  • 'compact' indicates the compact serialization.
  • 'json' indicates the general JSON serialization.
  • 'json_flat' indicates the flattened JOSN serialization. Flattened JSON serialization is available when only one signature exists.
.
error
The error information if an error occurs.
JWS
The output of the signature.

Examples

  • Compact serialization.
    var jose = require('jose');
// compact serialization
var hdr = jose.createJWSHeader(key, 'HS256');
var mySign = jose.createJWSSigner(hdr);
mySign.update("A string to sign");
mySign.sign('compact',function(error, JWSstring) {
  if (error) {
    session.output.write("jws sign fail: "+error);
  } else {
    session.output.write(jwsString);
  }
});
  • General JSON serialization.
    var jose = require('jose');
// JSON serialization
var hdr1 = jose.createJWSHeader(key, 'HS256');
hdr1.setUnprotected({'kid': "kid1"});
var hdr2 = jose.createJWSHeader(key);
hdr2.setUnprotected('alg', 'RS256');
hdr2.setUnprotected('kid', "kid2");
var mySign = jose.createJWSSigner(hdr1,hdr2);
mySign.update("A string to sign");
mySign.sign('json',function(error, JWSstring) {
  if (error) {
    session.output.write("jws sign fail: "+error);
  } else {
    session.output.write(JWSstring);
  }
});
  • Flattened JSON serialization.
    var jose = require('jose');
// compact serialization
var hdr = jose.createJWSHeader(key, 'HS256');
var mySign = jose.createJWSSigner(hdr);
mySign.update("A string to sign");
mySign.sign('json_flat',function(error, JWSstring) {
  if (error) {
    session.output.write("jws sign fail: "+error);
  } else {
    session.output.write(jwsString);
  }
});

jose.createJWSVerifier()

Creates a JWSVerifier object.

Syntax

jose.createJWSVerifier(object)

Parameters

object
A JWSObject object.

jose.isJWSObject()

Verifies whether an object is a JWSObject.

Syntax

jose.isJWSObject(object)

Parameters

object
A JavaScript object.

jose.parse()

Parses a JWS representation and returns an instance of JWSObject.

Syntax

jose.parse(representation)

Parameters

representation
The representation that contains the serialized values for the components for the JWS. The representation can be a String, Buffer, Buffers, or a JSON object.

Guidelines

For compact serialization, the JWS components are base64url-encoded representations. If the representation is a Buffer or Buffers, it is converted to a String with the default UTF-8 encoding.

Parsing fails if not correctly formatted.

JWSObject class

The JWSObject class is used to extract serialized values for the components of the JWS.

The JWSObject class provides the following class methods.

JWSObject.getSignatures()

Returns the array of JWSSignedHeader objects.

Guidelines

Each JWSSignedHeader object contains all parsed per-signature data.

JWSObject.getPayload()

Returns a base64url decoded payload value.

Syntax

JWSObject.getPayload()

JWSObject.getType()

Returns the serialization type of the JWS.

Syntax

JWSObject.getType()

Guidelines

The serialization format can be 'compact' or 'json'

JWSSignedHeader class

The JWSSignedHeader class is used to extract serialized values for the per-Signature components of the JWS.

The JWSSignedHeader class provides the following class methods.

JWSSignedHeader.get()

Returns the JOSE Header or the value that is assigned to the named Header Parameter in the JOSE Header.

Syntax

JWSSignedHeader.get([name])

Guidelines

If name is specified, the value of the name in the JOSE Header is returned. This JOSE Header Object is a union of the Protected Header and Unprotected Header Parameters.

JWSSignedHeader.getSignature()

Returns the signature value.

Syntax

JWSSignedHeader.getSignature()

JWSSignedHeader.getProtected()

Returns the JSON object of all name-value pairs.

Syntax

JWSSignedHeader.getProtected([name])

Guidelines

If name is specified, the value of the named Header Parameter in the Protected Header is returned or 'undefined'. Otherwise, a JSON Object that contains all the Protected Header's Header Parameters is returned.

JWSSignedHeader.getUnprotected()

Returns the JSON object of all name-value pairs.

Syntax

JWSSignedHeader.getUnprotected([name])

Guidelines

If name is specified, the value of the named Header Parameter in the Unprotected Header is returned or 'undefined'. Otherwise, a JSON Object that contains all the Protected Header's Header Parameters is returned.

JWSSignedHeader.setKey()

Sets the key certificate necessary to verify the signature.

Syntax

JWSSignedHeader.setKey(key)

Parameters

key
The shared secret key or public key that is used by the algorithm to encrypt text.
The key must be.
  • A String object that refers to a configured object that also supports prefix usage in XSLT.
  • A Buffer or Buffers object that contains the base64 encoded data of a key.
  • An Object.
  • An RSA public key in JWK form or symmetric key in JWK form. For JWK requirements or limitations, see jwk.isJWK().
  • A JWK set. The 'kid' and 'alg' JOSE headers are used to find a proper JWK inside the JWK set. The 'kid' header is an optional string that the verifier can use to find the correct key to verify the signature.
For more information about formats when defining a key object, see Key object usage.

JWSVerifier class

The JWSVerifier class is used to validate all data necessary to verify the received signature.

The JWSVerifier class provides the following class method.

JWSVerifier.validate()

Validates all data necessary to verify the received signature.

Syntax

JWSVerifier.validate(function(error) {...})

Parameters

function
A callback function that is run when JWS verify is done.
error
The error information if an error occurs.

Example

JWS Sign followed by JWS Validate.
var hdr = jose.createJWSHeader(key, alg);
hdr.setProtected({'kid': kid1});
var mySign = jose.createJWSSigner(hdr).update(payloadString,'utf8').sign(jwsType, function(error,jwsObj){
  if(error) throw new Error(error);
  else {
    //Parse of the JWS successful
    //Access the per-signature data and set key to mark the signature for verification
    var jwsSignedObject    = jose.parse(jwsObj);
    var signedJWSHeaders   = jwsSignedObject.getSignatures();
    for (var i = 0; i < signedJWSHeaders.length; i++) {
      var hdr2 = signedJWSHeaders[i];
      var kid = hdr2.get('kid');
      switch (kid) {
        case kid1:
        case kid2:
          hdr2.setKey(key);
        break;
        default:
        break;
      }
    }
    var myValidator = jose.createJWSVerifier(jwsSignedObject);
    //Validate all signatures for which a key has been set
    //At least one signature must have key set
    myValidator.validate( function(error){ 
      if (error) {
        console.error("validate fail: "+error);
        throw new Error(error);
      } else {
        //All signature verifications have succeeded
        return jwsSignedObject.getPayload();
      }
    });
  });