Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

1481 lines (1126 sloc) 52.6 KB

jose API Documentation

"JSON Web Almost Everything" - JWA, JWS, JWE, JWT, JWK, JWKS for Node.js with minimal dependencies

Table of Contents

Sponsor

auth0-logo If you want to quickly add secure token-based authentication to Node.js projects, feel free to check Auth0’s free plan at auth0.com/overview.

Support

If you or your business use jose, please consider becoming a sponsor so I can continue maintaining it and adding new features carefree.



JWK (JSON Web Key)

All jose operations require <JWK.Key> or <JWKS.KeyStore> as arguments. Here's how to get a <JWK.Key> instances generated or instantiated from existing key material.

const { JWK } = require('jose')
// { asKey: [Function: asKey],
//   generate: [AsyncFunction: generate],
//   generateSync: [Function: generateSync] }

Class: <JWK.Key> and <JWK.RSAKey> | <JWK.ECKey> | <JWK.OKPKey> | <JWK.OctKey>

<JWK.RSAKey>, <JWK.ECKey>, <JWK.OKPKey> and <JWK.OctKey> represent a key usable for JWS and JWE operations. The JWK.asKey() method is used to retrieve a key representation of an existing key or secret. JWK.generate() method is used to generate a new random key.

<JWK.RSAKey>, <JWK.ECKey>, <JWK.OKPKey> and <JWK.OctKey> inherit methods from <JWK.Key> and in addition to the properties documented below have the respective key component properties exported as <string> in their format defined by the specifications.

  • e, n for Public RSA Keys
  • e, n, d, p, q, dp, dq, qi for Private RSA Keys
  • crv, x, y for Public EC Keys
  • crv, x, y, n for Private EC Keys
  • crv, x for Public OKP Keys
  • crv, x, n for Private OKP Keys
  • k for Symmetric keys

key.kty

Returns the key's JWK Key Type Parameter. 'EC', 'RSA', 'OKP' or 'oct' for the respective supported key types.

  • <string>

key.alg

Returns the key's JWK Algorithm Parameter if set, undefined otherwise. If set the key is only usable for that one algorithm and will fail when used with others.

  • <string>

key.use

Returns the key's JWK Key Use Parameter if set, undefined otherwise. Only 'sig' and 'enc' values are supported. If set the key can only be used for either signing / verification or encryption related operations (key management or encryption).

  • <string>

key.kid

Returns the key's JWK Key ID Parameter if set, if not set it will be calculated using the method defined in RFC7638.

  • <string>

key.x5c

Returns the key's X.509 Certificate Chain Parameter if set

  • string[]

key.x5t

Returns the key's X.509 Certificate SHA-1 Thumbprint Parameter if set. This property can be either set manually by the JWK producer or left to the library to compute based on the first certificate in the key's x5c, the latter is preferred.

  • <string>

key['x5t#S256']

Returns the key's X.509 Certificate SHA-256 Thumbprint Parameter if set. This property can be either set manually by the JWK producer or left to the library to compute based on the first certificate in the key's x5c, the latter is preferred.

  • <string>

key.key_ops

Returns the key's JWK Key Operations Parameter if set. If set the key can only be used for the specified operations. Supported values are 'sign', 'verify', 'encrypt', 'decrypt', 'wrapKey', 'unwrapKey' and 'deriveKey'.

  • string[]

key.thumbprint

Returns the key's JWK Key thumbprint calculated using the method defined in RFC7638.

  • <string>

key.type

Returns the type of key. One of 'private', 'public' or 'secret'

  • <string>

key.public

Returns true/false if the key is asymmetric and public. Returns false for symmetric keys.

  • <boolean>

key.private

Returns true/false if the key is asymmetric and private. Returns false for symmetric keys.

  • <boolean>

key.secret

Returns true/false if the key is symmetric. Returns false for asymmetric keys.

  • <boolean>

key.algorithms([operation])

Returns a Set of algorithms the key may perform.

  • operation: <string> Must be one of 'encrypt', 'decrypt', 'sign', 'verify', 'wrapKey', 'unwrapKey'
  • Returns: Set<string>
Example (Click to expand)
const { JWK: { generateSync } } = require('jose')

const privateKey = generateSync('RSA')
privateKey.algorithms()
// Set {
//  'PS256',
//  'RS256',
//  'PS384',
//  'RS384',
//  'PS512',
//  'RS512',
//  'RSA-OAEP',
//  'RSA-OAEP-256',
//  'RSA1_5' }
privateKey.algorithms('wrapKey')
// Set {
//  'RSA-OAEP',
//  'RSA-OAEP-256',
//  'RSA1_5' }

const publicKey = generateSync('RSA', 2048, { use: 'enc' }, false)
publicKey.algorithms('sign')
// Set {}
publicKey.algorithms('unwrapKey')
// Set {}
publicKey.algorithms('wrapKey')
// Set {
//  'RSA-OAEP',
//  'RSA-OAEP-256',
//  'RSA1_5' }

key.toJWK([private])

Exports the key to a JSON Web Key formatted object.

  • private: <boolean> When true exports keys with its private components. Default: 'false'
  • Returns: <Object>
Example (Click to expand)
const { JWK: { generateSync } } = require('jose')

