@enbox/crypto 0.0.1

package/src/algorithms/aes-ctr.ts

@@ -0,0 +1,156 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { Cipher } from '../types/cipher.js';
+import type { KeyGenerator } from '../types/key-generator.js';
+import type { DecryptParams, EncryptParams, GenerateKeyParams } from '../types/params-direct.js';
+
+import { AesCtr } from '../primitives/aes-ctr.js';
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+
+/**
+ * The `AesCtrGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the AES-CTR algorithm.
+ */
+export interface AesCtrGenerateKeyParams extends GenerateKeyParams {
+  /** Specifies the algorithm variant for key generation in AES-CTR mode.
+   * The value determines the length of the key to be generated and must be one of the following:
+   * - `"A128CTR"`: Generates a 128-bit key.
+   * - `"A192CTR"`: Generates a 192-bit key.
+   * - `"A256CTR"`: Generates a 256-bit key.
+   */
+  algorithm: 'A128CTR' | 'A192CTR' | 'A256CTR';
+}
+
+/**
+ * The `AesCtrParams` interface defines the algorithm-specific parameters that should be passed
+ * into the `encrypt()` and `decrypt()` methods when using the AES-CTR algorithm.
+ */
+export interface AesCtrParams {
+  /** The initial value of the counter block. */
+  counter: Uint8Array;
+
+  /** The number of bits in the counter block that are used for the actual counter. */
+  length: number;
+}
+
+/**
+ * The `AesCtrAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the AES algorithm in Counter (CTR) mode. This class implements both {@link Cipher | `Cipher`} and
+ * { @link KeyGenerator | `KeyGenerator`} interfaces, providing key generation, encryption, and
+ * decryption features.
+ *
+ * This class is typically accessed through implementations that extend the
+ * {@link CryptoApi | `CryptoApi`} interface.
+ */
+export class AesCtrAlgorithm extends CryptoAlgorithm
+  implements Cipher<EncryptParams & AesCtrParams, DecryptParams & AesCtrParams>,
+             KeyGenerator<AesCtrGenerateKeyParams, Jwk> {
+
+  /**
+   * Decrypts the provided data using AES-CTR.
+   *
+   * @remarks
+   * This method performs AES-CTR decryption on the given encrypted data using the specified key.
+   * Similar to the encryption process, it requires an initial counter block and the length
+   * of the counter block, along with the encrypted data and the decryption key. The method
+   * returns the decrypted data as a Uint8Array.
+   *
+   * @example
+   * ```ts
+   * const aesCtr = new AesCtrAlgorithm();
+   * const encryptedData = new Uint8Array([...]); // Encrypted data
+   * const counter = new Uint8Array(16); // 16-byte (128-bit) counter block used during encryption
+   * const key = { ... }; // A Jwk object representing the same AES key used for encryption
+   * const decryptedData = await aesCtr.decrypt({
+   *   data: encryptedData,
+   *   counter,
+   *   key,
+   *   length: 128 // Length of the counter in bits
+   * });
+   * ```
+   *
+   * @param params - The parameters for the decryption operation.
+   *
+   * @returns A Promise that resolves to the decrypted data as a Uint8Array.
+   */
+  public async decrypt(params:
+    DecryptParams & AesCtrParams
+  ): Promise<Uint8Array> {
+    const plaintext = AesCtr.decrypt(params);
+
+    return plaintext;
+  }
+
+  /**
+   * Encrypts the provided data using AES-CTR.
+   *
+   * @remarks
+   * This method performs AES-CTR encryption on the given data using the specified key.
+   * It requires the initial counter block and the length of the counter block, alongside
+   * the data and key. The method is designed to work asynchronously and returns the
+   * encrypted data as a Uint8Array.
+   *
+   * @example
+   * ```ts
+   * const aesCtr = new AesCtrAlgorithm();
+   * const data = new TextEncoder().encode('Messsage');
+   * const counter = new Uint8Array(16); // 16-byte (128-bit) counter block
+   * const key = { ... }; // A Jwk object representing an AES key
+   * const encryptedData = await aesCtr.encrypt({
+   *   data,
+   *   counter,
+   *   key,
+   *   length: 128 // Length of the counter in bits
+   * });
+   * ```
+   *
+   * @param params - The parameters for the encryption operation.
+   *
+   * @returns A Promise that resolves to the encrypted data as a Uint8Array.
+   */
+  public async encrypt(params:
+    EncryptParams & AesCtrParams
+  ): Promise<Uint8Array> {
+    const ciphertext = AesCtr.encrypt(params);
+
+    return ciphertext;
+  }
+
+  /**
+   * Generates a symmetric key for AES in Counter (CTR) mode in JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method generates a symmetric AES key for use in CTR mode, based on the specified
+   * `algorithm` parameter which determines the key length. It uses cryptographically secure random
+   * number generation to ensure the uniqueness and security of the key. The key is returned in JWK
+   * format.
+   *
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const aesCtr = new AesCtrAlgorithm();
+   * const privateKey = await aesCtr.generateKey({ algorithm: 'A256CTR' });
+   * ```
+   *
+   * @param params - The parameters for the key generation.
+   *
+   * @returns A Promise that resolves to the generated symmetric key in JWK format.
+   */
+  public async generateKey({ algorithm }:
+    AesCtrGenerateKeyParams
+  ): Promise<Jwk> {
+    // Map algorithm name to key length.
+    const length = { A128CTR: 128, A192CTR: 192, A256CTR: 256 }[algorithm] as 128 | 192 | 256;
+
+    // Generate a random private key.
+    const privateKey = await AesCtr.generateKey({ length });
+
+    // Set the `alg` property based on the specified algorithm.
+    privateKey.alg = algorithm;
+
+    return privateKey;
+  }
+}

