{"record":{"id":"d507a2741c4621fd","repo":"auth0/node-jsonwebtoken","slug":"invalid-key-for-this-operation-its-rsa-pss-parame","errorCode":null,"errorMessage":"Invalid key for this operation, its RSA-PSS parameters do not meet the requirements of \"alg\" ${algorithm}.","messagePattern":"Invalid key for this operation, its RSA-PSS parameters do not meet the requirements of \"alg\" (.+?)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"lib/validateAsymmetricKey.js","lineNumber":56,"sourceCode":"  /* istanbul ignore next */\n  if (ASYMMETRIC_KEY_DETAILS_SUPPORTED) {\n    switch (keyType) {\n    case 'ec':\n      const keyCurve = key.asymmetricKeyDetails.namedCurve;\n      const allowedCurve = allowedCurves[algorithm];\n\n      if (keyCurve !== allowedCurve) {\n        throw new Error(`\"alg\" parameter \"${algorithm}\" requires curve \"${allowedCurve}\".`);\n      }\n      break;\n\n    case 'rsa-pss':\n      if (RSA_PSS_KEY_DETAILS_SUPPORTED) {\n        const length = parseInt(algorithm.slice(-3), 10);\n        const { hashAlgorithm, mgf1HashAlgorithm, saltLength } = key.asymmetricKeyDetails;\n\n        if (hashAlgorithm !== `sha${length}` || mgf1HashAlgorithm !== hashAlgorithm) {\n          throw new Error(`Invalid key for this operation, its RSA-PSS parameters do not meet the requirements of \"alg\" ${algorithm}.`);\n        }\n\n        if (saltLength !== undefined && saltLength > length >> 3) {\n          throw new Error(`Invalid key for this operation, its RSA-PSS parameter saltLength does not meet the requirements of \"alg\" ${algorithm}.`)\n        }\n      }\n      break;\n    }\n  }\n}\n","sourceCodeStart":38,"sourceCodeEnd":67,"githubUrl":"https://github.com/auth0/node-jsonwebtoken/blob/b924272f29192e12926b5414546f7c5bfcc9579d/lib/validateAsymmetricKey.js#L38-L67","documentation":"RSA-PSS keys embed their hash algorithm, MGF1 hash algorithm, and salt length as key parameters. jsonwebtoken checks that these parameters are consistent with the chosen PS* algorithm (e.g. PS256 requires sha256 hash and sha256 MGF1) and throws when the key's internal parameters don't satisfy the algorithm's requirements.","triggerScenarios":"jwt.sign() or jwt.verify() with an RSA-PSS key whose asymmetricKeyDetails.hashAlgorithm or mgf1HashAlgorithm differs from sha<length> implied by PS256/PS384/PS512 (available on Node >= 12.9 where RSA_PSS_KEY_DETAILS_SUPPORTED is true).","commonSituations":"Generating a PSS key with openssl using default SHA-1 or SHA-384 parameters then signing with PS256; keys generated for one PSS variant reused for another after an algorithm upgrade; third-party provisioning tools that set mgf1 to a different hash than the key hash.","solutions":["Regenerate the PSS key with matching parameters, e.g. openssl genpkey -algorithm RSA-PSS -pkeyopt rsa_pss_keygen_md:sha256 -pkeyopt rsa_pss_keygen_mgf1_md:sha256 for PS256","Or choose the PS* algorithm matching the key's existing hash (sha384 key -> PS384)","If you cannot regenerate, use a plain RSA (PKCS#1 v1.5) key with RS256 instead"],"exampleFix":"// before\nopenssl genpkey -algorithm RSA-PSS -out key.pem  # defaults may mismatch PS256\n// after\nopenssl genpkey -algorithm RSA-PSS -pkeyopt rsa_pss_keygen_md:sha256 \\\n  -pkeyopt rsa_pss_keygen_mgf1_md:sha256 -out key.pem","handlingStrategy":"validation","validationCode":"function pssHashMatches(alg, key) {\n  if (!/^PS/.test(alg)) return true;\n  const bits = alg.slice(2);\n  const d = key.asymmetricKeyDetails || {};\n  return d.hashAlgorithm === 'sha' + bits && d.mgf1HashAlgorithm === d.hashAlgorithm;\n}\nif (!pssHashMatches(alg, key)) throw new Error('RSA-PSS key hash/mgf1 do not match ' + alg);","typeGuard":"function isPsCompatibleKey(alg, key) {\n  const bits = alg.replace(/^PS/, '');\n  const d = key.asymmetricKeyDetails;\n  return !d || (d.hashAlgorithm === 'sha' + bits && d.mgf1HashAlgorithm === d.hashAlgorithm);\n}","tryCatchPattern":"try {\n  return jwt.sign(payload, pssKey, { algorithm: alg });\n} catch (err) {\n  if (/RSA-PSS parameters do not meet/.test(err.message)) {\n    throw new Error('Regenerate PSS key with hash+mgf1 = ' + 'sha' + alg.slice(2));\n  }\n  throw err;\n}","preventionTips":["Generate PSS keys with explicit -pkeyopt rsa_pss_keygen_md and mgf1 md matching the target PS* variant","Keep hash, mgf1 hash, and salt length derived from a single algorithm constant","Inspect key.asymmetricKeyDetails when loading provisioned keys","Prefer RS256 with plain RSA keys unless PSS is a hard requirement"],"tags":["jwt","rsa-pss","key-parameters"],"backgroundTag":"jwt-rsa-pss-parameters-invalid","analyzedSha":"b924272f29192e12926b5414546f7c5bfcc9579d","analyzedAt":"2026-09-02T21:29:06.876Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}