const key = generateSync('RSA', 2048, { use: 'sig', alg: 'PS256' })
key.toJWK()
// { kty: 'RSA',
//   kid: 'UFldqYiAzlc1aGj5SoqxqYnWcv2Nc4us2ryQe3-FsUA',
//   e: 'AQAB',
//   n:
//    'uKEKEJUrnfBdXr6zmzq91fQHhW_8GFFUAYtvt5Uvj9wzsWDbspfL9MorhJgkPioo9T6QQvyyEJBaAQOLZxLsPORk83vmB9OACQT3PEM2LbSFK7XUoZGwqlf8Anvs7M1GwvypYbc1v1WrCqcsjrbmYF9TZkV8nNsy2cweh9gFNR-lIiZCHWDgnP6PifoeGvC9RxKdusFa66vtUJGUcoVmMoiOM7EDVdYOP91qJtbDBx7NPPywwD-8pt3UVBW0bYvOqHGF6XXky5JiB8AZQ2NdZHWxklaM2fd8Mxu9CT3xSYg51nS0KV7wO9lAh_ynBpxE2Qmr-7nvKkkDMOL1FSoEQw',
//   alg: 'PS256',
//   use: 'sig' }
key.toJWK(true)
// { kty: 'RSA',
//   kid: 'UFldqYiAzlc1aGj5SoqxqYnWcv2Nc4us2ryQe3-FsUA',
//   e: 'AQAB',
//   n:
//    'uKEKEJUrnfBdXr6zmzq91fQHhW_8GFFUAYtvt5Uvj9wzsWDbspfL9MorhJgkPioo9T6QQvyyEJBaAQOLZxLsPORk83vmB9OACQT3PEM2LbSFK7XUoZGwqlf8Anvs7M1GwvypYbc1v1WrCqcsjrbmYF9TZkV8nNsy2cweh9gFNR-lIiZCHWDgnP6PifoeGvC9RxKdusFa66vtUJGUcoVmMoiOM7EDVdYOP91qJtbDBx7NPPywwD-8pt3UVBW0bYvOqHGF6XXky5JiB8AZQ2NdZHWxklaM2fd8Mxu9CT3xSYg51nS0KV7wO9lAh_ynBpxE2Qmr-7nvKkkDMOL1FSoEQw',
//   d:
//    'F9G24bLNAMBM23dQ5prqeNrVyZJL_LspUlWx4QZfL3kiNiUf0uegiYE3ohCaxGZeCF288Nd3BYoKAo15g5--WJDCsWLvp1zS7Nb2KpElQTpD4ALCXuHT3_Yf7hYc1-QX1_oOxCuFxJyBx4sPxY21JQPHV69pRzdEVTLvUWk-Kr8k-kgu8xFOsyqLK0g0IBAtwOX2ksIPLuHT-nGh_VQwfpJowq1MoUZD-y_6Ai5HWAZy9t6gARpG3K4yBcmAQBRIQgoFiGw41BqVB5fJyjVZDsMbvT_iEFKkrHRjifUI6QTNtt1k9xOFIL_Ojzn6aLylm58AGD8oORWZvfpmJJ03yQ',
//   p:
//    '8lvcv5Ov9rJsa_kaCJBRijeOdz3La11_26o2QDpkINFKKoDNWRpIT0KZNF4P16Z5OXOK6rSezuN2vACAPg3riUHVdbRyFhMI6FvQhlx7unyv07xBBqbnp8dV2NiQv3-rFeNPV_5RqZHJyqQga-VUXvwics3eUzm_2CbrMQG3Klc',
//   q:
//    'wwVZ6d5uZm9kj3tWICF1FqCWHwSWMt1wgFZ3DOp2LPuqBHjYPas4zwXd3V4wolaCi8irbTfbL0F6c51yN72-enAjgm6r5yzxedkV9GWk5U0y8VrNwYm55qz1o88LB6PX6RG5Lp2rYZp_34dgCrllQc8T-5YY4KIHy7TaLkKkGfU',
//   dp:
//    'sPZseCIxcPOVAT3xSWF_eGnah6zCVJH_4vglBr7cD65h9ij4R-BN_jnFvhwUe0Ud7No2C-x4rN4f-2RuP2FQo3dDkt-AEigx79_iocjzuxaCGBu0a1QBgFunjl-LSZjB5oiEjd6v6B4AdwtidQYNlhGKYcN6W9CmCQFZ5_21rZ8',
//   dq:
//    'sokKmGSuUw61U_mIjh-zDoTzCfBsBKLepE8D7AoVJ_c43aE37bT7a-MmCst44JUsLAYIkhMpkKh0DrXb45XMdFCG4ZipvRhS9Ma9J6GKBPXYpkYHyZ9pVfmPY2he456mQdOc4UUsqU0EtcE8NnUlcsq9s3vkyHjthBrMBr-xdaU',
//   qi:
//    'jbZrzP8f3y0-ZAjqSQAPbKnQI0Vli952nQTUgffF2Bh2q0dB719PHjmIV7NjwCFOMcNx-2usJFwI9VikgN9GTGauakvG7SFzXD8yHiRzFwcjYvXDuJ-4Q1Yjo1m4JUIW_BLVnzauSg0P9qnxT1dxvchEQRIIfF72FW80BsJD4LQ',
//   alg: 'PS256',
//   use: 'sig' }

key.toPEM([private[, encoding]])

Exports an asymmetric key as a PEM string with specified encoding and optional encryption for private keys.

  • private: <boolean> When true exports keys as private. Default: 'false'
  • encoding: <Object> See below
  • Returns: <string>

For public key export, the following encoding options can be used:

  • type: <string> Must be one of 'pkcs1' (RSA only) or 'spki'. Default: 'spki'

For private key export, the following encoding options can be used:

  • type: <string> Must be one of 'pkcs1' (RSA only), 'pkcs8' or 'sec1' (EC only). Default: 'pkcs8'
  • cipher: <string> If specified, the private key will be encrypted with the given cipher and passphrase using PKCS#5 v2.0 password based encryption. Default: 'undefined' (no encryption)
  • passphrase: <string> | <Buffer> The passphrase to use for encryption. Default: 'undefined' (no encryption)
Example (Click to expand)
const { JWK: { generateSync } } = require('jose')

const key = generateSync('RSA', 2048)
key.toPEM()
// -----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEATPpxgDY7XU8cYX9Rb44xxXDO6zP\nzELVOHTcutCiXS9HZvUrZsnG7U/SPj0AT1hsH6lTUK4uFr7GG7KWgsf1Aw==\n-----END PUBLIC KEY-----\n
key.toPEM(true)
// -----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgUdAzlvX4i+RJS2BL\nQrqRj/ndTbpqugX61Ih9X+rvAcShRANCAAQBM+nGANjtdTxxhf1FvjjHFcM7rM/M\nQtU4dNy60KJdL0dm9StmycbtT9I+PQBPWGwfqVNQri4WvsYbspaCx/UD\n-----END PRIVATE KEY-----\n
key.toPEM(true, { passphrase: 'super-strong', cipher: 'aes-256-cbc' })
// -----BEGIN ENCRYPTED PRIVATE KEY-----\nMIHsMFcGCSqGSIb3DQEFDTBKMCkGCSqGSIb3DQEFDDAcBAjjeqsgorjSqwICCAAw\nDAYIKoZIhvcNAgkFADAdBglghkgBZQMEASoEEJFcyG1ZBe2FZuvXIqiRFUcEgZD5\nWzt2XIUGIEZQIUUpJ1naaIFKiZvBcFAXhqG5KJ6PgaohgcmRUK8OZTA9Ome+uXB+\n9PLLfKscOsyr0gkd45gYYNRDLYwbQSqDQ4g8pHrCVjR+R3mh1nk8jIkOxSppwzmF\n7aoCmnQo7oXRy1+kRZL7OfwAD5gAXnsIA42D9RgOG1XIiBYTvAITcFVX0UPh0zM=\n-----END ENCRYPTED PRIVATE KEY-----\n

