crypto: align key argument names in docs and error messages

panva · panva · commit 03f624d25952 · 2026-04-07T13:03:57.000+02:00
Signed-off-by: Filip Skokan &lt;panva.ip@gmail.com&gt;
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
@@ -2743,14 +2743,14 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or
 
 This can be called many times with new data as it is streamed.
 
-### `verify.verify(object, signature[, signatureEncoding])`
+### `verify.verify(key, signature[, signatureEncoding])`
 
 <!-- YAML
 added: v0.1.92
 changes:
   - version: v15.0.0
     pr-url: https://github.com/nodejs/node/pull/35093
-    description: The object can also be an ArrayBuffer and CryptoKey.
+    description: The key can also be an ArrayBuffer and CryptoKey.
   - version:
      - v13.2.0
      - v12.16.0
@@ -2769,7 +2769,7 @@ changes:
 
 <!--lint disable maximum-line-length remark-lint-->
 
-* `object` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey}
+* `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey}
   * `dsaEncoding` {string}
   * `padding` {integer}
   * `saltLength` {integer}
@@ -2780,10 +2780,10 @@ changes:
 
 <!--lint enable maximum-line-length remark-lint-->
 
-Verifies the provided data using the given `object` and `signature`.
+Verifies the provided data using the given `key` and `signature`.
 
-If `object` is not a [`KeyObject`][], this function behaves as if
-`object` had been passed to [`crypto.createPublicKey()`][]. If it is an
+If `key` is not a [`KeyObject`][], this function behaves as if
+`key` had been passed to [`crypto.createPublicKey()`][]. If it is an
 object, the following additional properties can be passed:
 
 * `dsaEncoding` {string} For DSA and ECDSA, this option specifies the
@@ -6950,7 +6950,7 @@ See the [list of SSL OP Flags][] for details.
 [`stream.transform` options]: stream.md#new-streamtransformoptions
 [`util.promisify()`]: util.md#utilpromisifyoriginal
 [`verify.update()`]: #verifyupdatedata-inputencoding
-[`verify.verify()`]: #verifyverifyobject-signature-signatureencoding
+[`verify.verify()`]: #verifyverifykey-signature-signatureencoding
 [`x509.fingerprint256`]: #x509fingerprint256
 [`x509.verify(publicKey)`]: #x509verifypublickey
 [argon2]: https://www.rfc-editor.org/rfc/rfc9106.html
diff --git a/lib/internal/crypto/cipher.js b/lib/internal/crypto/cipher.js
@@ -63,14 +63,15 @@ const { normalizeEncoding } = require('internal/util');
 const { StringDecoder } = require('string_decoder');
 
 function rsaFunctionFor(method, defaultPadding, keyType) {
-  return (options, buffer) => {
+  const keyName = keyType === 'private' ? 'privateKey' : undefined;
+  return (key, buffer) => {
     const { format, type, data, passphrase, namedCurve } =
       keyType === 'private' ?
-        preparePrivateKey(options) :
-        preparePublicOrPrivateKey(options);
-    const padding = options.padding || defaultPadding;
-    const { oaepHash, encoding } = options;
-    let { oaepLabel } = options;
+        preparePrivateKey(key, keyName) :
+        preparePublicOrPrivateKey(key, keyName);
+    const padding = key.padding || defaultPadding;
+    const { oaepHash, encoding } = key;
+    let { oaepLabel } = key;
     if (oaepHash !== undefined)
       validateString(oaepHash, 'key.oaepHash');
     if (oaepLabel !== undefined)
diff --git a/lib/internal/crypto/keygen.js b/lib/internal/crypto/keygen.js
@@ -148,7 +148,7 @@ function parseKeyEncoding(keyType, options = kEmptyObject) {
       format: publicFormat,
       type: publicType,
     } = parsePublicKeyEncoding(publicKeyEncoding, keyType,
-                               'publicKeyEncoding'));
+                               'options.publicKeyEncoding'));
   } else {
     throw new ERR_INVALID_ARG_VALUE('options.publicKeyEncoding',
                                     publicKeyEncoding);
@@ -164,7 +164,7 @@ function parseKeyEncoding(keyType, options = kEmptyObject) {
       cipher,
       passphrase,
     } = parsePrivateKeyEncoding(privateKeyEncoding, keyType,
-                                'privateKeyEncoding'));
+                                'options.privateKeyEncoding'));
   } else {
     throw new ERR_INVALID_ARG_VALUE('options.privateKeyEncoding',
                                     privateKeyEncoding);
diff --git a/lib/internal/crypto/keys.js b/lib/internal/crypto/keys.js
@@ -466,9 +466,9 @@ function parseKeyType(typeStr, required, keyType, isPublic, optionName) {
   throw new ERR_INVALID_ARG_VALUE(optionName, typeStr);
 }
 
-function option(name, objName) {
-  return objName === undefined ?
-    `options.${name}` : `options.${objName}.${name}`;
+function option(name, prefix) {
+  return prefix === undefined ?
+    `options.${name}` : `${prefix}.${name}`;
 }
 
 function parseKeyFormatAndType(enc, keyType, isPublic, objName) {
@@ -668,7 +668,7 @@ function prepareAsymmetricKey(key, ctx, name = 'key') {
       if (key.asymmetricKeyType === 'ec') {
         validateString(key.namedCurve, `${name}.namedCurve`);
       }
-      const rawFormat = parseKeyFormat(format, undefined, 'options.format');
+      const rawFormat = parseKeyFormat(format, undefined, `${name}.format`);
       return {
         data: getArrayBufferOrView(data, `${name}.key`),
         format: rawFormat,
@@ -689,7 +689,7 @@ function prepareAsymmetricKey(key, ctx, name = 'key') {
       (ctx === kConsumePrivate || ctx === kCreatePrivate) ? false : undefined;
     return {
       data: getArrayBufferOrView(data, `${name}.key`, encoding),
-      ...parseKeyEncoding(key, undefined, isPublic),
+      ...parseKeyEncoding(key, undefined, isPublic, name),
     };
   }
 
diff --git a/lib/internal/crypto/sig.js b/lib/internal/crypto/sig.js
@@ -130,19 +130,19 @@ function getIntOption(name, options) {
   return undefined;
 }
 
-Sign.prototype.sign = function sign(options, encoding) {
-  if (!options)
+Sign.prototype.sign = function sign(privateKey, encoding) {
+  if (!privateKey)
     throw new ERR_CRYPTO_SIGN_KEY_REQUIRED();
 
   const { data, format, type, passphrase, namedCurve } =
-    preparePrivateKey(options);
+    preparePrivateKey(privateKey, 'privateKey');
 
   // Options specific to RSA
-  const rsaPadding = getPadding(options);
-  const pssSaltLength = getSaltLength(options);
+  const rsaPadding = getPadding(privateKey);
+  const pssSaltLength = getSaltLength(privateKey);
 
   // Options specific to (EC)DSA
-  const dsaSigEnc = getDSASignatureEncoding(options);
+  const dsaSigEnc = getDSASignatureEncoding(privateKey);
 
   const ret = this[kHandle].sign(data, format, type,
                                  passphrase, namedCurve,
@@ -232,21 +232,21 @@ ObjectSetPrototypeOf(Verify, Writable);
 Verify.prototype._write = Sign.prototype._write;
 Verify.prototype.update = Sign.prototype.update;
 
-Verify.prototype.verify = function verify(options, signature, sigEncoding) {
+Verify.prototype.verify = function verify(key, signature, sigEncoding) {
   const {
     data,
     format,
     type,
     passphrase,
     namedCurve,
-  } = preparePublicOrPrivateKey(options);
+  } = preparePublicOrPrivateKey(key, 'key');
 
   // Options specific to RSA
-  const rsaPadding = getPadding(options);
-  const pssSaltLength = getSaltLength(options);
+  const rsaPadding = getPadding(key);
+  const pssSaltLength = getSaltLength(key);
 
   // Options specific to (EC)DSA
-  const dsaSigEnc = getDSASignatureEncoding(options);
+  const dsaSigEnc = getDSASignatureEncoding(key);
 
   signature = getArrayBufferOrView(signature, 'signature', sigEncoding);
 
diff --git a/test/parallel/test-crypto-dh-stateless.js b/test/parallel/test-crypto-dh-stateless.js
@@ -398,6 +398,49 @@ for (const { privateKey: alicePriv, publicKey: bobPub } of [
   }
 }
 
+// Test that error messages include the correct property path
+{
+  const kp = crypto.generateKeyPairSync('x25519');
+  const pub = kp.publicKey.export({ type: 'spki', format: 'pem' });
+  const priv = kp.privateKey.export({ type: 'pkcs8', format: 'pem' });
+
+  // Invalid privateKey format
+  assert.throws(() => crypto.diffieHellman({
+    privateKey: { key: Buffer.alloc(0), format: 'banana', type: 'pkcs8' },
+    publicKey: pub,
+  }), {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /options\.privateKey\.format/,
+  });
+
+  // Invalid privateKey type
+  assert.throws(() => crypto.diffieHellman({
+    privateKey: { key: Buffer.alloc(0), format: 'der', type: 'banana' },
+    publicKey: pub,
+  }), {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /options\.privateKey\.type/,
+  });
+
+  // Invalid publicKey format
+  assert.throws(() => crypto.diffieHellman({
+    publicKey: { key: Buffer.alloc(0), format: 'banana', type: 'spki' },
+    privateKey: priv,
+  }), {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /options\.publicKey\.format/,
+  });
+
+  // Invalid publicKey type
+  assert.throws(() => crypto.diffieHellman({
+    publicKey: { key: Buffer.alloc(0), format: 'der', type: 'banana' },
+    privateKey: priv,
+  }), {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /options\.publicKey\.type/,
+  });
+}
+
 // Test C++ error conditions
 {
   const ec256 = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
diff --git a/test/parallel/test-crypto-key-objects.js b/test/parallel/test-crypto-key-objects.js
@@ -343,7 +343,7 @@ const privateDsa = fixtures.readKey('dsa_private_encrypted_1025.pem',
     createPrivateKey({ key: Buffer.alloc(0), format: 'der', type: 'spki' });
   }, {
     code: 'ERR_INVALID_ARG_VALUE',
-    message: "The property 'options.type' is invalid. Received 'spki'"
+    message: "The property 'key.type' is invalid. Received 'spki'"
   });
 
   // Unlike SPKI, PKCS#1 is a valid encoding for private keys (and public keys),
@@ -1074,3 +1074,38 @@ const privateDsa = fixtures.readKey('dsa_private_encrypted_1025.pem',
     }, { code: 'ERR_INVALID_ARG_TYPE', message: /The "key\.key" property must be of type object/ });
   }
 }
+
+// Test that createPublicKey/createPrivateKey error messages use 'key.<property>' paths
+{
+  // createPrivateKey with invalid format
+  assert.throws(() => {
+    createPrivateKey({ key: Buffer.alloc(0), format: 'banana', type: 'pkcs8' });
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /key\.format/,
+  });
+
+  // createPrivateKey with invalid type
+  assert.throws(() => {
+    createPrivateKey({ key: Buffer.alloc(0), format: 'der', type: 'banana' });
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /key\.type/,
+  });
+
+  // createPublicKey with invalid format
+  assert.throws(() => {
+    createPublicKey({ key: Buffer.alloc(0), format: 'banana', type: 'spki' });
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /key\.format/,
+  });
+
+  // createPublicKey with invalid type
+  assert.throws(() => {
+    createPublicKey({ key: Buffer.alloc(0), format: 'der', type: 'banana' });
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /key\.type/,
+  });
+}
diff --git a/test/parallel/test-crypto-sign-verify.js b/test/parallel/test-crypto-sign-verify.js
@@ -891,7 +891,7 @@ if (hasOpenSSL(3, 2)) {
     }, { code: 'ERR_INVALID_ARG_TYPE', message: /The "key\.key" property must be of type object/ });
     assert.throws(() => {
       crypto.createSign('sha256').sign({ key, format: 'jwk' });
-    }, { code: 'ERR_INVALID_ARG_TYPE', message: /The "key\.key" property must be of type object/ });
+    }, { code: 'ERR_INVALID_ARG_TYPE', message: /The "privateKey\.key" property must be of type object/ });
   }
 }
 
@@ -932,3 +932,66 @@ if (hasOpenSSL(3, 2)) {
     }, { code: 'ERR_OSSL_EVP_OPERATION_NOT_SUPPORTED_FOR_THIS_KEYTYPE', message: /operation not supported for this keytype/ });
   }
 }
+
+// Test that sign/verify error messages use correct property paths
+{
+  // Sign with invalid format
+  assert.throws(() => {
+    crypto.createSign('SHA256').update('test').sign({
+      key: Buffer.alloc(0), format: 'banana', type: 'pkcs8',
+    });
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /privateKey\.format/,
+  });
+
+  // Sign with invalid type
+  assert.throws(() => {
+    crypto.createSign('SHA256').update('test').sign({
+      key: Buffer.alloc(0), format: 'der', type: 'banana',
+    });
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /privateKey\.type/,
+  });
+
+  // Verify with invalid format
+  assert.throws(() => {
+    crypto.createVerify('SHA256').update('test').verify({
+      key: Buffer.alloc(0), format: 'banana', type: 'spki',
+    }, Buffer.alloc(0));
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /key\.format/,
+  });
+
+  // Verify with invalid type
+  assert.throws(() => {
+    crypto.createVerify('SHA256').update('test').verify({
+      key: Buffer.alloc(0), format: 'der', type: 'banana',
+    }, Buffer.alloc(0));
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /key\.type/,
+  });
+
+  // crypto.sign with invalid format
+  assert.throws(() => {
+    crypto.sign('SHA256', Buffer.from('test'), {
+      key: Buffer.alloc(0), format: 'banana', type: 'pkcs8',
+    });
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /key\.format/,
+  });
+
+  // crypto.verify with invalid format
+  assert.throws(() => {
+    crypto.verify('SHA256', Buffer.from('test'), {
+      key: Buffer.alloc(0), format: 'banana', type: 'spki',
+    }, Buffer.alloc(0));
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: /key\.format/,
+  });
+}
