crypto: align key argument names in docs and error messages

panva · sxa · commit bb2857b85a12 · 2026-06-23T01:06:35.000+01:00
Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: #62527 Backport-PR-URL: #63563 Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
@@ -2734,14 +2734,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
@@ -2760,7 +2760,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}
@@ -2771,10 +2771,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
@@ -6933,7 +6933,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/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -4484,7 +4484,7 @@ will throw an error in a future version.
 [`Sign.prototype.sign()`]: crypto.md#signsignprivatekey-outputencoding
 [`SlowBuffer`]: buffer.md#class-slowbuffer
 [`String.prototype.toWellFormed`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toWellFormed
-[`Verify.prototype.verify()`]: crypto.md#verifyverifyobject-signature-signatureencoding
+[`Verify.prototype.verify()`]: crypto.md#verifyverifykey-signature-signatureencoding
 [`WriteStream.open()`]: fs.md#class-fswritestream
 [`assert.CallTracker`]: assert.md#class-assertcalltracker
 [`assert`]: assert.md
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/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
@@ -1085,3 +1085,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
@@ -1031,3 +1031,66 @@ if (hasOpenSSL(3, 2)) {
     assert.strictEqual(crypto.verify('SHA256', dataBuffer, publicKey, sigSAB), true);
   }
 }
+
+// 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/,
+  });
+}