JWK.asKey(key[, options]) asymmetric key import

Imports an asymmetric private or public key. Supports importing JWK formatted keys (private, public, secrets), pem and der formatted private and public keys, pem formatted X.509 certificates. Private keys may also be passphrase protected.

  • key: <Object> | <string> | <Buffer> | <KeyObject>
    • key: <string> | <Buffer>
    • format: <string> Must be 'pem' or 'der'. Default: 'pem'.
    • type: <string> Must be 'pkcs1', 'pkcs8' or 'sec1'. This option is required only if the format is 'der' and ignored if it is 'pem'.
    • passphrase: <string> | <Buffer> The passphrase to use for decryption.
  • options: <Object>
    • alg: <string> option identifies the algorithm intended for use with the key.
    • kid: <string> Key ID Parameter. When not provided is computed using the method defined in RFC7638
    • use: <string> option indicates whether the key is to be used for encrypting & decrypting data or signing & verifying data. Must be 'sig' or 'enc'.
  • Returns: <JWK.RSAKey> | <JWK.ECKey> | <JWK.OKPKey>

See the underlying Node.js API for details on importing private and public keys in the different formats

Example (Click to expand)
const { readFileSync } = require('fs')
const { JWK: { asKey } } = require('jose')

const key = asKey(readFileSync('path/to/key/file'))
// ECKey {
//   kty: 'EC',
//   public: true,
//   kid: [Getter],
//   crv: [Getter],
//   x: [Getter],
//   y: [Getter] }

JWK.asKey(secret[, options]) secret key import

Imports a symmetric key.

  • secret: <string> | <Buffer> | <KeyObject>
  • options: <Object>
    • alg: <string> option identifies the algorithm intended for use with the key.
    • kid: <string> Key ID Parameter. When not provided is computed using the method defined in RFC7638
    • use: <string> option indicates whether the key is to be used for encrypting & decrypting data or signing & verifying data. Must be 'sig' or 'enc'.
  • Returns: <JWK.OctKey>
Example (Click to expand)
const { JWK: { asKey } } = require('jose')

const key = asKey(Buffer.from('8yHym6h5CG5FylbzrCn8fhxEbp3kOaTsgLaawaaJ'))
// OctKey {
//   kty: 'oct',
//   kid: [Getter],
//   k: [Getter] }

JWK.asKey(jwk[, options]) JWK-formatted key import

Imports a JWK formatted key. This supports JWK formatted RSA, EC, OKP and oct keys. Asymmetrical keys may be both private and public.

  • jwk: <Object>
    • kty: <string> Key type. Must be 'RSA', 'EC', 'OKP' or 'oct'.
    • alg: <string> option identifies the algorithm intended for use with the key.
    • use: <string> option indicates whether the key is to be used for encrypting & decrypting data or signing & verifying data. Must be 'sig' or 'enc'.
    • kid: <string> Key ID Parameter. When not provided is computed using the method defined in RFC7638
    • e, n properties as <string> for RSA public keys
    • e, n, d, p, q, dp, dq, qi properties as <string> for RSA private keys
    • e, n, d properties as <string> for RSA private keys without optimization parametes (only with calculateMissingRSAPrimes option, see below)
    • crv, x, y properties as <string> for EC public keys
    • crv, x, y, d properties as <string> for EC private keys
    • crv, x, properties as <string> for OKP public keys
    • crv, x, d properties as <string> for OKP private keys
    • k properties as <string> for secret oct keys
  • options: <Object>
    • calculateMissingRSAPrimes: <boolean> Default 'false'. This option is really only in effect when importing private RSA JWK keys, by default, keys without the optimization private key parameters (p, q, dp, dq, qi) won't imported because their calculation is heavy and prone to blocking the process. Setting this option to true will enable these keys to be imported, albeit at your own risk. Depending on the key size the calculation takes long and it should only be used for JWK keys from trusted sources.
  • Returns: <JWK.RSAKey> | <JWK.ECKey> | <JWK.OKPKey> | <JWK.OctKey>
Example (Click to expand)
const { JWK: { asKey } } = require('jose')
const jwk = {
  kty: 'RSA',
  kid: 'r1LkbBo3925Rb2ZFFrKyU3MVex9T2817Kx0vbi6i_Kc',
  use: 'sig',
  e: 'AQAB',
  n: 'xwQ72P9z9OYshiQ-ntDYaPnnfwG6u9JAdLMZ5o0dmjlcyrvwQRdoFIKPnO65Q8mh6F_LDSxjxa2Yzo_wdjhbPZLjfUJXgCzm54cClXzT5twzo7lzoAfaJlkTsoZc2HFWqmcri0BuzmTFLZx2Q7wYBm0pXHmQKF0V-C1O6NWfd4mfBhbM-I1tHYSpAMgarSm22WDMDx-WWI7TEzy2QhaBVaENW9BKaKkJklocAZCxk18WhR0fckIGiWiSM5FcU1PY2jfGsTmX505Ub7P5Dz75Ygqrutd5tFrcqyPAtPTFDk8X1InxkkUwpP3nFU5o50DGhwQolGYKPGtQ-ZtmbOfcWQ'
}

const key = asKey(jwk)
// RSAKey {
//   kty: 'RSA',
//   public: true,
//   use: 'sig',
//   kid: 'r1LkbBo3925Rb2ZFFrKyU3MVex9T2817Kx0vbi6i_Kc',
//   e: [Getter],
//   n: [Getter] }

JWK.generate(kty[, crvOrSize[, options[, private]]]) generating new keys

Securely generates a new RSA, EC, OKP or oct key.

  • kty: <string> Key type. Must be 'RSA', 'EC', 'OKP' or 'oct'.
  • crvOrSize: <number> | <string> key's bit size or in case of OKP and EC keys the curve Default: 2048 for RSA, 'P-256' for EC, 'Ed25519' for OKP and 256 for oct.
  • options: <Object>
    • alg: <string> Key Algorithm Parameter. It identifies the algorithm intended for use with the key.
    • kid: <string> Key ID Parameter. When not provided is computed using the method defined in RFC7638.
    • use: <string> Public Key Use Parameter. Indicates whether the key is to be used for encrypting & decrypting data or signing & verifying data. Must be 'sig' or 'enc'.
    • key_ops: string[] Key Operations Parameter. If set, the key can only be used for the specified operations. Supported values are 'sign', 'verify', 'encrypt', 'decrypt', 'wrapKey', 'unwrapKey' and 'deriveKey'.
  • private: <boolean> Default 'true'. Is the resulting key private or public (when asymmetrical)
  • Returns: Promise<JWK.RSAKey> | Promise<JWK.ECKey> | Promise<JWK.OKPKey> | Promise<JWK.OctKey>