package/src/algorithms/aes-gcm.ts

@@ -0,0 +1,187 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { Cipher } from '../types/cipher.js';
+import type { KeyGenerator } from '../types/key-generator.js';
+import type { DecryptParams, EncryptParams, GenerateKeyParams } from '../types/params-direct.js';
+
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+import { AesGcm, AES_GCM_TAG_LENGTHS } from '../primitives/aes-gcm.js';
+
+/**
+ * The `AesGcmGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the AES-GCM algorithm.
+ */
+export interface AesGcmGenerateKeyParams extends GenerateKeyParams {
+  /** Specifies the algorithm variant for key generation in AES-GCM mode.
+   * The value determines the length of the key to be generated and must be one of the following:
+   * - `"A128GCM"`: Generates a 128-bit key.
+   * - `"A192GCM"`: Generates a 192-bit key.
+   * - `"A256GCM"`: Generates a 256-bit key.
+   */
+  algorithm: 'A128GCM' | 'A192GCM' | 'A256GCM';
+}
+
+/**
+ * The `AesGcmParams` interface defines the algorithm-specific parameters that should be passed
+ * into the `encrypt()` and `decrypt()` methods when using the AES-GCM algorithm.
+ */
+export interface AesGcmParams {
+  /**
+   * The `additionalData` property is used for authentication alongside encrypted data but isn't
+   * encrypted itself. It must match in both encryption and decryption; a mismatch will cause
+   * decryption to fail. This feature allows for the authentication of data without encrypting it.
+   *
+   * The `additionalData` property is optional and omitting it does not compromise encryption
+   * security.
+   */
+  additionalData?: Uint8Array;
+
+  /**
+   * The initialization vector (IV) must be unique for every encryption operation carried out with a
+   * given key. The IV need not be secret, but it must be unpredictable: that is, the IV must not be
+   * reused with the same key. The IV must be 12 bytes (96 bits) in length in accordance with the
+   * AES-GCM specification recommendedation to promote interoperability and efficiency.
+   *
+   * Note: It is OK to transmit the IV in the clear with the encrypted message.
+   */
+  iv: Uint8Array;
+
+  /**
+   * This property determines the size in bits of the authentication tag generated in the encryption
+   * operation and used for authentication in the corresponding decryption. In accordance with the
+   * AES-GCM specification, the tag length must be 96, 104, 112, 120 or 128.
+   *
+   * The `tagLength` property is optional and defaults to 128 bits if omitted.
+   */
+  tagLength?: typeof AES_GCM_TAG_LENGTHS[number];
+}
+
+/**
+ * The `AesGcmAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the AES algorithm in Galois/Counter Mode (GCM). This class implements both
+ * {@link Cipher | `Cipher`} and { @link KeyGenerator | `KeyGenerator`} interfaces, providing
+ * key generation, encryption, and decryption features.
+ *
+ * This class is typically accessed through implementations that extend the
+ * {@link CryptoApi | `CryptoApi`} interface.
+ */
+export class AesGcmAlgorithm extends CryptoAlgorithm
+  implements Cipher<AesGcmParams, AesGcmParams>,
+             KeyGenerator<AesGcmGenerateKeyParams, Jwk> {
+
+  /**
+   * Decrypts the provided data using AES-GCM.
+   *
+   * @remarks
+   * This method performs AES-GCM decryption on the given encrypted data using the specified key.
+   * It requires an initialization vector (IV), the encrypted data along with the decryption key,
+   * and optionally, additional authenticated data (AAD). The method returns the decrypted data as a
+   * Uint8Array. The optional `tagLength` parameter specifies the size in bits of the authentication
+   * tag used when encrypting the data. If not specified, the default tag length of 128 bits is
+   * used.
+   *
+   * @example
+   * ```ts
+   * const aesGcm = new AesGcmAlgorithm();
+   * const encryptedData = new Uint8Array([...]); // Encrypted data
+   * const iv = new Uint8Array([...]); // Initialization vector used during encryption
+   * const additionalData = new Uint8Array([...]); // Optional additional authenticated data
+   * const key = { ... }; // A Jwk object representing the AES key
+   * const decryptedData = await aesGcm.decrypt({
+   *   data: encryptedData,
+   *   iv,
+   *   additionalData,
+   *   key,
+   *   tagLength: 128 // Optional tag length in bits
+   * });
+   * ```
+   *
+   * @param params - The parameters for the decryption operation.
+   *
+   * @returns A Promise that resolves to the decrypted data as a Uint8Array.
+   */
+  public async decrypt(params:
+    DecryptParams & AesGcmParams
+  ): Promise<Uint8Array> {
+    const plaintext = AesGcm.decrypt(params);
+
+    return plaintext;
+  }
+
+  /**
+   * Encrypts the provided data using AES-GCM.
+   *
+   * @remarks
+   * This method performs AES-GCM encryption on the given data using the specified key.
+   * It requires an initialization vector (IV), the encrypted data along with the decryption key,
+   * and optionally, additional authenticated data (AAD). The method returns the encrypted data as a
+   * Uint8Array. The optional `tagLength` parameter specifies the size in bits of the authentication
+   * tag generated in the encryption operation and used for authentication in the corresponding
+   * decryption. If not specified, the default tag length of 128 bits is used.
+   *
+   * @example
+   * ```ts
+   * const aesGcm = new AesGcmAlgorithm();
+   * const data = new TextEncoder().encode('Messsage');
+   * const iv = new Uint8Array([...]); // Initialization vector
+   * const additionalData = new Uint8Array([...]); // Optional additional authenticated data
+   * const key = { ... }; // A Jwk object representing an AES key
+   * const encryptedData = await aesGcm.encrypt({
+   *   data,
+   *   iv,
+   *   additionalData,
+   *   key,
+   *   tagLength: 128 // Optional tag length in bits
+   * });
+   * ```
+   *
+   * @param params - The parameters for the encryption operation.
+   *
+   * @returns A Promise that resolves to the encrypted data as a Uint8Array.
+   */
+  public async encrypt(params:
+    EncryptParams & AesGcmParams
+  ): Promise<Uint8Array> {
+    const ciphertext = AesGcm.encrypt(params);
+
+    return ciphertext;
+  }
+
+  /**
+   * Generates a symmetric key for AES in Galois/Counter Mode (GCM) in JSON Web Key (JWK) format.
+   *
+   * @remarks
+   * This method generates a symmetric AES key for use in GCM mode, based on the specified
+   * `algorithm` parameter which determines the key length. It uses cryptographically secure random
+   * number generation to ensure the uniqueness and security of the key. The key is returned in JWK
+   * format.
+   *
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const aesGcm = new AesGcmAlgorithm();
+   * const privateKey = await aesGcm.generateKey({ algorithm: 'A256GCM' });
+   * ```
+   *
+   * @param params - The parameters for the key generation.
+   *
+   * @returns A Promise that resolves to the generated symmetric key in JWK format.
+   */
+  public async generateKey({ algorithm }:
+    AesGcmGenerateKeyParams
+  ): Promise<Jwk> {
+    // Map algorithm name to key length.
+    const length = { A128GCM: 128, A192GCM: 192, A256GCM: 256 }[algorithm] as 128 | 192 | 256;
+
+    // Generate a random private key.
+    const privateKey = await AesGcm.generateKey({ length });
+
+    // Set the `alg` property based on the specified algorithm.
+    privateKey.alg = algorithm;
+
+    return privateKey;
+  }
+}

