@enbox/crypto 0.0.2 → 0.0.4

package/src/primitives/aes-kw.ts

@@ -0,0 +1,269 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { UnwrapKeyParams, WrapKeyParams } from '../types/params-direct.js';
+
+import { getWebcryptoSubtle } from '@noble/ciphers/webcrypto';
+
+import { Convert } from '@enbox/common';
+import { computeJwkThumbprint, isOctPrivateJwk } from '../jose/jwk.js';
+import { CryptoError, CryptoErrorCode } from '../crypto-error.js';
+
+/**
+ * Constant defining the AES key length values in bits.
+ *
+ * @remarks
+ * NIST publication FIPS 197 states:
+ * > The AES algorithm is capable of using cryptographic keys of 128, 192, and 256 bits to encrypt
+ * > and decrypt data in blocks of 128 bits.
+ *
+ * This implementation does not support key lengths that are different from the three values
+ * defined by this constant.
+ *
+ * @see {@link https://doi.org/10.6028/NIST.FIPS.197-upd1 | NIST FIPS 197}
+ */
+const AES_KEY_LENGTHS = [128, 192, 256] as const;
+
+export class AesKw {
+  /**
+   * Converts a raw private key in bytes to its corresponding JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method takes a symmetric key represented as a byte array (Uint8Array) and
+   * converts it into a JWK object for use with AES (Advanced Encryption Standard)
+   * for key wrapping. The conversion process involves encoding the key into
+   * base64url format and setting the appropriate JWK parameters.
+   *
+   * The resulting JWK object includes the following properties:
+   * - `kty`: Key Type, set to 'oct' for Octet Sequence (representing a symmetric key).
+   * - `k`: The symmetric key, base64url-encoded.
+   * - `kid`: Key ID, generated based on the JWK thumbprint.
+   *
+   * @example
+   * ```ts
+   * const privateKeyBytes = new Uint8Array([...]); // Replace with actual symmetric key bytes
+   * const privateKey = await AesKw.bytesToPrivateKey({ privateKeyBytes });
+   * ```
+   *
+   * @param params - The parameters for the symmetric key conversion.
+   * @param params.privateKeyBytes - The raw symmetric key as a Uint8Array.
+   *
+   * @returns A Promise that resolves to the symmetric key in JWK format.
+   */
+  public static async bytesToPrivateKey({ privateKeyBytes }: {
+    privateKeyBytes: Uint8Array;
+  }): Promise<Jwk> {
+    // Construct the private key in JWK format.
+    const privateKey: Jwk = {
+      k   : Convert.uint8Array(privateKeyBytes).toBase64Url(),
+      kty : 'oct'
+    };
+
+    // Compute the JWK thumbprint and set as the key ID.
+    privateKey.kid = await computeJwkThumbprint({ jwk: privateKey });
+
+    // Add algorithm identifier based on key length.
+    const lengthInBits = privateKeyBytes.length * 8;
+    privateKey.alg = { 128: 'A128KW', 192: 'A192KW', 256: 'A256KW' }[lengthInBits];
+
+    return privateKey;
+  }
+
+  /**
+   * Generates a symmetric key for AES for key wrapping in JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method creates a new symmetric key of a specified length suitable for use with
+   * AES key wrapping. It uses cryptographically secure random number generation to
+   * ensure the uniqueness and security of the key. The generated key adheres to the JWK
+   * format, making it compatible with common cryptographic standards and easy to use in
+   * various cryptographic processes.
+   *
+   * The generated key includes the following components:
+   * - `kty`: Key Type, set to 'oct' for Octet Sequence.
+   * - `k`: The symmetric key component, base64url-encoded.
+   * - `kid`: Key ID, generated based on the JWK thumbprint.
+   * - `alg`: Algorithm, set to 'A128KW', 'A192KW', or 'A256KW' for AES Key Wrap with the
+   *   specified key length.
+   *
+   * @example
+   * ```ts
+   * const length = 256; // Length of the key in bits (e.g., 128, 192, 256)
+   * const privateKey = await AesKw.generateKey({ length });
+   * ```
+   *
+   * @param params - The parameters for the key generation.
+   * @param params.length - The length of the key in bits. Common lengths are 128, 192, and 256 bits.
+   *
+   * @returns A Promise that resolves to the generated symmetric key in JWK format.
+   */
+  public static async generateKey({ length }: {
+    length: typeof AES_KEY_LENGTHS[number];
+  }): Promise<Jwk> {
+    // Validate the key length.
+    if (!(AES_KEY_LENGTHS as readonly number[]).includes(length)) {
+      throw new RangeError(`The key length is invalid: Must be ${AES_KEY_LENGTHS.join(', ')} bits`);
+    }
+
+    // Get the Web Crypto API interface.
+    const webCrypto = getWebcryptoSubtle() as SubtleCrypto;
+
+    // Generate a random private key.
+    // See https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues#usage_notes for
+    // an explanation for why Web Crypto generateKey() is used instead of getRandomValues().
+    const webCryptoKey = await webCrypto.generateKey( { name: 'AES-KW', length }, true, ['wrapKey', 'unwrapKey']);
+
+    // Export the private key in JWK format.
+    const { ext, key_ops, ...privateKey } = await webCrypto.exportKey('jwk', webCryptoKey) as Jwk;
+
+    // Compute the JWK thumbprint and set as the key ID.
+    privateKey.kid = await computeJwkThumbprint({ jwk: privateKey });
+
+    return privateKey;
+  }
+
+  /**
+   * Converts a private key from JSON Web Key (JWK) format to a raw byte array (Uint8Array).
+   *
+   * @remarks
+   * This method takes a symmetric key in JWK format and extracts its raw byte representation.
+   * It decodes the 'k' parameter of the JWK value, which represents the symmetric key in base64url
+   * encoding, into a byte array.
+   *
+   * @example
+   * ```ts
+   * const privateKey = { ... }; // A symmetric key in JWK format
+   * const privateKeyBytes = await AesKw.privateKeyToBytes({ privateKey });
+   * ```
+   *
+   * @param params - The parameters for the symmetric key conversion.
+   * @param params.privateKey - The symmetric key in JWK format.
+   *
+   * @returns A Promise that resolves to the symmetric key as a Uint8Array.
+   */
+  public static async privateKeyToBytes({ privateKey }: {
+    privateKey: Jwk;
+  }): Promise<Uint8Array> {
+    // Verify the provided JWK represents a valid oct private key.
+    if (!isOctPrivateJwk(privateKey)) {
+      throw new Error(`AesKw: The provided key is not a valid oct private key.`);
+    }
+
+    // Decode the provided private key to bytes.
+    const privateKeyBytes = Convert.base64Url(privateKey.k).toUint8Array();
+
+    return privateKeyBytes;
+  }
+
+  public static async unwrapKey({ wrappedKeyBytes, wrappedKeyAlgorithm, decryptionKey }:
+    UnwrapKeyParams
+  ): Promise<Jwk> {
+    if (!('alg' in decryptionKey && decryptionKey.alg)) {
+      throw new CryptoError(CryptoErrorCode.InvalidJwk, `The decryption key is missing the 'alg' property.`);
+    }
+
+    if (!['A128KW', 'A192KW', 'A256KW'].includes(decryptionKey.alg)) {
+      throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `The 'decryptionKey' algorithm is not supported: ${decryptionKey.alg}`);
+    }
+
+    // Get the Web Crypto API interface.
+    const webCrypto = getWebcryptoSubtle() as SubtleCrypto;
+
+    // Import the decryption key for use with the Web Crypto API.
+    const decryptionCryptoKey = await webCrypto.importKey(
+      'jwk', // key format
+      decryptionKey as JsonWebKey, // key data
+      { name: 'AES-KW' }, // algorithm identifier
+      true, // key is extractable
+      ['unwrapKey'] // key usages
+    );
+
+    // Map the private key's JOSE algorithm name to the Web Crypto API algorithm identifier.
+    const webCryptoAlgorithm = {
+      A128KW  : 'AES-KW', A192KW  : 'AES-KW', A256KW  : 'AES-KW',
+      A128GCM : 'AES-GCM', A192GCM : 'AES-GCM', A256GCM : 'AES-GCM',
+    }[wrappedKeyAlgorithm];
+
+    if (!webCryptoAlgorithm) {
+      throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `The 'wrappedKeyAlgorithm' is not supported: ${wrappedKeyAlgorithm}`);
+    }
+
+    // Unwrap the key using the Web Crypto API.
+    const unwrappedCryptoKey = await webCrypto.unwrapKey(
+      'raw', // output format
+      wrappedKeyBytes.buffer, // key to unwrap
+      decryptionCryptoKey, // unwrapping key
+      'AES-KW', // algorithm identifier
+      { name: webCryptoAlgorithm }, // unwrapped key algorithm identifier
+      true, // key is extractable
+      ['unwrapKey'] // key usages
+    );
+
+    // Export the unwrapped key in JWK format.
+    const { ext, key_ops, ...unwrappedJsonWebKey } = await webCrypto.exportKey('jwk', unwrappedCryptoKey);
+    const unwrappedKey = unwrappedJsonWebKey as Jwk;
+
+    // Compute the JWK thumbprint and set as the key ID.
+    unwrappedKey.kid = await computeJwkThumbprint({ jwk: unwrappedKey });
+
+    return unwrappedKey;
+  }
+
+  public static async wrapKey({ unwrappedKey, encryptionKey }:
+    WrapKeyParams
+  ): Promise<Uint8Array> {
+    if (!('alg' in encryptionKey && encryptionKey.alg)) {
+      throw new CryptoError(CryptoErrorCode.InvalidJwk, `The encryption key is missing the 'alg' property.`);
+    }
+
+    if (!['A128KW', 'A192KW', 'A256KW'].includes(encryptionKey.alg)) {
+      throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `The 'encryptionKey' algorithm is not supported: ${encryptionKey.alg}`);
+    }
+
+    if (!('alg' in unwrappedKey && unwrappedKey.alg)) {
+      throw new CryptoError(CryptoErrorCode.InvalidJwk, `The private key to wrap is missing the 'alg' property.`);
+    }
+
+    // Get the Web Crypto API interface.
+    const webCrypto = getWebcryptoSubtle() as SubtleCrypto;
+
+    // Import the encryption key for use with the Web Crypto API.
+    const encryptionCryptoKey = await webCrypto.importKey(
+      'jwk', // key format
+      encryptionKey as JsonWebKey, // key data
+      { name: 'AES-KW' }, // algorithm identifier
+      true, // key is extractable
+      ['wrapKey'] // key usages
+    );
+
+    // Map the private key's JOSE algorithm name to the Web Crypto API algorithm identifier.
+    const webCryptoAlgorithm = {
+      A128KW  : 'AES-KW', A192KW  : 'AES-KW', A256KW  : 'AES-KW',
+      A128GCM : 'AES-GCM', A192GCM : 'AES-GCM', A256GCM : 'AES-GCM',
+    }[unwrappedKey.alg];
+
+    if (!webCryptoAlgorithm) {
+      throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `The 'unwrappedKey' algorithm is not supported: ${unwrappedKey.alg}`);
+    }
+
+    // Import the private key to wrap for use with the Web Crypto API.
+    const unwrappedCryptoKey = await webCrypto.importKey(
+      'jwk', // key format
+      unwrappedKey as JsonWebKey, // key data
+      { name: webCryptoAlgorithm }, // algorithm identifier
+      true, // key is extractable
+      ['unwrapKey'] // key usages
+    );
+
+    // Wrap the key using the Web Crypto API.
+    const wrappedKeyBuffer = await webCrypto.wrapKey(
+      'raw', // output format
+      unwrappedCryptoKey, // key to wrap
+      encryptionCryptoKey, // wrapping key
+      'AES-KW' // algorithm identifier
+    );
+
+    // Convert from ArrayBuffer to Uint8Array.
+    const wrappedKeyBytes = new Uint8Array(wrappedKeyBuffer);
+
+    return wrappedKeyBytes;
+  }
+}