Example (Click to expand)
const { JWK: { generate } } = require('jose')
(async () => {
  const key = await generate('EC', 'P-384', { use: 'sig' })
  // ECKey {
  //   kty: 'EC',
  //   private: true,
  //   use: 'sig',
  //   kid: [Getter],
  //   crv: [Getter],
  //   x: [Getter],
  //   y: [Getter],
  //   d: [Getter] }
})()

JWK.generateSync(kty[, crvOrSize[, options[, private]]])

Synchronous version of JWK.generate()

  • kty: <string> Key type. Must be 'RSA', 'EC', 'OKP' or 'oct'.
  • crvOrSize: <number> | <string> key's bit size or in case of OKP and EC keys the curve. Default: 2048 for RSA, 'P-256' for EC, 'Ed25519' for OKP and 256 for oct.
  • options: <Object>
    • alg: <string> Key Algorithm Parameter. It identifies the algorithm intended for use with the key.
    • kid: <string> Key ID Parameter. When not provided is computed using the method defined in RFC7638.
    • use: <string> Public Key Use Parameter. Indicates whether the key is to be used for encrypting & decrypting data or signing & verifying data. Must be 'sig' or 'enc'.
    • key_ops: string[] Key Operations Parameter. If set, the key can only be used for the specified operations. Supported values are 'sign', 'verify', 'encrypt', 'decrypt', 'wrapKey', 'unwrapKey' and 'deriveKey'.
  • private: <boolean> Default 'true'. Is the resulting key private or public (when asymmetrical)
  • Returns: <JWK.RSAKey> | <JWK.ECKey> | <JWK.OKPKey> | <JWK.OctKey>
Example (Click to expand)
const { JWK: { generateSync } } = require('jose')
const key = generateSync('RSA', 2048, { use: 'enc' })
// RSAKey {
//   kty: 'RSA',
//   private: true,
//   use: 'enc',
//   kid: [Getter],
//   e: [Getter],
//   n: [Getter],
//   d: [Getter],
//   p: [Getter],
//   q: [Getter],
//   dp: [Getter],
//   dq: [Getter],
//   qi: [Getter] }

JWK.isKey(object)

Returns 'true' if the value is an instance of <JWK.Key>.

  • object: <any>
  • Returns: <boolean>

JWKS (JSON Web Key Set)

const { JWKS } = require('jose')
// { KeyStore: [Function: KeyStore] }

Class: <JWKS.KeyStore>

JWKS.KeyStore is an abstraction representing a set of JWKs, a keystore instance may be queried for keys matching specific parameters. Keystores may be instantiated either populated, or empty and there are lifecycle keystore.remove() and keystore.add() methods for adding/removing keys from an existing store.


new JWKS.KeyStore([keys])

Creates a new KeyStore, either empty or populated.

  • keys: <JWK.Key[]> Array of key keys instantiated by JWK.asKey()
  • Returns: <JWKS.KeyStore>

keystore.size

Returns the number of keys in the keystore.

  • <number>

keystore.all([parameters])

Retrieves an array of keys matching the provided parameters, returns all if none are provided. The returned array is sorted by relevance based on the parameters. Keys with the exact algorithm or use specified by the parameters are first.

  • parameters: <Object>
    • kty: <string> Key Type to filter for.
    • alg: <string> Key supported algorithm to filter for.
    • kid: <string> Key ID to filter for.
    • use: <string> Filter keys with the specified use defined. Keys missing "use" parameter will be matched but rank lower then ones with an exact match.
    • key_ops: string[] Filter keys with specified key_ops defined (if key_ops is defined on the key). Keys missing "key_ops" parameter will be matched but rank lower then ones with matching entries.
  • Returns: <Key[]> Array of key instances or an empty array when none are matching the parameters.

keystore.get([parameters])

Retrieves a single key matching the provided parameters. The most relevant Key based on the parameters is returned.

  • parameters: <Object>
    • kty: <string> Key Type to filter for.
    • alg: <string> Key supported algorithm to filter for.
    • kid: <string> Key ID to filter for.
    • use: <string> Filter keys with the specified use defined. Keys missing "use" parameter will be matched but rank lower then ones with an exact match.
    • key_ops: string[] Filter keys with specified key_ops defined (if key_ops is defined on the key). Keys missing "key_ops" parameter will be matched but rank lower then ones with matching entries.
  • Returns: <JWK.RSAKey> | <JWK.ECKey> | <JWK.OKPKey> | <JWK.OctKey> | <undefined>

keystore.add(key)

Adds a key instance to the store unless it is already included.

  • key: <JWK.RSAKey> | <JWK.ECKey> | <JWK.OKPKey> | <JWK.OctKey>

keystore.remove(key)

Ensures a key is removed from a store.

  • key: <JWK.RSAKey> | <JWK.ECKey> | <JWK.OKPKey> | <JWK.OctKey>

keystore.generate(...)

Asynchronously generates new random key and automatically adds it to the store. See JWK.generate() for the API.


keystore.generateSync(...)

Synchronous version of keystore.generate().


keystore.toJWKS([private])

Exports the keystore to a JSON Web Key Set formatted object.

  • private: <boolean> When true exports private keys with their private components. Default: 'false'
  • Returns: <Object>

JWKS.asKeyStore(jwks[, options])

Creates a new KeyStore from a JSON Web Key Set.

  • jwks: <Object> JWKS formatted object ({ keys: [{ kty: '...', ... }, ...] })
  • options: <Object>
    • ignoreErrors: <boolean> Default 'false'. This will make it so that keys unsupported by your Node.js runtime version (or otherwise faulty keys) get swallowed.
    • calculateMissingRSAPrimes: <boolean> Default 'false'. This option is really only in effect when the JWKS contains private RSA JWK keys, by default, keys without the optimization private key parameters (p, q, dp, dq, qi) won't imported because their calculation is heavy and prone to blocking the process. Setting this option to true will enable these keys to be imported, albeit at your own risk. Depending on the key size the calculation takes long and it should only be used for JWKS from trusted sources.
  • Returns: <JWKS.KeyStore>
