[v24.x backport] crypto,doc: selected crypto changes

doc/api/crypto.md

@@ -1172,7 +1172,7 @@ changes:
 * `options` {Object} [`stream.transform` options][]
   * `plaintextLength` {number}
   * `encoding` {string} String encoding to use when `buffer` is a string.
-* Returns: {Decipheriv} The same Decipher for method chaining.
+* Returns: {Decipheriv} The same `Decipheriv` instance for method chaining.
 
 When using an authenticated encryption mode (`GCM`, `CCM`, `OCB`, and
 `chacha20-poly1305` are
@@ -1214,7 +1214,7 @@ changes:
 
 * `buffer` {string|Buffer|ArrayBuffer|TypedArray|DataView}
 * `encoding` {string} String encoding to use when `buffer` is a string.
-* Returns: {Decipheriv} The same Decipher for method chaining.
+* Returns: {Decipheriv} The same `Decipheriv` instance for method chaining.
 
 When using an authenticated encryption mode (`GCM`, `CCM`, `OCB`, and
 `chacha20-poly1305` are
@@ -1249,7 +1249,7 @@ added: v0.7.1
 -->
 
 * `autoPadding` {boolean} **Default:** `true`
-* Returns: {Decipheriv} The same Decipher for method chaining.
+* Returns: {Decipheriv} The same `Decipheriv` instance for method chaining.
 
 When data has been encrypted without standard block padding, calling
 `decipher.setAutoPadding(false)` will disable automatic padding to prevent
@@ -5305,7 +5305,7 @@ changes:
 
 <!--lint enable maximum-line-length remark-lint-->
 
-Decrypts `buffer` with `key`.`buffer` was previously encrypted using
+Decrypts `buffer` with `key`. `buffer` was previously encrypted using
 the corresponding private key, for example using [`crypto.privateEncrypt()`][].
 
 If `key` is not a [`KeyObject`][], this function behaves as if

doc/api/webcrypto.md

@@ -504,8 +504,8 @@ const decrypted = new TextDecoder().decode(await crypto.subtle.decrypt(
 
 ## Algorithm matrix
 
-The tables details the algorithms supported by the Node.js Web Crypto API
-implementation and the APIs supported for each:
+The following tables detail the algorithms supported by the Node.js Web
+Crypto API implementation and the APIs supported for each:
 
 ### Key Management APIs
 
@@ -742,7 +742,7 @@ Valid key usages depend on the key algorithm (identified by
 | `'ECDSA'`                            |            | ✔                  |                        |              |                   |
 | `'Ed25519'`                          |            | ✔                  |                        |              |                   |
 | `'Ed448'`[^secure-curves]            |            | ✔                  |                        |              |                   |
-| `'HDKF'`                             |            |                    | ✔                      |              |                   |
+| `'HKDF'`                             |            |                    | ✔                      |              |                   |
 | `'HMAC'`                             |            | ✔                  |                        |              |                   |
 | `'KMAC128'`[^modern-algos]           |            | ✔                  |                        |              |                   |
 | `'KMAC256'`[^modern-algos]           |            | ✔                  |                        |              |                   |
@@ -979,7 +979,7 @@ a new {CryptoKey} based on the method and parameters in `derivedKeyAlgorithm`.
 
 Calling this method is equivalent to calling [`subtle.deriveBits()`][] to
 generate raw keying material, then passing the result into the
-[`subtle.importKey()`][] method using the `deriveKeyAlgorithm`, `extractable`, and
+[`subtle.importKey()`][] method using the `derivedKeyAlgorithm`, `extractable`, and
 `keyUsages` parameters as input.
 
 The algorithms currently supported include:
@@ -1325,7 +1325,7 @@ The algorithms currently supported include:
 | `'ECDSA'`                            | ✔        | ✔         | ✔       | ✔       |                | ✔              |              |
 | `'Ed25519'`                          | ✔        | ✔         | ✔       | ✔       |                | ✔              |              |
 | `'Ed448'`[^secure-curves]            | ✔        | ✔         | ✔       | ✔       |                | ✔              |              |
-| `'HDKF'`                             |          |           |         | ✔       | ✔              |                |              |
+| `'HKDF'`                             |          |           |         | ✔       | ✔              |                |              |
 | `'HMAC'`                             |          |           | ✔       | ✔       | ✔              |                |              |
 | `'KMAC128'`[^modern-algos]           |          |           | ✔       |         | ✔              |                |              |
 | `'KMAC256'`[^modern-algos]           |          |           | ✔       |         | ✔              |                |              |
@@ -1449,14 +1449,14 @@ The unwrapped key algorithms supported include:
 * `'Ed25519'`
 * `'Ed448'`[^secure-curves]
 * `'HMAC'`
-* `'KMAC128'`[^secure-curves]
-* `'KMAC256'`[^secure-curves]
+* `'KMAC128'`[^modern-algos]
+* `'KMAC256'`[^modern-algos]
 * `'ML-DSA-44'`[^modern-algos]
 * `'ML-DSA-65'`[^modern-algos]
 * `'ML-DSA-87'`[^modern-algos]
 * `'ML-KEM-512'`[^modern-algos]
 * `'ML-KEM-768'`[^modern-algos]
-* `'ML-KEM-1024'`[^modern-algos]v
+* `'ML-KEM-1024'`[^modern-algos]
 * `'RSA-OAEP'`
 * `'RSA-PSS'`
 * `'RSASSA-PKCS1-v1_5'`
@@ -1502,8 +1502,8 @@ The algorithms currently supported include:
 * `'Ed25519'`
 * `'Ed448'`[^secure-curves]
 * `'HMAC'`
-* `'KMAC128'`[^secure-curves]
-* `'KMAC256'`[^secure-curves]
+* `'KMAC128'`[^modern-algos]
+* `'KMAC256'`[^modern-algos]
 * `'ML-DSA-44'`[^modern-algos]
 * `'ML-DSA-65'`[^modern-algos]
 * `'ML-DSA-87'`[^modern-algos]
@@ -1850,7 +1850,7 @@ added: v24.7.0
 added: v24.7.0
 -->
 
-* Type: {string} Must be `Ed448`[^secure-curves], `'ML-DSA-44'`[^modern-algos],
+* Type: {string} Must be `'Ed448'`[^secure-curves], `'ML-DSA-44'`[^modern-algos],
   `'ML-DSA-65'`[^modern-algos], or `'ML-DSA-87'`[^modern-algos].
 
 #### `contextParams.context`
@@ -1884,7 +1884,7 @@ changes:
 added: v24.7.0
 -->
 
-* Type: {string} Must be `'cSHAKE128'`[^modern-algos] or `'cSHAKE256'`[^modern-algos]
+* Type: {string} Must be `'cSHAKE128'`[^modern-algos] or `'cSHAKE256'`[^modern-algos].
 
 #### `cShakeParams.outputLength`
 
@@ -1902,7 +1902,7 @@ added: v24.7.0
 
 * Type: {ArrayBuffer|TypedArray|DataView|Buffer|undefined}
 
-The `functionName` member represents represents the function name, used by NIST to define
+The `functionName` member represents the function name, used by NIST to define
 functions based on cSHAKE.
 The Node.js Web Crypto API implementation only supports zero-length functionName
 which is equivalent to not providing functionName at all.
@@ -1941,9 +1941,9 @@ added: v15.0.0
 
 * Type: {CryptoKey}
 
-ECDH key derivation operates by taking as input one parties private key and
-another parties public key -- using both to generate a common shared secret.
-The `ecdhKeyDeriveParams.public` property is set to the other parties public
+ECDH key derivation operates by taking as input one party's private key and
+another party's public key -- using both to generate a common shared secret.
+The `ecdhKeyDeriveParams.public` property is set to the other party's public
 key.
 
 ### Class: `EcdsaParams`

lib/internal/crypto/aes.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const {
-  ArrayFrom,
   ArrayPrototypePush,
   SafeSet,
 } = primordials;
@@ -205,7 +204,7 @@ async function aesGenerateKey(algorithm, extractable, keyUsages) {
   return new InternalCryptoKey(
     key,
     { name, length },
-    ArrayFrom(usagesSet),
+    usagesSet,
     extractable);
 }
 
@@ -300,7 +299,7 @@ function aesImportKey(
   return new InternalCryptoKey(
     keyObject,
     { name, length },
-    keyUsages,
+    usagesSet,
     extractable);
 }
 

lib/internal/crypto/cfrg.js

@@ -171,7 +171,7 @@ async function cfrgGenerateKey(algorithm, extractable, keyUsages) {
     case 'X25519':
       // Fall through
     case 'X448':
-      publicUsages = [];
+      publicUsages = new SafeSet();
       privateUsages = getUsagesUnion(usageSet, 'deriveKey', 'deriveBits');
       break;
   }
@@ -340,7 +340,7 @@ function cfrgImportKey(
   return new InternalCryptoKey(
     keyObject,
     { name },
-    keyUsages,
+    usagesSet,
     extractable);
 }
 

lib/internal/crypto/chacha20_poly1305.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const {
-  ArrayFrom,
   SafeSet,
 } = primordials;
 
@@ -76,7 +75,7 @@ async function c20pGenerateKey(algorithm, extractable, keyUsages) {
   return new InternalCryptoKey(
     createSecretKey(keyData),
     { name },
-    ArrayFrom(usagesSet),
+    usagesSet,
     extractable);
 }
 
@@ -155,7 +154,7 @@ function c20pImportKey(
   return new InternalCryptoKey(
     keyObject,
     { name },
-    keyUsages,
+    usagesSet,
     extractable);
 }
 

lib/internal/crypto/ec.js

@@ -114,7 +114,7 @@ async function ecGenerateKey(algorithm, extractable, keyUsages) {
       privateUsages = getUsagesUnion(usageSet, 'sign');
       break;
     case 'ECDH':
-      publicUsages = [];
+      publicUsages = new SafeSet();
       privateUsages = getUsagesUnion(usageSet, 'deriveKey', 'deriveBits');
       break;
   }
@@ -280,7 +280,7 @@ function ecImportKey(
   return new InternalCryptoKey(
     keyObject,
     { name, namedCurve },
-    keyUsages,
+    usagesSet,
     extractable);
 }
 

lib/internal/crypto/keys.js

@@ -62,6 +62,7 @@ const {
   bigIntArrayToUnsignedBigInt,
   normalizeAlgorithm,
   hasAnyNotIn,
+  getSortedUsages,
 } = require('internal/crypto/util');
 
 const {
@@ -765,7 +766,7 @@ function getKeyObjectHandleFromJwk(key, ctx) {
 
 
 function getKeyObjectHandleFromRaw(options, data, format) {
-  if (!isStringOrBuffer(data)) {
+  if (!isArrayBufferView(data) && !isAnyArrayBuffer(data)) {
     throw new ERR_INVALID_ARG_TYPE(
       'key.key',
       ['ArrayBuffer', 'Buffer', 'TypedArray', 'DataView'],
@@ -1094,7 +1095,7 @@ class InternalCryptoKey {
         keyObject,
         algorithm,
         extractable,
-        keyUsages,
+        getSortedUsages(new SafeSet(keyUsages)),
       );
     }
   }
@@ -1160,7 +1161,7 @@ function importGenericSecretKey(
       return undefined;
   }
 
-  return new InternalCryptoKey(keyObject, { name }, keyUsages, false);
+  return new InternalCryptoKey(keyObject, { name }, usagesSet, false);
 }
 
 module.exports = {

lib/internal/crypto/mac.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const {
-  ArrayFrom,
   SafeSet,
   StringPrototypeSubstring,
 } = primordials;
@@ -76,7 +75,7 @@ async function hmacGenerateKey(algorithm, extractable, keyUsages) {
   return new InternalCryptoKey(
     key,
     { name, length, hash },
-    ArrayFrom(usageSet),
+    usageSet,
     extractable);
 }
 
@@ -110,7 +109,7 @@ async function kmacGenerateKey(algorithm, extractable, keyUsages) {
   return new InternalCryptoKey(
     createSecretKey(keyData),
     { name, length },
-    ArrayFrom(usageSet),
+    usageSet,
     extractable);
 }
 
@@ -211,7 +210,7 @@ function macImportKey(
   return new InternalCryptoKey(
     keyObject,
     algorithmObject,
-    keyUsages,
+    usagesSet,
     extractable);
 }
 

lib/internal/crypto/ml_dsa.js

@@ -297,7 +297,7 @@ function mlDsaImportKey(
   return new InternalCryptoKey(
     keyObject,
     { name },
-    keyUsages,
+    usagesSet,
     extractable);
 }
 

lib/internal/crypto/ml_kem.js

@@ -69,8 +69,8 @@ async function mlKemGenerateKey(algorithm, extractable, keyUsages) {
       { name: 'OperationError', cause: err });
   }
 
-  const publicUsages = getUsagesUnion(usageSet, 'encapsulateBits', 'encapsulateKey');
-  const privateUsages = getUsagesUnion(usageSet, 'decapsulateBits', 'decapsulateKey');
+  const publicUsages = getUsagesUnion(usageSet, 'encapsulateKey', 'encapsulateBits');
+  const privateUsages = getUsagesUnion(usageSet, 'decapsulateKey', 'decapsulateBits');
 
   const keyAlgorithm = { name };
 
@@ -230,7 +230,7 @@ function mlKemImportKey(
   return new InternalCryptoKey(
     keyObject,
     { name },
-    keyUsages,
+    usagesSet,
     extractable);
 }
 

lib/internal/crypto/rsa.js

@@ -327,7 +327,7 @@ function rsaImportKey(
     modulusLength,
     publicExponent: new Uint8Array(publicExponent),
     hash: algorithm.hash,
-  }, keyUsages, extractable);
+  }, usagesSet, extractable);
 }
 
 async function rsaSignVerify(key, data, { saltLength }, signature) {