package/src/algorithms/crypto-algorithm.ts

@@ -0,0 +1,4 @@
+/**
+ * Base class for all cryptographic algorithm implementations.
+ */
+export abstract class CryptoAlgorithm {}

package/src/algorithms/ecdsa.ts

@@ -0,0 +1,269 @@
+import type { Jwk } from '../jose/jwk.js';
+import type { Signer } from '../types/signer.js';
+import type { AsymmetricKeyGenerator } from '../types/key-generator.js';
+import type { ComputePublicKeyParams, GenerateKeyParams, GetPublicKeyParams, SignParams, VerifyParams } from '../types/params-direct.js';
+
+import { Secp256k1 } from '../primitives/secp256k1.js';
+import { Secp256r1 } from '../primitives/secp256r1.js';
+import { CryptoAlgorithm } from './crypto-algorithm.js';
+import { isEcPrivateJwk, isEcPublicJwk } from '../jose/jwk.js';
+
+/**
+ * The `EcdsaGenerateKeyParams` interface defines the algorithm-specific parameters that should be
+ * passed into the `generateKey()` method when using the ECDSA algorithm.
+ */
+export interface EcdsaGenerateKeyParams extends GenerateKeyParams {
+  /**
+   * A string defining the type of key to generate. The value must be one of the following:
+   * - `"ES256"`: ECDSA using the secp256r1 (P-256) curve and SHA-256.
+   * - `"ES256K"`: ECDSA using the secp256k1 curve and SHA-256.
+   * - `"secp256k1"`: ECDSA using the secp256k1 curve and SHA-256.
+   * - `"secp256r1"`: ECDSA using the secp256r1 (P-256) curve and SHA-256.
+   */
+  algorithm: 'ES256' | 'ES256K' | 'secp256k1' | 'secp256r1';
+}
+
+/**
+ * The `EcdsaAlgorithm` class provides a concrete implementation for cryptographic operations using
+ * the Elliptic Curve Digital Signature Algorithm (ECDSA). This class implements both
+ * {@link Signer | `Signer`} and { @link AsymmetricKeyGenerator | `AsymmetricKeyGenerator`}
+ * interfaces, providing private key generation, public key derivation, and creation/verification
+ * of signatures.
+ *
+ * This class is typically accessed through implementations that extend the
+ * {@link CryptoApi | `CryptoApi`} interface.
+ */
+export class EcdsaAlgorithm extends CryptoAlgorithm
+  implements AsymmetricKeyGenerator<EcdsaGenerateKeyParams, Jwk, GetPublicKeyParams>,
+             Signer<SignParams, VerifyParams> {
+
+  /**
+   * Derives the public key in JWK format from a given private key.
+   *
+   * @remarks
+   * This method takes a private key in JWK format and derives its corresponding public key,
+   * also in JWK format. The process ensures that the derived public key correctly corresponds to
+   * the given private key.
+   *
+   * @example
+   * ```ts
+   * const ecdsa = new EcdsaAlgorithm();
+   * const privateKey = { ... }; // A Jwk object representing a private key
+   * const publicKey = await ecdsa.computePublicKey({ key: privateKey });
+   * ```
+   *
+   * @param params - The parameters for the public key derivation.
+   * @param params.key - The private key in JWK format from which to derive the public key.
+   *
+   * @returns A Promise that resolves to the derived public key in JWK format.
+   */
+  public async computePublicKey({ key }:
+    ComputePublicKeyParams
+  ): Promise<Jwk> {
+    if (!isEcPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');
+
+    switch (key.crv) {
+
+      case 'secp256k1': {
+        const publicKey = await Secp256k1.computePublicKey({ key });
+        publicKey.alg = 'ES256K';
+        return publicKey;
+      }
+
+      case 'P-256': {
+        const publicKey = await Secp256r1.computePublicKey({ key });
+        publicKey.alg = 'ES256';
+        return publicKey;
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Generates a new private key with the specified algorithm in JSON Web Key (JWK) format.
+   *
+   * @example
+   * ```ts
+   * const ecdsa = new EcdsaAlgorithm();
+   * const privateKey = await ecdsa.generateKey({ algorithm: 'ES256K' });
+   * ```
+   *
+   * @param params - The parameters for key generation.
+   * @param params.algorithm - The algorithm to use for key generation.
+   *
+   * @returns A Promise that resolves to the generated private key in JWK format.
+   */
+  public async generateKey({ algorithm }:
+    EcdsaGenerateKeyParams
+  ): Promise<Jwk> {
+    switch (algorithm) {
+
+      case 'ES256K':
+      case 'secp256k1': {
+        const privateKey = await Secp256k1.generateKey();
+        privateKey.alg = 'ES256K';
+        return privateKey;
+      }
+
+      case 'ES256':
+      case 'secp256r1': {
+        const privateKey = await Secp256r1.generateKey();
+        privateKey.alg = 'ES256';
+        return privateKey;
+      }
+    }
+  }
+
+  /**
+   * Retrieves the public key properties from a given private key in JWK format.
+   *
+   * @remarks
+   * This method extracts the public key portion from an ECDSA private key in JWK format. It does
+   * so by removing the private key property 'd' and making a shallow copy, effectively yielding the
+   * public key.
+   *
+   * Note: This method offers a significant performance advantage, being about 200 times faster
+   * than `computePublicKey()`. However, it does not mathematically validate the private key, nor
+   * does it derive the public key from the private key. It simply extracts existing public key
+   * properties from the private key object. This makes it suitable for scenarios where speed is
+   * critical and the private key's integrity is already assured.
+   *
+   * @example
+   * ```ts
+   * const ecdsa = new EcdsaAlgorithm();
+   * const privateKey = { ... }; // A Jwk object representing a private key
+   * const publicKey = await ecdsa.getPublicKey({ key: privateKey });
+   * ```
+   *
+   * @param params - The parameters for retrieving the public key properties.
+   * @param params.key - The private key in JWK format.
+   *
+   * @returns A Promise that resolves to the public key in JWK format.
+   */
+  public async getPublicKey({ key }:
+    GetPublicKeyParams
+  ): Promise<Jwk> {
+    if (!isEcPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');
+
+    switch (key.crv) {
+
+      case 'secp256k1': {
+        const publicKey = await Secp256k1.getPublicKey({ key });
+        publicKey.alg = 'ES256K';
+        return publicKey;
+      }
+
+      case 'P-256': {
+        const publicKey = await Secp256r1.getPublicKey({ key });
+        publicKey.alg = 'ES256';
+        return publicKey;
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Generates an ECDSA signature of given data using a private key.
+   *
+   * @remarks
+   * This method uses the signature algorithm determined by the given `algorithm` to sign the
+   * provided data.
+   *
+   * The signature can later be verified by parties with access to the corresponding
+   * public key, ensuring that the data has not been tampered with and was indeed signed by the
+   * holder of the private key.
+   *
+   * @example
+   * ```ts
+   * const ecdsa = new EcdsaAlgorithm();
+   * const data = new TextEncoder().encode('Message');
+   * const privateKey = { ... }; // A Jwk object representing a private key
+   * const signature = await ecdsa.sign({
+   *   key: privateKey,
+   *   data
+   * });
+   * ```
+   *
+   * @param params - The parameters for the signing operation.
+   * @param params.key - The private key to use for signing, represented in JWK format.
+   * @param params.data - The data to sign.
+   *
+   * @returns A Promise resolving to the digital signature as a `Uint8Array`.
+   */
+  public async sign({ key, data }:
+    SignParams
+  ): Promise<Uint8Array> {
+    if (!isEcPrivateJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) private key.');
+
+    switch (key.crv) {
+
+      case 'secp256k1': {
+        return await Secp256k1.sign({ key, data });
+      }
+
+      case 'P-256': {
+        return await Secp256r1.sign({ key, data });
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+
+  /**
+   * Verifies an ECDSA signature associated with the provided data using the provided key.
+   *
+   * @remarks
+   * This method uses the signature algorithm determined by the `crv` property of the provided key
+   * to check the validity of a digital signature against the original data. It confirms whether the
+   * signature was created by the holder of the corresponding private key and that the data has not
+   * been tampered with.
+   *s
+   * @example
+   * ```ts
+   * const ecdsa = new EcdsaAlgorithm();
+   * const publicKey = { ... }; // Public key in JWK format corresponding to the private key that signed the data
+   * const signature = new Uint8Array([...]); // Signature to verify
+   * const data = new TextEncoder().encode('Message');
+   * const isValid = await ecdsa.verify({
+   *   key: publicKey,
+   *   signature,
+   *   data
+   * });
+   * ```
+   *
+   * @param params - The parameters for the verification operation.
+   * @param params.key - The key to use for verification.
+   * @param params.signature - The signature to verify.
+   * @param params.data - The data to verify.
+   *
+   * @returns A Promise resolving to a boolean indicating whether the signature is valid.
+   */
+  public async verify({ key, signature, data }:
+    VerifyParams
+  ): Promise<boolean> {
+    if (!isEcPublicJwk(key)) throw new TypeError('Invalid key provided. Must be an elliptic curve (EC) public key.');
+
+    switch (key.crv) {
+
+      case 'secp256k1': {
+        return await Secp256k1.verify({ key, signature, data });
+      }
+
+      case 'P-256': {
+        return await Secp256r1.verify({ key, signature, data });
+      }
+
+      default: {
+        throw new Error(`Unsupported curve: ${key.crv}`);
+      }
+    }
+  }
+}