Example (Click to expand)
const { JWKS: { KeyStore, asKeyStore } } = require('jose')
const jwks = {
  keys: [
    { kty: 'RSA',
      kid: 'gqUcZ2TjhmNrVOd1d27tedkabhOTs9WghMHIyjIBn7Y',
      e: 'AQAB',
      n:
      'vi1Aui6R0rUL_7pdcFKKMhBF25h4x8WiTZ4w66eNZhwIp48lz-vBuyUUrSR-RwcuvnxlXdjBdSaN-PZkNRDv2bXE3mVtjZgoYyzQlGLJ1wduQaBXIkrQWxc7yzL91MvtP1kWwFHHrQHZRlpiFQQm9gNCy2wXCTbWGT9kjrR1W1bkwhmOKK4rF-hMgaCNDrtEQ6xWknxV8aXW4itouJ0pJv8xplc6J14f_SNq6arVUcAZ26EzJYC2fcvqwsrnKzvW7QxQGQzh-u9Tn82Tl14Omh1KDV8C7Vb_m8XClv_9zOrKBGdaTl1zgINyMEaa_IMophnBgK_kAXvtVvEThQ93GQ',
      use: 'enc' }
  ]
}
const ks = asKeyStore(jwks)
// KeyStore {}
ks.size
// 1
ks instanceof KeyStore
// true

JWT (JSON Web Token)

const { JWT } = require('jose')
// { decode: [Function], sign: [Function], verify: [Function] }

JWT.sign(payload, key[, options])

Serializes and signs the payload as JWT using the provided private or symmetrical key. The Algorithm that will be used to sign with is either provided as part of the 'options.algorithm', 'options.header.alg' or inferred from the provided <JWK.Key> instance.

  • payload: <Object> JWT Claims Set
  • key: <JWK.Key> The key to sign with.
  • options: <Object>
    • algorithm: <string> The algorithm to use
    • audience: <string> | string[] JWT Audience, "aud" claim value, if provided it will replace "aud" found in the payload
    • expiresIn: <string> JWT Expiration Time, "exp" claim value, specified as string which is added to the current unix epoch timestamp e.g. 24 hours, 20 m, 60s, etc., if provided it will replace Expiration Time found in the payload
    • header: <Object> JWT Header object
    • iat: <Boolean> When true it pushes the "iat" to the JWT Header. Default: 'true'
    • issuer: <string> JWT Issuer, "iss" claim value, if provided it will replace "iss" found in the payload
    • jti: <string> JWT ID, "jti" claim value, if provided it will replace "jti" found in the payload
    • kid: <Boolean> When true it pushes the key's "kid" to the JWT Header. Default: 'true'
    • nonce: <string> ID Token Nonce, "nonce" claim value, if provided it will replace "nonce" found in the payload. See OpenID Connect Core 1.0 for details.
    • notBefore: <string> JWT Not Before, "nbf" claim value, specified as string which is added to the current unix epoch timestamp e.g. 24 hours, 20 m, 60s, etc., if provided it will replace Not Before found in the payload
    • now: <Date> Date object to be used instead of the current unix epoch timestamp. Default: 'new Date()'
    • subject: <string> JWT subject, "sub" claim value, if provided it will replace "sub" found in the payload
  • Returns: <string>
Example (Click to expand)
const { JWT, JWK } = require('jose')
const key = JWK.asKey({
  kty: 'oct',
  k: 'hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg'
})

const payload = {
  'urn:example:claim': 'foo'
}

const token = JWT.sign(payload, key, {
  audience: ['urn:example:client'],
  issuer: 'https://op.example.com',
  expiresIn: '2 hours',
  header: {
    typ: 'JWT'
  }
})
// eyJ0eXAiOiJKV1QiLCJraWQiOiJSdG9SdXJfMURpcjVNNHd1T2ZxTmtEWU9mOU9fNFJKLWFIa1RBNzVSTEE4IiwiYWxnIjoiSFMyNTYifQ.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6ImZvbyIsImF1ZCI6WyJ1cm46ZXhhbXBsZTpjbGllbnQiXSwiaXNzIjoiaHR0cHM6Ly9vcC5leGFtcGxlLmNvbSIsImlhdCI6MTU1MTI5NDEzNywiZXhwIjoxNTUxMzAxMzM3fQ.YmtApwaGRBWlL9O8avbmpYcJ5UwNy0R8rpbxZqHxNd4

JWT.verify(token, keyOrStore[, options])

Verifies the claims and signature of a JSON Web Token.

  • token: <String> JSON Web Token to verify
  • keyOrStore: <JWK.Key> | <JWKS.KeyStore> The key or store to verify with. When <JWKS.KeyStore> instance is provided a selection of possible candidate keys will be done and the operation will succeed if just one key matches.
  • options: <Object>
    • algorithms: string[] Array of expected signing algorithms. JWT signed with an algorithm not found in this option will be rejected. Default: accepts all algorithms available on the passed key (or keys in the keystore)
    • profile: <string> To validate a JWT according to a specific profile, e.g. as an ID Token. Supported values are 'id_token' for now. Default: 'undefined' (generic JWT). Combine this option with the other ones like maxAuthAge and nonce or subject depending on the use-case.
    • audience: <string> | string[] Expected audience value(s). When string an exact match must be found in the payload, when array at least one must be matched.
    • clockTolerance: <string> Clock Tolerance for comparing timestamps, provided as timespan string e.g. 120s, 2 minutes, etc. Default: no clock tolerance
    • complete: <Boolean> When false only the parsed payload is returned, otherwise an object with a parsed header, payload, the matched key and the base64url encoded signature will be returned Default: 'false'
    • crit: string[] Array of Critical Header Parameter names to recognize. Default: '[]'
    • ignoreExp: <Boolean> When true will not be validating the "exp" claim value to be in the future from now. Default: 'false'
    • ignoreIat: <Boolean> When true will not be validating the "iat" claim value to be in the past from now. Default: 'false'
    • ignoreNbf: <Boolean> When true will not be validating the "nbf" claim value to be in the past from now. Default: 'false'
    • issuer: <string> Expected issuer value. An exact match must be found in the payload.
    • jti: <string> Expected jti value. An exact match must be found in the payload.
    • maxAuthAge: <string> When provided the payload is checked to have the "auth_time" claim and its value is validated, provided as timespan string e.g. 30m, 24 hours. See OpenID Connect Core 1.0 for details. Do not confuse with maxTokenAge option.
    • maxTokenAge: <string> When provided the payload is checked to have the "iat" claim and its value is validated not to be older than the provided timespan string e.g. 30m, 24 hours. Do not confuse with maxAuthAge option.
    • nonce: <string> Expected nonce value. An exact match must be found in the payload. See OpenID Connect Core 1.0 for details.
    • now: <Date> Date object to be used instead of the current unix epoch timestamp. Default: 'new Date()'
    • subject: <string> Expected subject value. An exact match must be found in the payload.
  • Returns: <Object>