package/src/primitives/concat-kdf.ts

@@ -1,6 +1,8 @@
+import type { TypedArray } from '@noble/hashes/utils';
+
+import { concatBytes } from '@noble/hashes/utils';
 import { sha256 } from '@noble/hashes/sha256';
 import { Convert, universalTypeOf } from '@enbox/common';
-import { TypedArray, concatBytes } from '@noble/hashes/utils';
 
 /**
  * ConcatKDF FixedInfo Parameters.
@@ -45,7 +47,7 @@ export type ConcatKdfFixedInfo = {
    * to the key agreement.
    */
   suppPrivInfo?: string | TypedArray;
-}
+};
 
 /**
  * An implementation of the Concatenation Key Derivation Function (ConcatKDF)

package/src/primitives/ecies-secp256k1.ts

@@ -0,0 +1,113 @@
+import { concatBytes } from '@noble/ciphers/utils';
+import { gcm } from '@noble/ciphers/aes';
+import { hkdf } from '@noble/hashes/hkdf';
+import { randomBytes } from '@noble/ciphers/webcrypto';
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { sha256 } from '@noble/hashes/sha256';
+
+/**
+ * AEAD tag length for AES-256-GCM (16 bytes / 128 bits).
+ */
+const AEAD_TAG_LENGTH = 16;
+
+/**
+ * Nonce length for AES-256-GCM encryption.
+ */
+const NONCE_LENGTH = 16;
+
+/**
+ * Output of an ECIES-SECP256K1 encryption operation.
+ */
+export type EciesSecp256k1EncryptionOutput = {
+  /** The AES-GCM initialization vector. */
+  initializationVector: Uint8Array;
+  /** The ephemeral secp256k1 public key (compressed, 33 bytes). */
+  ephemeralPublicKey: Uint8Array;
+  /** The encrypted data. */
+  ciphertext: Uint8Array;
+  /** The AES-GCM authentication tag (16 bytes). */
+  messageAuthenticationCode: Uint8Array;
+};
+
+/**
+ * Input required for ECIES-SECP256K1 decryption.
+ */
+export type EciesSecp256k1EncryptionInput = EciesSecp256k1EncryptionOutput & {
+  /** The recipient's secp256k1 private key (raw 32 bytes). */
+  privateKey: Uint8Array;
+};
+
+/**
+ * Browser-compatible ECIES (Elliptic Curve Integrated Encryption Scheme) using secp256k1.
+ *
+ * Wire-format compatible with `eciesjs` v0.4.x configured with
+ * `isEphemeralKeyCompressed: true, isHkdfKeyCompressed: false` (the default).
+ *
+ * Protocol:
+ *   1. Generate an ephemeral secp256k1 key pair.
+ *   2. ECDH shared secret (uncompressed point).
+ *   3. HKDF-SHA-256 key derivation: `hkdf(sha256, ephemeralPubUncompressed || sharedPointUncompressed)`.
+ *   4. AES-256-GCM encryption with random 16-byte nonce.
+ *
+ * All underlying primitives (`@noble/ciphers`, `@noble/curves`, `@noble/hashes`)
+ * are pure JavaScript and work in Node, Bun, and browsers.
+ */
+export class EciesSecp256k1 {
+  /**
+   * Encrypt plaintext for a given secp256k1 public key.
+   * @param publicKeyBytes - Recipient's public key (compressed 33 bytes or uncompressed 65 bytes).
+   * @param plaintext - The data to encrypt.
+   */
+  public static encrypt(publicKeyBytes: Uint8Array, plaintext: Uint8Array): EciesSecp256k1EncryptionOutput {
+    // Generate ephemeral key pair.
+    const ephemeralPrivateKey = secp256k1.utils.randomPrivateKey();
+    const ephemeralPubCompressed = secp256k1.getPublicKey(ephemeralPrivateKey, true);
+    const ephemeralPubUncompressed = secp256k1.getPublicKey(ephemeralPrivateKey, false);
+
+    // ECDH: shared point (uncompressed).
+    const sharedPointUncompressed = secp256k1.getSharedSecret(ephemeralPrivateKey, publicKeyBytes, false);
+
+    // HKDF-SHA-256: derive 32-byte symmetric key.
+    // eciesjs (isHkdfKeyCompressed=false): master = senderPubUncompressed || sharedPointUncompressed
+    const symmetricKey = hkdf(sha256, concatBytes(ephemeralPubUncompressed, sharedPointUncompressed), undefined, undefined, 32);
+
+    // AES-256-GCM encrypt.
+    const nonce = randomBytes(NONCE_LENGTH);
+    const ciphered = gcm(symmetricKey, nonce).encrypt(plaintext); // ciphertext || tag
+
+    return {
+      ephemeralPublicKey        : ephemeralPubCompressed,
+      initializationVector      : nonce,
+      messageAuthenticationCode : ciphered.subarray(ciphered.length - AEAD_TAG_LENGTH),
+      ciphertext                : ciphered.subarray(0, ciphered.length - AEAD_TAG_LENGTH),
+    };
+  }
+
+  /**
+   * Decrypt ciphertext produced by {@link EciesSecp256k1.encrypt}.
+   * @param input - The encryption output plus the recipient's private key.
+   */
+  public static decrypt(input: EciesSecp256k1EncryptionInput): Uint8Array {
+    const { privateKey, ephemeralPublicKey, initializationVector, messageAuthenticationCode, ciphertext } = input;
+
+    // Decompress ephemeral public key (HKDF needs uncompressed form).
+    const ephemeralPubUncompressed = secp256k1.ProjectivePoint.fromHex(ephemeralPublicKey).toRawBytes(false);
+
+    // ECDH: shared point (uncompressed).
+    const sharedPointUncompressed = secp256k1.getSharedSecret(privateKey, ephemeralPublicKey, false);
+
+    // HKDF-SHA-256: derive 32-byte symmetric key (same derivation as encrypt).
+    const symmetricKey = hkdf(sha256, concatBytes(ephemeralPubUncompressed, sharedPointUncompressed), undefined, undefined, 32);
+
+    // AES-256-GCM decrypt: reconstruct the wire format (ciphertext || tag).
+    const ciphered = concatBytes(ciphertext, messageAuthenticationCode);
+    return gcm(symmetricKey, Uint8Array.from(initializationVector)).decrypt(ciphered);
+  }
+
+  /**
+   * Whether the ephemeral public key is compressed (always true for this implementation).
+   */
+  public static get isEphemeralKeyCompressed(): boolean {
+    return true;
+  }
+}