Example (Click to expand)
const { JWK, JWT } = require('jose')

const key = JWK.asKey({
  kty: 'oct',
  k: 'hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg'
})

const token = 'eyJ0eXAiOiJKV1QiLCJraWQiOiJSdG9SdXJfMURpcjVNNHd1T2ZxTmtEWU9mOU9fNFJKLWFIa1RBNzVSTEE4IiwiYWxnIjoiSFMyNTYifQ.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6ImZvbyIsImF1ZCI6WyJ1cm46ZXhhbXBsZTpjbGllbnQiXSwiaXNzIjoiaHR0cHM6Ly9vcC5leGFtcGxlLmNvbSIsImlhdCI6MTU1MTI5NDEzNywiZXhwIjoxNTUxMzAxMzM3fQ.YmtApwaGRBWlL9O8avbmpYcJ5UwNy0R8rpbxZqHxNd4'

JWT.verify(token, key, {
  audience: 'urn:example:client',
  issuer: 'https://op.example.com',
  clockTolerance: '1 min'
})

JWT.decode(token[, options])

Decodes the JWT payload and optionally the header. Does not perform any claim validations what so ever.

  • token: <String> JSON Web Token to decode
  • options: <Object>
    • complete: <Boolean> When false only the parsed payload is returned, otherwise an object with a parsed header, payload and the base64url encoded signature will be returned Default: 'false'
  • Returns: <Object>
Example (Click to expand)
const { JWT } = require('jose')

const token = 'eyJ0eXAiOiJKV1QiLCJraWQiOiJSdG9SdXJfMURpcjVNNHd1T2ZxTmtEWU9mOU9fNFJKLWFIa1RBNzVSTEE4IiwiYWxnIjoiSFMyNTYifQ.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6ImZvbyIsImF1ZCI6WyJ1cm46ZXhhbXBsZTpjbGllbnQiXSwiaXNzIjoiaHR0cHM6Ly9vcC5leGFtcGxlLmNvbSIsImlhdCI6MTU1MTI5NDEzNywiZXhwIjoxNTUxMzAxMzM3fQ.YmtApwaGRBWlL9O8avbmpYcJ5UwNy0R8rpbxZqHxNd4'

JWT.decode(token)
// { 'urn:example:claim': 'foo',
//   aud: [ 'urn:example:client' ],
//   iss: 'https://op.example.com',
//   iat: 1551294137,
//   exp: 1551301337 }
JWT.decode(token, { complete: true })
// { header:
//    { typ: 'JWT',
//      kid: 'RtoRur_1Dir5M4wuOfqNkDYOf9O_4RJ-aHkTA75RLA8',
//      alg: 'HS256' },
//   payload:
//    { 'urn:example:claim': 'foo',
//      aud: [ 'urn:example:client' ],
//      iss: 'https://op.example.com',
//      iat: 1551294137,
//      exp: 1551301337 },
//   signature: 'YmtApwaGRBWlL9O8avbmpYcJ5UwNy0R8rpbxZqHxNd4' }

JWS (JSON Web Signature)

The <JWS> module provides methods required to sign or verify JSON Web Signatures in either one of the defined serializations.

const { JWS } = require('jose')
// { Sign: [Function: Sign],
//   sign:
//    { [Function: bound single]
//      flattened: [Function: bound single] },
//   verify: [Function: bound jwsVerify] }

Class: <JWS.Sign>

<JWS.Sign> is the class used when you need to produce a JWS for multiple recipients (with multiple signatures of the same payload) using the General JWS JSON Serialization Syntax.

Example (Click to expand)
const { JWK, JWS } = require('jose')

const key = JWK.asKey({
  kty: 'oct',
  k: 'hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg'
})
const key2 = JWK.asKey({
  kty: 'oct',
  k: 'AAPapAv4LbFbiVawEjagUBluYqN5rhna-8nuldDvOx8'
})

const payload = {
  sub: 'John Doe'
}

const sig = new JWS.Sign(payload)
sig.recipient(key, { alg: 'HS256' }, { foo: 'bar' })
sig.recipient(key2, { alg: 'HS512' }, { foo: 'baz' })
sig.sign('general')
// { payload: 'eyJzdWIiOiJKb2huIERvZSJ9',
//   signatures:
//    [ { protected: 'eyJhbGciOiJIUzI1NiJ9',
//        header: { foo: 'bar' },
//        signature: 'mnBcKK-9setCco03NtYws-RMlYXP3LGlDu2RUB7vetQ' },
//      { protected: 'eyJhbGciOiJIUzUxMiJ9',
//        header: { foo: 'baz' },
//        signature:
//         'R7e5ZUkgiZQLh8JagoCbwAY21e9A-Y0rhUGQkhihLOvIU8JG2AyZ9zROOUICaUucf8NQKc2dEaIKdRCXy-fDdQ' } ] }

new JWS.Sign(payload)

Creates a new Sign object for the provided payload, intended for one or more recipients.

  • payload: <Object> | <string> | <Buffer> The payload that will be signed. When <Object> it will be automatically serialized to JSON before signing
  • Returns: <JWS.Sign>

sign.recipient(key[, protected[, header]])

Adds a recipient to the JWS, the Algorithm that will be used to sign with is either provided as part of the Protected or Unprotected Header or inferred from the provided <JWK.Key> instance.

  • key: <JWK.Key> The key to sign with.
  • protected: <Object> Protected Header for this recipient
  • header: <Object> Unprotected Header for this recipient

sign.sign(serialization)

Performs the signing operations for each registered recipient and returns the final JWS representation in the serialization requested. The JWS is validated for conformance during this step. Please note that only 'general' and 'flattened' serialization supports Unprotected Per-Recipient Header and only the 'general' serialization supports multiple recipients. See <JWS.sign> and <JWS.sign.flattened> for shorthand methods to sign for a single recipient.

  • serialization: <string> JWS Serialization. Must be one of 'general', 'flattened', 'compact'
  • Returns: <string> | <Object>

JWS.sign(payload, key[, protected])

Performs the signing operation and 'compact' JWS serialization of the result. The Algorithm that will be used to sign with is either provided as part of the Protected Header or inferred from the provided <JWK.Key> instance.

  • payload: <Object> | <string> | <Buffer> The payload that will be signed. When <Object> it will be automatically serialized to JSON before signing
  • key: <JWK.Key> The key to sign with.
  • protected: <Object> Protected Header
  • Returns: <string>
Example (Click to expand)
const { JWK, JWS } = require('jose')

const key = JWK.asKey({
  kty: 'oct',
  k: 'hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg'
})

const payload = {
  sub: 'John Doe'
}
JWS.sign(payload, key, { alg: 'HS256' })
// eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2huIERvZSJ9.mnBcKK-9setCco03NtYws-RMlYXP3LGlDu2RUB7vetQ

JWS.sign.flattened(payload, key[, protected[, header]])

Performs the signing operation and 'flattened' JWS serialization of the result. The Algorithm that will be used to sign with is either provided as part of the Protected or Unprotected Header or inferred from the provided <JWK.Key> instance.

  • payload: <Object> | <string> | <Buffer> The payload that will be signed. When <Object> it will be automatically serialized to JSON before signing
  • key: <JWK.Key> The key to sign with.
  • protected: <Object> Protected Header
  • header: <Object> Unprotected Header
  • Returns: <Object>
Example (Click to expand)
const { JWK, JWS } = require('jose')

const key = JWK.asKey({
  kty: 'oct',
  k: 'hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg'
})

const payload = {
  sub: 'John Doe'
}

JWS.sign.flattened(payload, key)
// { payload: 'eyJzdWIiOiJKb2huIERvZSJ9',
//   protected: 'eyJhbGciOiJIUzI1NiJ9',
//   signature: 'mnBcKK-9setCco03NtYws-RMlYXP3LGlDu2RUB7vetQ' }

JWS.verify(jws, keyOrStore[, options])

Verifies the provided JWS in either serialization with a given <JWK.Key> or <JWKS.KeyStore>

  • jws: <Object> | <string> The JWS to verify. This must be a valid JWS.
  • keyOrStore: <JWK.Key> | <JWKS.KeyStore> The key or store to verify with. When <JWKS.KeyStore> instance is provided a selection of possible candidate keys will be done and the operation will succeed if just one key or signature (in case of General JWS JSON Serialization Syntax) matches.
  • options: <Object>
    • algorithms: string[] Array of Algorithms to accept, when the signature does not use an algorithm from this list the verification will fail. Default: 'undefined' - accepts all algorithms available on the keys
    • complete: <boolean> When true returns a complete object with the parsed headers and payload instead of just the verified payload. Default: 'false'
    • crit: string[] Array of Critical Header Parameter names to recognize. Default: '[]'
  • Returns: <string> | <Object>
Example (Click to expand)
const { JWK, JWS, JWKS } = require('jose')

const key = JWK.asKey({
  kty: 'oct',
  k: 'hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg'
})
const key2 = JWK.asKey({
  kty: 'oct',
  k: 'AAPapAv4LbFbiVawEjagUBluYqN5rhna-8nuldDvOx8'
})

const compact = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2huIERvZSJ9.mnBcKK-9setCco03NtYws-RMlYXP3LGlDu2RUB7vetQ'

const flattened = { payload: 'eyJzdWIiOiJKb2huIERvZSJ9',
  protected: 'eyJhbGciOiJIUzI1NiJ9',
  signature: 'mnBcKK-9setCco03NtYws-RMlYXP3LGlDu2RUB7vetQ' }

const general = { payload: 'eyJzdWIiOiJKb2huIERvZSJ9',
  signatures:
   [ { protected: 'eyJhbGciOiJIUzI1NiJ9',
       header: { foo: 'bar' },
       signature: 'mnBcKK-9setCco03NtYws-RMlYXP3LGlDu2RUB7vetQ' },
     { protected: 'eyJhbGciOiJIUzUxMiJ9',
       header: { foo: 'baz' },
       signature:
        'R7e5ZUkgiZQLh8JagoCbwAY21e9A-Y0rhUGQkhihLOvIU8JG2AyZ9zROOUICaUucf8NQKc2dEaIKdRCXy-fDdQ' } ] }

JWS.verify(compact, key)
// { sub: 'John Doe' }

JWS.verify(flattened, key2)
// JWSVerificationFailed: signature verification failed

JWS.verify(compact, key, { complete: true })
// { payload: { sub: 'John Doe' }, protected: { alg: 'HS256' }, key: OctKey {} }

JWS.verify(flattened, key, { algorithms: ['PS256'] })
// JOSEAlgNotWhitelisted: alg not whitelisted

JWS.verify(general, key)
// { sub: 'John Doe' }
JWS.verify(general, key2)
// { sub: 'John Doe' }

JWS.verify(general, key, { complete: true })
// { payload: { sub: 'John Doe' },
//   protected: { alg: 'HS256' },
//   header: { foo: 'bar' },
//   key: : OctKey {} } <- key
JWS.verify(general, key2, { complete: true })
// { payload: { sub: 'John Doe' },
//   protected: { alg: 'HS512' },
//   header: { foo: 'baz' },
//   key: : OctKey {} } <- key2
const keystore = new JWKS.KeyStore(key)
JWS.verify(general, keystore, { complete: true })
// { payload: { sub: 'John Doe' },
//   protected: { alg: 'HS256' },
//   header: { foo: 'bar' },
//   key: : OctKey {} } <- key that matched in the keystore

JWE (JSON Web Encryption)

The <JWE> module provides methods required to encrypt or decrypt JSON Web Encryptions in either one of the defined serializations.

const { JWE } = require('jose')
// { Encrypt: [Function: Encrypt],
//   encrypt:
//    { [Function: bound single]
//      flattened: [Function: bound single] },
//   decrypt: [Function: bound jweDecrypt] }

Class: <JWE.Encrypt>

<JWE.Encrypt> is the class used when you need to produce a JWE for multiple recipients using the General JWE JSON Serialization Syntax.


new JWE.Encrypt(cleartext[, protected[, unprotected[, aad]]])

Creates a new Encrypt object for the provided cleartext with optional Protected and Unprotected Headers and Additional Authenticated Data.

  • cleartext: <string> | <Buffer> The cleartext that will be encrypted.
  • protected: <Object> JWE Protected Header
  • unprotected: <Object> JWE Shared Unprotected Header
  • aad: <string> | <Buffer> JWE Additional Authenticated Data
  • Returns: <JWE.Encrypt>

encrypt.recipient(key[, header])

Adds a recipient to the JWE, the Algorithm that will be used to wrap or derive the Content Encryption Key (CEK) is either provided as part of the combined JWE Header for the recipient or inferred from the provided <JWK.Key> instance.

  • key: <JWK.Key> The key to use for Key Management or Direct Encryption
  • header: <Object> JWE Per-Recipient Unprotected Header

encrypt.encrypt(serialization)