package/src/primitives/ed25519.ts

@@ -1,5 +1,5 @@
 import { Convert } from '@enbox/common';
-import { ed25519, edwardsToMontgomeryPub, edwardsToMontgomeryPriv, x25519 } from '@noble/curves/ed25519';
+import { ed25519, edwardsToMontgomeryPriv, edwardsToMontgomeryPub, x25519 } from '@noble/curves/ed25519';
 
 import type { Jwk } from '../jose/jwk.js';
 import type { ComputePublicKeyParams, GetPublicKeyParams, SignParams, VerifyParams } from '../types/params-direct.js';
@@ -86,7 +86,7 @@ export class Ed25519 {
     privateKeyBytes: Uint8Array;
   }): Promise<Jwk> {
     // Derive the public key from the private key.
-    const publicKeyBytes  = ed25519.getPublicKey(privateKeyBytes);
+    const publicKeyBytes = ed25519.getPublicKey(privateKeyBytes);
 
     // Construct the private key in JWK format.
     const privateKey: Jwk = {
@@ -167,10 +167,10 @@ export class Ed25519 {
     ComputePublicKeyParams
   ): Promise<Jwk> {
     // Convert the provided private key to a byte array.
-    const privateKeyBytes  = await Ed25519.privateKeyToBytes({ privateKey: key });
+    const privateKeyBytes = await Ed25519.privateKeyToBytes({ privateKey: key });
 
     // Derive the public key from the private key.
-    const publicKeyBytes  = ed25519.getPublicKey(privateKeyBytes);
+    const publicKeyBytes = ed25519.getPublicKey(privateKeyBytes);
 
     // Construct the public key in JWK format.
     const publicKey: Jwk = {
@@ -355,7 +355,7 @@ export class Ed25519 {
     }
 
     // Remove the private key property ('d') and make a shallow copy of the provided key.
-    let { d, ...publicKey } = key;
+    const { d, ...publicKey } = key;
 
     // If the key ID is undefined, set it to the JWK thumbprint.
     publicKey.kid ??= await computeJwkThumbprint({ jwk: publicKey });
@@ -502,7 +502,7 @@ export class Ed25519 {
       // Check if points are on the Twisted Edwards curve.
       point.assertValidity();
 
-    } catch(error: any) {
+    } catch {
       return false;
     }
 

package/src/primitives/hkdf.ts

@@ -0,0 +1,121 @@
+import type { DeriveKeyBytesParams } from '../types/params-direct.js';
+
+import { getWebcryptoSubtle } from '@noble/ciphers/webcrypto';
+
+import { Convert } from '@enbox/common';
+
+/**
+ * The object that should be passed into `Hkdf.deriveKeyBytes()`, when using the HKDF algorithm.
+ */
+export type HkdfParams = {
+  /**
+   * A string representing the digest algorithm to use. This may be one of:
+   * - 'SHA-256'
+   * - 'SHA-384'
+   * - 'SHA-512'
+   */
+  hash: 'SHA-256' | 'SHA-384' | 'SHA-512';
+
+  /**
+   * The salt value to use in the derivation process.
+   *
+   * Ideally, the salt is a random or pseudo-random value with the same length as the output of the
+   * digest function. Unlike the input key material passed into deriveKey(), salt does not need to
+   * be kept secret.
+   *
+   * Note: The {@link https://datatracker.ietf.org/doc/html/rfc5869 | HKDF specification} states
+   *       that adding salt "adds significantly to the strength of HKDF".
+   */
+  salt: string | Uint8Array;
+
+  /**
+   * Optional application-specific information to use in the HKDF.
+   *
+   * If given, this value is used to bind the derived key to application-specific contextual
+   * information. This makes it possible to derive different keys for different contexts while using
+   * the same input key material.
+   *
+   * If not provided, the `info` value is set to an empty array.
+   *
+   * Note: It is important that the `info` value be independent and unrelated to the input key
+   * material.
+   */
+  info?: string | Uint8Array,
+};
+
+/**
+ * The `Hkdf` class provides an interface for HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
+ * as defined in RFC 5869.
+ *
+ * Note: The `baseKeyBytes` that will be the input key material for HKDF should be a high-entropy secret
+ * value, such as a cryptographic key. It should be kept confidential and not be derived from a
+ * low-entropy value, such as a password.
+ *
+ * @example
+ * ```ts
+ * const info = new Uint8Array([...]);
+ * const derivedKeyBytes = await Hkdf.deriveKeyBytes({
+ *   baseKeyBytes: new Uint8Array([...]), // Input keying material
+ *   hash: 'SHA-256', // The hash function to use ('SHA-256', 'SHA-384', 'SHA-512')
+ *   salt: new Uint8Array([...]), // The salt value
+ *   info: new Uint8Array([...]), // Optional application-specific information
+ *   length: 256 // The length of the derived key in bits
+ * });
+ * ```
+ */
+export class Hkdf {
+  /**
+   * Derives a key using the HMAC-based Extract-and-Expand Key Derivation Function (HKDF).
+   *
+   * This method generates a derived key using a hash function from input keying material given as
+   * `baseKeyBytes`. The length of the derived key can be specified. Optionally, it can also use a salt
+   * and info for the derivation process.
+   *
+   * HKDF is useful in various cryptographic applications and protocols, especially when
+   * there's a need to derive multiple keys from a single source of key material.
+   *
+   * Note: The `baseKeyBytes` that will be the input key material for HKDF should be a high-entropy
+   * secret value, such as a cryptographic key. It should be kept confidential and not be derived
+   * from a low-entropy value, such as a password.
+   *
+   * @example
+   * ```ts
+   * const info = new Uint8Array([...]);
+   * const derivedKeyBytes = await Hkdf.deriveKeyBytes({
+   *   baseKeyBytes: new Uint8Array([...]), // Input keying material
+   *   hash: 'SHA-256', // The hash function to use ('SHA-256', 'SHA-384', 'SHA-512')
+   *   salt: new Uint8Array([...]), // The salt value
+   *   info: new Uint8Array([...]), // Optional application-specific information
+   *   length: 256 // The length of the derived key in bits
+   * });
+   * ```
+   *
+   * @param params - The parameters for key derivation.
+   * @returns A Promise that resolves to the derived key as a byte array.
+   */
+  public static async deriveKeyBytes({ baseKeyBytes, length, hash, salt, info = new Uint8Array() }:
+    DeriveKeyBytesParams & HkdfParams
+  ): Promise<Uint8Array> {
+    // Get the Web Crypto API interface.
+    const webCrypto = getWebcryptoSubtle() as SubtleCrypto;
+
+    // Import the baseKeyBytes into the Web Crypto API to use for the key derivation operation.
+    const webCryptoKey = await webCrypto.importKey('raw', baseKeyBytes, { name: 'HKDF' }, false, ['deriveBits']);
+
+    // Convert the salt and info to Uint8Array if they are provided as strings.
+    const saltBytes = typeof salt === 'string' ? Convert.string(salt).toUint8Array() : salt;
+    const infoBytes = typeof info === 'string' ? Convert.string(info).toUint8Array() : info;
+
+    // Derive the bytes using the Web Crypto API.
+    const derivedKeyBuffer = await webCrypto.deriveBits(
+      { name: 'HKDF', hash, salt: saltBytes, info: infoBytes },
+      webCryptoKey,
+      length
+    );
+
+    // Convert from ArrayBuffer to Uint8Array.
+    const derivedKeyBytes = new Uint8Array(derivedKeyBuffer);
+
+    return derivedKeyBytes;
+  }
+}

package/src/primitives/pbkdf2.ts

@@ -1,5 +1,38 @@
+import type { DeriveKeyBytesParams } from '../types/params-direct.js';
+
+import { getWebcryptoSubtle } from '@noble/ciphers/webcrypto';
+
 import { crypto } from '@noble/hashes/crypto';
 
+/**
+ * The object that should be passed into `Pbkdf2.deriveKeyBytes()`, when using the PBKDF2 algorithm.
+ */
+export interface Pbkdf2Params {
+  /**
+   * A string representing the digest algorithm to use. This may be one of:
+   * - 'SHA-256'
+   * - 'SHA-384'
+   * - 'SHA-512'
+   */
+  hash: 'SHA-256' | 'SHA-384' | 'SHA-512';
+
+  /**
+   * The salt value to use in the derivation process, as a Uint8Array. This should be a random or
+   * pseudo-random value of at least 16 bytes. Unlike the `password`, `salt` does not need to be
+   * kept secret.
+   */
+  salt: Uint8Array;
+
+  /**
+   * A `Number` representing the number of iterations the hash function will be executed in
+   * `deriveKey()`. This impacts the computational cost of the `deriveKey()` operation, making it
+   * more resistant to dictionary attacks. The higher the number, the more secure, but also slower,
+   * the operation. Choose a value that balances security needs and performance for your
+   * application.
+   */
+  iterations: number;
+}
+
 /**
  * The object that should be passed into `Pbkdf2.deriveKey()`, when using the PBKDF2 algorithm.
  */
@@ -119,4 +152,62 @@ export class Pbkdf2 {
 
     return derivedKey;
   }
+
+  /**
+   * Derives cryptographic key bytes from base key material using the PBKDF2 algorithm.
+   *
+   * @remarks
+   * This method is similar to {@link Pbkdf2.deriveKey | `deriveKey()`} but accepts
+   * raw key bytes (`baseKeyBytes`) instead of a password. It is intended for use cases
+   * where the input key material is already available as a byte array.
+   *
+   * Notes:
+   * - The `baseKeyBytes` that will be the input key material for PBKDF2 is expected to be a
+   *   low-entropy value, such as a password or passphrase. It should be kept confidential.
+   * - In 2023,
+   *   {@link https://web.archive.org/web/20230123232056/https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2
+   *   | OWASP recommended}
+   *   a minimum of 600,000 iterations for PBKDF2-HMAC-SHA256 and 210,000 for PBKDF2-HMAC-SHA512.
+   *
+   * @example
+   * ```ts
+   * const derivedKeyBytes = await Pbkdf2.deriveKeyBytes({
+   *   baseKeyBytes: new TextEncoder().encode('password'),
+   *   hash: 'SHA-256',
+   *   salt: new Uint8Array([...]),
+   *   iterations: 600_000,
+   *   length: 256
+   * });
+   * ```
+   *
+   * @param params - The parameters for key derivation.
+   * @returns A Promise that resolves to the derived key as a byte array.
+   */
+  public static async deriveKeyBytes({ baseKeyBytes, hash, salt, iterations, length }:
+    DeriveKeyBytesParams & Pbkdf2Params
+  ): Promise<Uint8Array> {
+    // Get the Web Crypto API interface.
+    const webCrypto = getWebcryptoSubtle() as SubtleCrypto;
+
+    // Import the password as a raw key for use with the Web Crypto API.
+    const webCryptoKey = await webCrypto.importKey(
+      'raw', // key format is raw bytes
+      baseKeyBytes, // key data to import
+      { name: 'PBKDF2' }, // algorithm identifier
+      false, // key is not extractable
+      ['deriveBits'] // key usages
+    );
+
+    // Derive the bytes using the Web Crypto API.
+    const derivedKeyBuffer = await webCrypto.deriveBits(
+      { name: 'PBKDF2', hash, salt, iterations },
+      webCryptoKey,
+      length
+    );
+
+    // Convert from ArrayBuffer to Uint8Array.
+    const derivedKeyBytes = new Uint8Array(derivedKeyBuffer);
+
+    return derivedKeyBytes;
+  }
 }