Performs the encryption operations for each registered recipient and returns the final JWE representation in the serialization requested. The JWE is validated for conformance during this step. Please note that only 'general' and 'flattened' serialization supports Unprotected Per-Recipient Header and AAD and only the 'general' serialization supports multiple recipients. See <JWE.encrypt> and <JWE.encrypt.flattened> for shorthand methods to encrypt for a single recipient.

  • serialization: <string> JWE Serialization. Must be one of 'general', 'flattened', 'compact'
  • Returns: <string> | <Object>

JWE.encrypt(cleartext, key[, protected])

Performs the encryption operation and 'compact' JWE serialization of the result. The Algorithm that will be used to wrap or derive the Content Encryption Key (CEK) is either provided as part of the Protected Header or inferred from the provided <JWK.Key> instance.

  • cleartext: <string> | <Buffer> The cleartext that will be encrypted.
  • key: <JWK.Key> The key to use for Key Management or Direct Encryption
  • protected: <Object> JWE Protected Header
  • Returns: <string>

JWE.encrypt.flattened(cleartext, key[, protected[, header[, aad]]])

Performs the encryption operation and 'flattened' JWE serialization of the result. The Algorithm that will be used to wrap or derive the Content Encryption Key (CEK) is either provided as part of the combined JWE Header or inferred from the provided <JWK.Key> instance.

  • cleartext: <string> | <Buffer> The cleartext that will be encrypted.
  • key: <JWK.Key> The key to use for Key Management or Direct Encryption
  • protected: <Object> JWE Protected Header
  • unprotected: <Object> JWE Shared Unprotected Header
  • aad: <string> | <Buffer> JWE Additional Authenticated Data
  • Returns: <Object>

JWE.decrypt(jwe, keyOrStore[, options])

Verifies the provided JWE in either serialization with a given <JWK.Key> or <JWKS.KeyStore>

  • jwe: <Object> | <string> The JWE to decrypt. This must be a valid JWE.
  • keyOrStore: <JWK.Key> | <JWKS.KeyStore> The key or store to decrypt with. When <JWKS.KeyStore> instance is provided a selection of possible candidate keys will be done and the operation will succeed if just one key or signature (in case of General JWE JSON Serialization Syntax) matches.
  • options: <Object>
    • algorithms: string[] Array of Algorithms to accept, when the JWE does not use an Key Management algorithm from this list the decryption will fail. Default: 'undefined' - accepts all algorithms available on the keys
    • complete: <boolean> When true returns a complete object with the parsed headers, verified AAD and cleartext instead of just the cleartext. Default: 'false'
  • Returns: <string> | <Object>

Errors

The following errors are expected to be thrown by jose runtime and have their prototypes exported in jose.errors. If you encounter an Error other then TypeError or one that's instanceof jose.errors.JOSEError please report it, it is not intended.

Class: TypeError

Thrown when unexpected argument types or their format is encountered. This is the standard built-in TypeError.

Class: JOSEError

Base Error the others inherit from.

Class: JOSEAlgNotWhitelisted

Thrown when an algorithm whitelist is provided but the validated JWE/JWS does not use one from it.

if (err.code === 'ERR_JOSE_ALG_NOT_WHITELISTED') {
  // ...
}

Class: JOSECritNotUnderstood

Thrown when a Critical member is encountered that's not acknowledged. The only built in "crit" handler is for "b64", it must still be acknowledged though.

if (err.code === 'ERR_JOSE_CRIT_NOT_UNDERSTOOD') {
  // ...
}

Class: JOSEMultiError

This error is thrown when

  • multi-recipient JWE decryption fails for each recipient with errors other than JWEDecryptionFailed (ERR_JWE_DECRYPTION_FAILED)
  • multi-recipient JWS verification fails for each recipient with errors other than JWSVerificationFailed (ERR_JWS_VERIFICATION_FAILED)
  • KeyStore instance is passed to JWT/JWS verify, there are multiple usable keys and all of them fail with errors other than JWSVerificationFailed (ERR_JWS_VERIFICATION_FAILED)
  • KeyStore instance is passed to JWE decrypt, there are multiple usable keys and all of them fail with errors other than JWEDecryptionFailed (ERR_JWE_DECRYPTION_FAILED)

The error is an Iterable and yields every single one of the encountered errors.

if (err.code === 'ERR_JOSE_MULTIPLE_ERRORS') {
  for (const e of err) {
    console.log(e)
    // ...
  }
}

Class: JOSENotSupported

Thrown when an unsupported "alg", "kty" or specific header value like "zip" is encountered.

if (err.code === 'ERR_JOSE_NOT_SUPPORTED') {
  // ...
}

Class: JWEDecryptionFailed

Thrown when JWE decrypt operations are started but fail to decrypt. Only generic error message is provided.

if (err.code === 'ERR_JWE_DECRYPTION_FAILED') {
  // ...
}

Class: JWEInvalid

Thrown when syntactically incorrect JWE is either requested to be encrypted or decrypted

if (err.code === 'ERR_JWE_INVALID') {
  // ...
}

Class: JWKImportFailed

Thrown when a key failed to import as <JWK.Key>

if (err.code === 'ERR_JWK_IMPORT_FAILED') {
  // ...
}

Class: JWKKeyInvalid

Thrown when key's parameters are invalid, e.g. key_ops and use values are inconsistent.

if (err.code === 'ERR_JWK_INVALID') {
  // ...
}

Class: JWKKeySupport

Thrown when a key does not support the request algorithm.

if (err.code === 'ERR_JWK_KEY_SUPPORT') {
  // ...
}

Class: JWKSNoMatchingKey

Thrown when <JWKS.KeyStore> is used as argument for decrypt / verify operation and no usable key for the crypto operation is found in it

if (err.code === 'ERR_JWKS_NO_MATCHING_KEY') {
  // ...
}

Class: JWSInvalid

Thrown when syntactically incorrect JWS is either requested to be signed or verified

if (err.code === 'ERR_JWS_INVALID') {
  // ...
}

Class: JWSVerificationFailed

Thrown when JWS verify operations are started but fail to verify. Only generic error message is provided.

if (err.code === 'ERR_JWS_VERIFICATION_FAILED') {
  // ...
}

Class: JWTClaimInvalid

Thrown when JWT Claim is either of incorrect type or fails to validate by the provided options.

if (err.code === 'ERR_JWT_CLAIM_INVALID') {
  // ...
}

Class: JWTMalformed

Thrown when malformed JWT is either being decoded or verified.

if (err.code === 'ERR_JWT_MALFORMED') {
  // ...
}
You can’t perform that action at this time.