@alessiofrittoli/crypto-cipher 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,206 @@
+import crypto from 'crypto';
+import { CoerceToUint8ArrayInput } from '@alessiofrittoli/crypto-buffer/coercion';
+import { Cph } from './types.mjs';
+import '@alessiofrittoli/crypto-buffer';
+import 'stream';
+
+/**
+ * Utility class for AES encryption and decryption following [NIST SP 800-38D](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf) standard reccomendations.
+ */
+declare class Cipher {
+    /**
+     * Cipher default `salt` lengths.
+     */
+    static readonly SALT_LENGTH: {
+        readonly min: 16;
+        readonly max: 64;
+        readonly default: 32;
+    };
+    /**
+     * Cipher default `IV` lengths.
+     */
+    static readonly IV_LENGTH: {
+        readonly min: 8;
+        readonly max: 32;
+        readonly default: 16;
+    };
+    /**
+     * Cipher default `Auth Tag` lengths.
+     */
+    static readonly AUTH_TAG_LENGTH: {
+        readonly min: 4;
+        readonly max: 16;
+        readonly default: 16;
+    };
+    /**
+     * Cipher default `Additional Authenticated Data` lengths.
+     */
+    static readonly AAD_LENGTH: {
+        readonly min: 16;
+        readonly max: 128;
+        readonly default: 32;
+    };
+    /**
+     * Default AES algorithms used based on functionality.
+     */
+    static readonly DEFAULT_ALGORITHM: {
+        readonly buffer: "aes-256-gcm";
+        readonly stream: "aes-256-cbc";
+    };
+    /**
+     * Supported AES algorithms.
+     */
+    static readonly ALGORITHMS: Cph.AesAlgorithm[];
+    /**
+     * Encrypt in-memory data buffer.
+     *
+     * ⚠️ This is not suitable for large data. Use {@link Cipher.streamEncrypt()} or {@link Cipher.hybridEncrypt()} methods for large data encryption.
+     *
+     * @param	data	The data to encrypt.
+     * @param	secret	The secret key used to encrypt the `data`.
+     * @param	options	( Optional ) Additional options.
+     * @returns	The encrypted result Buffer.
+     */
+    static encrypt(data: CoerceToUint8ArrayInput, secret: CoerceToUint8ArrayInput, options?: Cph.Options): Buffer;
+    /**
+     * Decrypt in-memory data buffer.
+     *
+     * ⚠️ This is not suitable for large data. Use {@link Cipher.streamDecrypt()} or {@link Cipher.hybridDecrypt()} methods for large data decryption.
+     *
+     * @param	data	The data to decrypt.
+     * @param	secret	The secret key used to decrypt the `data`.
+     * @param	options	( Optional ) Additional options. Must be the same used while encrypting data.
+     * @returns	The decrypted data Buffer.
+     */
+    static decrypt(data: CoerceToUint8ArrayInput, secret: CoerceToUint8ArrayInput, options?: Cph.Options): Buffer;
+    /**
+     * Encrypt a `Readable` to a `Writable` Stream.
+     *
+     * The `Readable` Stream could be 'in-memory buffer' or 'file' based.
+     *
+     * @param	secret	The secret key used to encrypt the `data`.
+     * @param	options Additional options.
+     * @returns A new Promise that resolves `void` once stream is completed.
+     */
+    static streamEncrypt(secret: CoerceToUint8ArrayInput, options: Cph.Stream.Symmetric.EncryptOptions): Promise<void>;
+    /**
+     * Decrypt a `Readable` to a `Writable` Stream.
+     *
+     * The `Readable` Stream could be 'in-memory buffer' or 'file' based.
+     *
+     * @param	secret	The secret key used to encrypt the `data`.
+     * @param	options Additional options.
+     * @returns A new Promise that resolves `void` once stream is completed.
+     */
+    static streamDecrypt(secret: CoerceToUint8ArrayInput, options: Cph.Stream.Symmetric.DecryptOptions): Promise<void>;
+    /**
+     * Encrypt a `Readable` to a `Writable` Stream with hybird Encryption.
+     *
+     * The `Readable` Stream could be 'in-memory buffer' or 'file' based.
+     *
+     * @param	secret		The secret key used to encrypt the stream.
+     * @param	publicKey	The RSA public key used to encrypt the symmetric key.
+     * @param	options		Options for the stream encryption.
+     * @returns	A new Promise that resolves `void` once stream is completed.
+     */
+    static hybridEncrypt(secret: CoerceToUint8ArrayInput, publicKey: crypto.RsaPublicKey | crypto.RsaPrivateKey | crypto.KeyLike, options: Cph.Stream.Hybrid.EncryptOptions): Promise<void>;
+    /**
+     * Decrypt a `Readable` to a `Writable` Stream with hybrid Decryption.
+     *
+     * The `Readable` Stream could be 'in-memory buffer' or 'file' based.
+     *
+     * @param	privateKey	The RSA private key used to decrypt the symmetric key.
+     * @param	options		Options for the stream decryption.
+     * @returns	A new Promise that resolves `void` once stream is completed.
+     */
+    static hybridDecrypt(privateKey: crypto.RsaPrivateKey | crypto.KeyLike, options: Cph.Stream.Hybrid.DecryptOptions): Promise<void>;
+    /**
+     * Handle pipe flow to encrypt a Stream.
+     *
+     * @param	options Required parameters.
+     * @returns A new Promise that resolves `void` once stream is completed.
+     */
+    private static stream;
+    /**
+     * Handle pipe flow to decrypt a Stream.
+     *
+     * @param	options Required parameters.
+     * @returns A new Promise that resolves `void` once stream is completed.
+     */
+    private static decipherStream;
+    /**
+     * Extract the Cipher Encrypted Symmetric Key and Initialization Vector from an encrypted `Readable` Stream.
+     *
+     * @param	input		The `Readable` Stream.
+     * @param	keyLength	The encrypted key length in bytes. This is used to properly extract the encrypted Cipher Key and Initialization Vector.
+     * @returns	A new Promise that resolve a tuple containing the Cipher Encrypted Symmetric Key and Initialization Vector once fulfilled.
+     */
+    private static extractKeyIV;
+    /**
+     * Generates a `Scrypt` Symmetric Key and the Initialization Vector with the given options.
+     *
+     * @param	secret	The secret key.
+     * @param	options	( Optional ) Additional options.
+     *
+     * @returns An object with the generated `Key`, `IV`, `salt` and resolved `options`.
+     */
+    static newKeyIV<T extends Cph.ResolvedOptions = Cph.ResolvedOptions>(secret: CoerceToUint8ArrayInput, options?: Cph.Options): {
+        options: T;
+        Key: Buffer<ArrayBufferLike>;
+        IV: Buffer<ArrayBufferLike>;
+        AAD: Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike>;
+        salt: Buffer<ArrayBufferLike>;
+    };
+    /**
+     * Resolves the given `options` with `Cipher` defaults and constraints.
+     *
+     * @param options ( Optional ) Additional options.
+     * @returns The given `options` with `Cipher` defaults and constraints.
+     */
+    static resolveOptions<T extends Cph.ResolvedOptions = Cph.ResolvedOptions>(options?: Cph.Options): T;
+    /**
+     * Get the Initialization Vector length based on the given algorithm.
+     *
+     * @param	algorithm The algorithm in use.
+     * @param	options ( Optional ) Additional options.
+     * @returns	The Initialization Vector length based on the given algorithm
+     */
+    private static getIVLength;
+    /**
+     * Ensure correct key length based on the given algorithm.
+     *
+     * @param	algorithm The AES algorithm name.
+     * @returns	An object with validated `algorithm` and `keyLength`.
+     */
+    private static getKeyLength;
+    /**
+     * Check if the given algorithm is a Cipher AES-GCM algorithm.
+     *
+     * @param algorithm The AES Algorithm to check.
+     * @returns `true` if the given algorithm is a Cipher AES-GCM algorithm. `false` otherwise.
+     */
+    static isGCM(algorithm: Cph.AesAlgorithm): algorithm is crypto.CipherGCMTypes;
+    /**
+     * Check if the given algorithm is a Cipher AES-CCM algorithm.
+     *
+     * @param algorithm The AES Algorithm to check.
+     * @returns `true` if the given algorithm is a Cipher AES-CCM algorithm. `false` otherwise.
+     */
+    static isCCM(algorithm: Cph.AesAlgorithm): algorithm is crypto.CipherCCMTypes;
+    /**
+     * Check if the given algorithm is a Cipher AES-OCB algorithm.
+     *
+     * @param algorithm The AES Algorithm to check.
+     * @returns `true` if the given algorithm is a Cipher AES-OCB algorithm. `false` otherwise.
+     */
+    static isOCB(algorithm: Cph.AesAlgorithm): algorithm is crypto.CipherOCBTypes;
+    /**
+     * Check if the given algorithm is a Cipher AES-CBC algorithm.
+     *
+     * @param algorithm The AES Algorithm to check.
+     * @returns `true` if the given algorithm is a Cipher AES-CBC algorithm. `false` otherwise.
+     */
+    static isCBC(algorithm: Cph.AesAlgorithm): algorithm is Cph.CBCTypes;
+}
+
+export { Cipher };

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+import crypto from 'crypto';
+import { CoerceToUint8ArrayInput } from '@alessiofrittoli/crypto-buffer/coercion';
+import { Cph } from './types.js';
+import '@alessiofrittoli/crypto-buffer';
+import 'stream';
+
+/**
+ * Utility class for AES encryption and decryption following [NIST SP 800-38D](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf) standard reccomendations.
+ */
+declare class Cipher {
+    /**
+     * Cipher default `salt` lengths.
+     */
+    static readonly SALT_LENGTH: {
+        readonly min: 16;
+        readonly max: 64;
+        readonly default: 32;
+    };
+    /**
+     * Cipher default `IV` lengths.
+     */
+    static readonly IV_LENGTH: {
+        readonly min: 8;
+        readonly max: 32;
+        readonly default: 16;
+    };
+    /**
+     * Cipher default `Auth Tag` lengths.
+     */
+    static readonly AUTH_TAG_LENGTH: {
+        readonly min: 4;
+        readonly max: 16;
+        readonly default: 16;
+    };
+    /**
+     * Cipher default `Additional Authenticated Data` lengths.
+     */
+    static readonly AAD_LENGTH: {
+        readonly min: 16;
+        readonly max: 128;
+        readonly default: 32;
+    };
+    /**
+     * Default AES algorithms used based on functionality.
+     */
+    static readonly DEFAULT_ALGORITHM: {
+        readonly buffer: "aes-256-gcm";
+        readonly stream: "aes-256-cbc";
+    };
+    /**
+     * Supported AES algorithms.
+     */
+    static readonly ALGORITHMS: Cph.AesAlgorithm[];
+    /**
+     * Encrypt in-memory data buffer.
+     *
+     * ⚠️ This is not suitable for large data. Use {@link Cipher.streamEncrypt()} or {@link Cipher.hybridEncrypt()} methods for large data encryption.
+     *
+     * @param	data	The data to encrypt.
+     * @param	secret	The secret key used to encrypt the `data`.
+     * @param	options	( Optional ) Additional options.
+     * @returns	The encrypted result Buffer.
+     */
+    static encrypt(data: CoerceToUint8ArrayInput, secret: CoerceToUint8ArrayInput, options?: Cph.Options): Buffer;
+    /**
+     * Decrypt in-memory data buffer.
+     *
+     * ⚠️ This is not suitable for large data. Use {@link Cipher.streamDecrypt()} or {@link Cipher.hybridDecrypt()} methods for large data decryption.
+     *
+     * @param	data	The data to decrypt.
+     * @param	secret	The secret key used to decrypt the `data`.
+     * @param	options	( Optional ) Additional options. Must be the same used while encrypting data.
+     * @returns	The decrypted data Buffer.
+     */
+    static decrypt(data: CoerceToUint8ArrayInput, secret: CoerceToUint8ArrayInput, options?: Cph.Options): Buffer;
+    /**
+     * Encrypt a `Readable` to a `Writable` Stream.
+     *
+     * The `Readable` Stream could be 'in-memory buffer' or 'file' based.
+     *
+     * @param	secret	The secret key used to encrypt the `data`.
+     * @param	options Additional options.
+     * @returns A new Promise that resolves `void` once stream is completed.
+     */
+    static streamEncrypt(secret: CoerceToUint8ArrayInput, options: Cph.Stream.Symmetric.EncryptOptions): Promise<void>;
+    /**
+     * Decrypt a `Readable` to a `Writable` Stream.
+     *
+     * The `Readable` Stream could be 'in-memory buffer' or 'file' based.
+     *
+     * @param	secret	The secret key used to encrypt the `data`.
+     * @param	options Additional options.
+     * @returns A new Promise that resolves `void` once stream is completed.
+     */
+    static streamDecrypt(secret: CoerceToUint8ArrayInput, options: Cph.Stream.Symmetric.DecryptOptions): Promise<void>;
+    /**
+     * Encrypt a `Readable` to a `Writable` Stream with hybird Encryption.
+     *
+     * The `Readable` Stream could be 'in-memory buffer' or 'file' based.
+     *
+     * @param	secret		The secret key used to encrypt the stream.
+     * @param	publicKey	The RSA public key used to encrypt the symmetric key.
+     * @param	options		Options for the stream encryption.
+     * @returns	A new Promise that resolves `void` once stream is completed.
+     */
+    static hybridEncrypt(secret: CoerceToUint8ArrayInput, publicKey: crypto.RsaPublicKey | crypto.RsaPrivateKey | crypto.KeyLike, options: Cph.Stream.Hybrid.EncryptOptions): Promise<void>;
+    /**
+     * Decrypt a `Readable` to a `Writable` Stream with hybrid Decryption.
+     *
+     * The `Readable` Stream could be 'in-memory buffer' or 'file' based.
+     *
+     * @param	privateKey	The RSA private key used to decrypt the symmetric key.
+     * @param	options		Options for the stream decryption.
+     * @returns	A new Promise that resolves `void` once stream is completed.
+     */
+    static hybridDecrypt(privateKey: crypto.RsaPrivateKey | crypto.KeyLike, options: Cph.Stream.Hybrid.DecryptOptions): Promise<void>;
+    /**
+     * Handle pipe flow to encrypt a Stream.
+     *
+     * @param	options Required parameters.
+     * @returns A new Promise that resolves `void` once stream is completed.
+     */
+    private static stream;
+    /**
+     * Handle pipe flow to decrypt a Stream.
+     *
+     * @param	options Required parameters.
+     * @returns A new Promise that resolves `void` once stream is completed.
+     */
+    private static decipherStream;
+    /**
+     * Extract the Cipher Encrypted Symmetric Key and Initialization Vector from an encrypted `Readable` Stream.
+     *
+     * @param	input		The `Readable` Stream.
+     * @param	keyLength	The encrypted key length in bytes. This is used to properly extract the encrypted Cipher Key and Initialization Vector.
+     * @returns	A new Promise that resolve a tuple containing the Cipher Encrypted Symmetric Key and Initialization Vector once fulfilled.
+     */
+    private static extractKeyIV;
+    /**
+     * Generates a `Scrypt` Symmetric Key and the Initialization Vector with the given options.
+     *
+     * @param	secret	The secret key.
+     * @param	options	( Optional ) Additional options.
+     *
+     * @returns An object with the generated `Key`, `IV`, `salt` and resolved `options`.
+     */
+    static newKeyIV<T extends Cph.ResolvedOptions = Cph.ResolvedOptions>(secret: CoerceToUint8ArrayInput, options?: Cph.Options): {
+        options: T;
+        Key: Buffer<ArrayBufferLike>;
+        IV: Buffer<ArrayBufferLike>;
+        AAD: Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike>;
+        salt: Buffer<ArrayBufferLike>;
+    };
+    /**
+     * Resolves the given `options` with `Cipher` defaults and constraints.
+     *
+     * @param options ( Optional ) Additional options.
+     * @returns The given `options` with `Cipher` defaults and constraints.
+     */
+    static resolveOptions<T extends Cph.ResolvedOptions = Cph.ResolvedOptions>(options?: Cph.Options): T;
+    /**
+     * Get the Initialization Vector length based on the given algorithm.
+     *
+     * @param	algorithm The algorithm in use.
+     * @param	options ( Optional ) Additional options.
+     * @returns	The Initialization Vector length based on the given algorithm
+     */
+    private static getIVLength;
+    /**
+     * Ensure correct key length based on the given algorithm.
+     *
+     * @param	algorithm The AES algorithm name.
+     * @returns	An object with validated `algorithm` and `keyLength`.
+     */
+    private static getKeyLength;
+    /**
+     * Check if the given algorithm is a Cipher AES-GCM algorithm.
+     *
+     * @param algorithm The AES Algorithm to check.
+     * @returns `true` if the given algorithm is a Cipher AES-GCM algorithm. `false` otherwise.
+     */
+    static isGCM(algorithm: Cph.AesAlgorithm): algorithm is crypto.CipherGCMTypes;
+    /**
+     * Check if the given algorithm is a Cipher AES-CCM algorithm.
+     *
+     * @param algorithm The AES Algorithm to check.
+     * @returns `true` if the given algorithm is a Cipher AES-CCM algorithm. `false` otherwise.
+     */
+    static isCCM(algorithm: Cph.AesAlgorithm): algorithm is crypto.CipherCCMTypes;
+    /**
+     * Check if the given algorithm is a Cipher AES-OCB algorithm.
+     *
+     * @param algorithm The AES Algorithm to check.
+     * @returns `true` if the given algorithm is a Cipher AES-OCB algorithm. `false` otherwise.
+     */
+    static isOCB(algorithm: Cph.AesAlgorithm): algorithm is crypto.CipherOCBTypes;
+    /**
+     * Check if the given algorithm is a Cipher AES-CBC algorithm.
+     *
+     * @param algorithm The AES Algorithm to check.
+     * @returns `true` if the given algorithm is a Cipher AES-CBC algorithm. `false` otherwise.
+     */
+    static isCBC(algorithm: Cph.AesAlgorithm): algorithm is Cph.CBCTypes;
+}
+
+export { Cipher };

package/dist/index.js

@@ -0,0 +1 @@
+'use strict';var u=require('crypto'),stream=require('stream'),coercion=require('@alessiofrittoli/crypto-buffer/coercion');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var u__default=/*#__PURE__*/_interopDefault(u);var t=class t{static encrypt(a,e,o={}){let r=coercion.coerceToUint8Array(a),{salt:n,Key:c,IV:i,AAD:p,options:{algorithm:s,authTag:h}}=t.newKeyIV(e,o);if(t.isCBC(s)){let d=u__default.default.createCipheriv(s,c,i),f=Buffer.concat([d.update(r),d.final()]);return Buffer.concat([n,i,f])}let y=u__default.default.createCipheriv(s,c,i,{authTagLength:h});t.isCCM(s)&&y.setAAD(p,{plaintextLength:r.length}),(t.isGCM(s)||t.isOCB(s))&&y.setAAD(p);let m=Buffer.concat([y.update(r),y.final()]),l=y.getAuthTag();return Buffer.concat([n,i,p,l,m])}static decrypt(a,e,o={}){let r=coercion.coerceToUint8Array(a),n=coercion.coerceToUint8Array(e),c=t.resolveOptions(o),{algorithm:i}=c,p=r.subarray(0,c.salt);r=r.subarray(c.salt);let s=r.subarray(0,c.iv);r=r.subarray(c.iv);let h=u__default.default.scryptSync(n,p,c.length);if(t.isCBC(i)){let T=u__default.default.createDecipheriv(c.algorithm,h,s);return Buffer.concat([T.update(r),T.final()])}let y=c.aadLength,m=c.authTag,l=r.subarray(0,y);r=r.subarray(y);let d=r.subarray(0,m);r=r.subarray(m);let f=u__default.default.createDecipheriv(i,h,s,{authTagLength:m});return t.isCCM(i)&&f.setAAD(l,{plaintextLength:r.length}),(t.isGCM(i)||t.isOCB(i))&&f.setAAD(l),f.setAuthTag(d),Buffer.concat([f.update(r),f.final()])}static streamEncrypt(a,e){e.algorithm||(e.algorithm=t.DEFAULT_ALGORITHM.stream);let{Key:o,IV:r,options:{input:n,output:c,algorithm:i,salt:p,iv:s,authTag:h}}=t.newKeyIV(a,e),y=t.encrypt(Buffer.concat([o,r]),a,{algorithm:i,salt:p,iv:s,authTag:h});return t.stream({Key:o,IV:r,input:n,output:c,encryptedKey:y,algorithm:i})}static streamDecrypt(a,e){e.algorithm||(e.algorithm=t.DEFAULT_ALGORITHM.stream);let{input:o,output:r,algorithm:n,salt:c,iv:i,authTag:p,length:s}=t.resolveOptions(e),h=s+i+c+i+p;return t.extractKeyIV(o,h).then(([y,m])=>{if(m.errored)throw m.errored;let l=t.decrypt(y,a,{algorithm:n,salt:c,iv:i,authTag:p});return t.decipherStream({KeyIV:l,length:s,input:m,output:r,algorithm:n})})}static hybridEncrypt(a,e,o){o.algorithm||(o.algorithm=t.DEFAULT_ALGORITHM.stream);let{Key:r,IV:n,options:{algorithm:c,input:i,output:p}}=t.newKeyIV(a,o),s=u__default.default.publicEncrypt(e,Buffer.concat([r,n]));return t.stream({Key:r,IV:n,input:i,output:p,encryptedKey:s,algorithm:c})}static hybridDecrypt(a,e){e.algorithm||(e.algorithm=t.DEFAULT_ALGORITHM.stream);let{input:o,output:r,algorithm:n,length:c,rsaKeyLength:i}=t.resolveOptions(e);return t.extractKeyIV(o,i).then(([p,s])=>{if(s.errored)throw s.errored;let h=u__default.default.privateDecrypt(a,p);return t.decipherStream({KeyIV:h,length:c,input:s,output:r,algorithm:n})})}static stream(a){let{Key:e,IV:o,encryptedKey:r,input:n,output:c,algorithm:i}=a;return new Promise((p,s)=>{let h=u__default.default.createCipheriv(i,e,o);h.on("error",s),n.on("error",s),c.on("error",s),c.on("finish",p),c.write(r),n.pipe(h).pipe(c);})}static decipherStream(a){let{KeyIV:e,length:o,algorithm:r,input:n,output:c}=a;return new Promise((i,p)=>{let s=e.subarray(0,o),h=e.subarray(o),y=u__default.default.createDecipheriv(r,s,h);y.on("error",p),n.on("error",p),c.on("error",p),c.on("finish",i),n.pipe(y).pipe(c);})}static extractKeyIV(a,e){return new Promise((o,r)=>{let n=Buffer.alloc(0),c=0,i=false,p=new stream.Transform({async transform(s,h,y){if(n.length<e&&(n=Buffer.concat([n,s])),c+=s.length,n.length>e){let m=Math.max(0,n.length-e);n=n.subarray(0,e);let l=s.subarray(m*-1);return i||(o([n,this]),i=true),this.push(l,h),y()}return c>e&&(i||(o([n,this]),i=true),this.push(s,h)),y()},final(s){return n.length<e?s(new Error("The extracted KeyIV length is less than the expected length.")):s()}});p.on("error",r),a.on("error",s=>{p.destroy(s),r(s);}),a.pipe(p);})}static newKeyIV(a,e={}){let o=coercion.coerceToUint8Array(a),r=t.resolveOptions(e),n=u__default.default.randomBytes(r.salt),c=u__default.default.scryptSync(o,n,r.length),i=u__default.default.randomBytes(r.iv),p=r.aad||u__default.default.scryptSync(c,n,r.aadLength);return {options:r,Key:c,IV:i,AAD:p,salt:n}}static resolveOptions(a={}){let e={...a};e.aad&&(e.aad=coercion.coerceToUint8Array(e.aad)),e.salt||(e.salt=t.SALT_LENGTH.default),e.authTag||(e.authTag=t.AUTH_TAG_LENGTH.default),e.aadLength=e.aad?.length||e.aadLength||t.AAD_LENGTH.default,e.salt=Math.min(Math.max(e.salt,t.SALT_LENGTH.min),t.SALT_LENGTH.max),e.authTag=Math.min(Math.max(e.authTag,t.AUTH_TAG_LENGTH.min),t.AUTH_TAG_LENGTH.max),e.aad||(e.aadLength=Math.min(Math.max(e.aadLength,t.AAD_LENGTH.min),t.AAD_LENGTH.max));let{keyLength:o,algorithm:r}=t.getKeyLength(a.algorithm);return e.algorithm=r,e.length=o,e.iv=t.getIVLength(r,a),e}static getIVLength(a=t.DEFAULT_ALGORITHM.buffer,e={}){switch(a){case "aes-128-ccm":case "aes-128-ocb":case "aes-192-ccm":case "aes-192-ocb":case "aes-256-ccm":case "aes-256-ocb":return 8;case "chacha20-poly1305":return 12;default:return Math.min(Math.max(e.iv||t.IV_LENGTH.default,t.IV_LENGTH.min),t.IV_LENGTH.max)}}static getKeyLength(a=t.DEFAULT_ALGORITHM.buffer){switch(a){case "chacha20-poly1305":return {algorithm:a,keyLength:256/8};case "aes-128-cbc":case "aes-128-ccm":case "aes-128-gcm":case "aes-128-ocb":return {algorithm:a,keyLength:128/8};case "aes-192-cbc":case "aes-192-ccm":case "aes-192-gcm":case "aes-192-ocb":return {algorithm:a,keyLength:192/8};case "aes-256-cbc":case "aes-256-ccm":case "aes-256-gcm":case "aes-256-ocb":default:return {algorithm:a,keyLength:256/8}}}static isGCM(a){return a==="aes-128-gcm"||a==="aes-192-gcm"||a==="aes-256-gcm"}static isCCM(a){return a==="aes-128-ccm"||a==="aes-192-ccm"||a==="aes-256-ccm"||a==="chacha20-poly1305"}static isOCB(a){return a==="aes-128-ocb"||a==="aes-192-ocb"||a==="aes-256-ocb"}static isCBC(a){return a==="aes-128-cbc"||a==="aes-192-cbc"||a==="aes-256-cbc"}};t.SALT_LENGTH={min:16,max:64,default:32},t.IV_LENGTH={min:8,max:32,default:16},t.AUTH_TAG_LENGTH={min:4,max:16,default:16},t.AAD_LENGTH={min:16,max:128,default:32},t.DEFAULT_ALGORITHM={buffer:"aes-256-gcm",stream:"aes-256-cbc"},t.ALGORITHMS=["aes-128-cbc","aes-128-ccm","aes-128-gcm","aes-128-ocb","aes-192-cbc","aes-192-ccm","aes-192-gcm","aes-192-ocb","aes-256-cbc","aes-256-ccm","aes-256-gcm","aes-256-ocb","chacha20-poly1305"];var A=t;exports.Cipher=A;

package/dist/index.mjs

@@ -0,0 +1 @@
+import u from'crypto';import {Transform}from'stream';import {coerceToUint8Array}from'@alessiofrittoli/crypto-buffer/coercion';var t=class t{static encrypt(a,e,o={}){let r=coerceToUint8Array(a),{salt:n,Key:c,IV:i,AAD:p,options:{algorithm:s,authTag:h}}=t.newKeyIV(e,o);if(t.isCBC(s)){let d=u.createCipheriv(s,c,i),f=Buffer.concat([d.update(r),d.final()]);return Buffer.concat([n,i,f])}let y=u.createCipheriv(s,c,i,{authTagLength:h});t.isCCM(s)&&y.setAAD(p,{plaintextLength:r.length}),(t.isGCM(s)||t.isOCB(s))&&y.setAAD(p);let m=Buffer.concat([y.update(r),y.final()]),l=y.getAuthTag();return Buffer.concat([n,i,p,l,m])}static decrypt(a,e,o={}){let r=coerceToUint8Array(a),n=coerceToUint8Array(e),c=t.resolveOptions(o),{algorithm:i}=c,p=r.subarray(0,c.salt);r=r.subarray(c.salt);let s=r.subarray(0,c.iv);r=r.subarray(c.iv);let h=u.scryptSync(n,p,c.length);if(t.isCBC(i)){let T=u.createDecipheriv(c.algorithm,h,s);return Buffer.concat([T.update(r),T.final()])}let y=c.aadLength,m=c.authTag,l=r.subarray(0,y);r=r.subarray(y);let d=r.subarray(0,m);r=r.subarray(m);let f=u.createDecipheriv(i,h,s,{authTagLength:m});return t.isCCM(i)&&f.setAAD(l,{plaintextLength:r.length}),(t.isGCM(i)||t.isOCB(i))&&f.setAAD(l),f.setAuthTag(d),Buffer.concat([f.update(r),f.final()])}static streamEncrypt(a,e){e.algorithm||(e.algorithm=t.DEFAULT_ALGORITHM.stream);let{Key:o,IV:r,options:{input:n,output:c,algorithm:i,salt:p,iv:s,authTag:h}}=t.newKeyIV(a,e),y=t.encrypt(Buffer.concat([o,r]),a,{algorithm:i,salt:p,iv:s,authTag:h});return t.stream({Key:o,IV:r,input:n,output:c,encryptedKey:y,algorithm:i})}static streamDecrypt(a,e){e.algorithm||(e.algorithm=t.DEFAULT_ALGORITHM.stream);let{input:o,output:r,algorithm:n,salt:c,iv:i,authTag:p,length:s}=t.resolveOptions(e),h=s+i+c+i+p;return t.extractKeyIV(o,h).then(([y,m])=>{if(m.errored)throw m.errored;let l=t.decrypt(y,a,{algorithm:n,salt:c,iv:i,authTag:p});return t.decipherStream({KeyIV:l,length:s,input:m,output:r,algorithm:n})})}static hybridEncrypt(a,e,o){o.algorithm||(o.algorithm=t.DEFAULT_ALGORITHM.stream);let{Key:r,IV:n,options:{algorithm:c,input:i,output:p}}=t.newKeyIV(a,o),s=u.publicEncrypt(e,Buffer.concat([r,n]));return t.stream({Key:r,IV:n,input:i,output:p,encryptedKey:s,algorithm:c})}static hybridDecrypt(a,e){e.algorithm||(e.algorithm=t.DEFAULT_ALGORITHM.stream);let{input:o,output:r,algorithm:n,length:c,rsaKeyLength:i}=t.resolveOptions(e);return t.extractKeyIV(o,i).then(([p,s])=>{if(s.errored)throw s.errored;let h=u.privateDecrypt(a,p);return t.decipherStream({KeyIV:h,length:c,input:s,output:r,algorithm:n})})}static stream(a){let{Key:e,IV:o,encryptedKey:r,input:n,output:c,algorithm:i}=a;return new Promise((p,s)=>{let h=u.createCipheriv(i,e,o);h.on("error",s),n.on("error",s),c.on("error",s),c.on("finish",p),c.write(r),n.pipe(h).pipe(c);})}static decipherStream(a){let{KeyIV:e,length:o,algorithm:r,input:n,output:c}=a;return new Promise((i,p)=>{let s=e.subarray(0,o),h=e.subarray(o),y=u.createDecipheriv(r,s,h);y.on("error",p),n.on("error",p),c.on("error",p),c.on("finish",i),n.pipe(y).pipe(c);})}static extractKeyIV(a,e){return new Promise((o,r)=>{let n=Buffer.alloc(0),c=0,i=false,p=new Transform({async transform(s,h,y){if(n.length<e&&(n=Buffer.concat([n,s])),c+=s.length,n.length>e){let m=Math.max(0,n.length-e);n=n.subarray(0,e);let l=s.subarray(m*-1);return i||(o([n,this]),i=true),this.push(l,h),y()}return c>e&&(i||(o([n,this]),i=true),this.push(s,h)),y()},final(s){return n.length<e?s(new Error("The extracted KeyIV length is less than the expected length.")):s()}});p.on("error",r),a.on("error",s=>{p.destroy(s),r(s);}),a.pipe(p);})}static newKeyIV(a,e={}){let o=coerceToUint8Array(a),r=t.resolveOptions(e),n=u.randomBytes(r.salt),c=u.scryptSync(o,n,r.length),i=u.randomBytes(r.iv),p=r.aad||u.scryptSync(c,n,r.aadLength);return {options:r,Key:c,IV:i,AAD:p,salt:n}}static resolveOptions(a={}){let e={...a};e.aad&&(e.aad=coerceToUint8Array(e.aad)),e.salt||(e.salt=t.SALT_LENGTH.default),e.authTag||(e.authTag=t.AUTH_TAG_LENGTH.default),e.aadLength=e.aad?.length||e.aadLength||t.AAD_LENGTH.default,e.salt=Math.min(Math.max(e.salt,t.SALT_LENGTH.min),t.SALT_LENGTH.max),e.authTag=Math.min(Math.max(e.authTag,t.AUTH_TAG_LENGTH.min),t.AUTH_TAG_LENGTH.max),e.aad||(e.aadLength=Math.min(Math.max(e.aadLength,t.AAD_LENGTH.min),t.AAD_LENGTH.max));let{keyLength:o,algorithm:r}=t.getKeyLength(a.algorithm);return e.algorithm=r,e.length=o,e.iv=t.getIVLength(r,a),e}static getIVLength(a=t.DEFAULT_ALGORITHM.buffer,e={}){switch(a){case "aes-128-ccm":case "aes-128-ocb":case "aes-192-ccm":case "aes-192-ocb":case "aes-256-ccm":case "aes-256-ocb":return 8;case "chacha20-poly1305":return 12;default:return Math.min(Math.max(e.iv||t.IV_LENGTH.default,t.IV_LENGTH.min),t.IV_LENGTH.max)}}static getKeyLength(a=t.DEFAULT_ALGORITHM.buffer){switch(a){case "chacha20-poly1305":return {algorithm:a,keyLength:256/8};case "aes-128-cbc":case "aes-128-ccm":case "aes-128-gcm":case "aes-128-ocb":return {algorithm:a,keyLength:128/8};case "aes-192-cbc":case "aes-192-ccm":case "aes-192-gcm":case "aes-192-ocb":return {algorithm:a,keyLength:192/8};case "aes-256-cbc":case "aes-256-ccm":case "aes-256-gcm":case "aes-256-ocb":default:return {algorithm:a,keyLength:256/8}}}static isGCM(a){return a==="aes-128-gcm"||a==="aes-192-gcm"||a==="aes-256-gcm"}static isCCM(a){return a==="aes-128-ccm"||a==="aes-192-ccm"||a==="aes-256-ccm"||a==="chacha20-poly1305"}static isOCB(a){return a==="aes-128-ocb"||a==="aes-192-ocb"||a==="aes-256-ocb"}static isCBC(a){return a==="aes-128-cbc"||a==="aes-192-cbc"||a==="aes-256-cbc"}};t.SALT_LENGTH={min:16,max:64,default:32},t.IV_LENGTH={min:8,max:32,default:16},t.AUTH_TAG_LENGTH={min:4,max:16,default:16},t.AAD_LENGTH={min:16,max:128,default:32},t.DEFAULT_ALGORITHM={buffer:"aes-256-gcm",stream:"aes-256-cbc"},t.ALGORITHMS=["aes-128-cbc","aes-128-ccm","aes-128-gcm","aes-128-ocb","aes-192-cbc","aes-192-ccm","aes-192-gcm","aes-192-ocb","aes-256-cbc","aes-256-ccm","aes-256-gcm","aes-256-ocb","chacha20-poly1305"];var A=t;export{A as Cipher};

package/dist/types.d.mts

@@ -0,0 +1,89 @@
+import { CoerceToUint8ArrayInput } from '@alessiofrittoli/crypto-buffer';
+import crypto from 'crypto';
+import { Readable, Writable } from 'stream';
+
+declare namespace Cph {
+    /** Cipher CBC algorithm types. */
+    type CBCTypes = 'aes-128-cbc' | 'aes-192-cbc' | 'aes-256-cbc';
+    /** Cipher supported algorithm types. */
+    type AesAlgorithm = (crypto.CipherCCMTypes | crypto.CipherGCMTypes | crypto.CipherOCBTypes | Cph.CBCTypes);
+    /**
+     * Common Cipher options.
+     * @template T The AES algorithm type.
+     */
+    interface Options<T extends Cph.AesAlgorithm = Cph.AesAlgorithm> {
+        /** The Cipher algorithm to use. Default: `aes-256-gcm` | `aes-256-cbc`. */
+        algorithm?: T;
+        /** The salt length. Minimum: `16`, Maximum: `64`. Default: `32`. */
+        salt?: number;
+        /** The `IV` length. Minimum: `8`, Maximum: `32`. Default: `16`. */
+        iv?: number;
+        /** The `authTag` length. Minimum: `4`, Maximum: `16`. Default: `16`. */
+        authTag?: number;
+        /** Custom `Additional Authenticated Data`. */
+        aad?: CoerceToUint8ArrayInput;
+        /** The `AAD` length. Minimum: `16`, Maximum: `128`. Default: `32`. */
+        aadLength?: number;
+    }
+    /**
+     * Resolved Common options.
+     */
+    interface ResolvedOptions<T extends Cph.AesAlgorithm = Cph.AesAlgorithm> extends Required<Omit<Cph.Options<T>, 'aad'>> {
+        /** The symmetric key length. */
+        length: number;
+        aad?: Uint8Array;
+    }
+    namespace Stream {
+        namespace Symmetric {
+            /**
+             * Options for encrypting a stream.
+             */
+            interface EncryptOptions extends Cph.Options<Cph.CBCTypes> {
+                /** The `Readable` Stream from where raw data to encrypt is read. */
+                input: Readable;
+                /** The `Writable` Stream where encrypted data is written. */
+                output: Writable;
+            }
+            /**
+             * Resolved Stream Encrypt options (symmetric and hybrid).
+             */
+            type EncryptResolvedOptions = (Cph.ResolvedOptions & Required<Cph.Stream.Symmetric.EncryptOptions>);
+            /**
+             * Options for decrypting a stream (symmetric).
+             */
+            interface DecryptOptions extends Cph.Stream.Symmetric.EncryptOptions {
+                /** The `Readable` Stream from where encrypted data is read. */
+                input: Readable;
+                /** The `Writable` Stream where decrypted data is written. */
+                output: Writable;
+            }
+            /**
+             * Resolved Stream Decrypt options (symmetric).
+             */
+            type DecryptResolvedOptions = (Cph.ResolvedOptions & Required<Cph.Stream.Symmetric.DecryptOptions>);
+        }
+        namespace Hybrid {
+            /**
+             * Alias for {@link Cph.Stream.Symmetric.EncryptOptions}
+             */
+            type EncryptOptions = Cph.Stream.Symmetric.EncryptOptions;
+            /**
+             * Alias for {@link Cph.Stream.Symmetric.EncryptResolvedOptions}
+             */
+            type EncryptResolvedOptions = Cph.Stream.Symmetric.EncryptResolvedOptions;
+            /**
+             * Options for decrypting a stream.
+             */
+            interface DecryptOptions extends Cph.Stream.Symmetric.DecryptOptions {
+                /** The RSA key length in bytes used while encrypting data. This is used to properly extract the encrypted Cipher Key and Initialization Vector. */
+                rsaKeyLength: number;
+            }
+            /**
+             * Resolved Stream Decrypt options.
+             */
+            type DecryptResolvedOptions = (Cph.ResolvedOptions & Required<Cph.Stream.Hybrid.DecryptOptions>);
+        }
+    }
+}
+
+export { Cph };

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+import { CoerceToUint8ArrayInput } from '@alessiofrittoli/crypto-buffer';
+import crypto from 'crypto';
+import { Readable, Writable } from 'stream';
+
+declare namespace Cph {
+    /** Cipher CBC algorithm types. */
+    type CBCTypes = 'aes-128-cbc' | 'aes-192-cbc' | 'aes-256-cbc';
+    /** Cipher supported algorithm types. */
+    type AesAlgorithm = (crypto.CipherCCMTypes | crypto.CipherGCMTypes | crypto.CipherOCBTypes | Cph.CBCTypes);
+    /**
+     * Common Cipher options.
+     * @template T The AES algorithm type.
+     */
+    interface Options<T extends Cph.AesAlgorithm = Cph.AesAlgorithm> {
+        /** The Cipher algorithm to use. Default: `aes-256-gcm` | `aes-256-cbc`. */
+        algorithm?: T;
+        /** The salt length. Minimum: `16`, Maximum: `64`. Default: `32`. */
+        salt?: number;
+        /** The `IV` length. Minimum: `8`, Maximum: `32`. Default: `16`. */
+        iv?: number;
+        /** The `authTag` length. Minimum: `4`, Maximum: `16`. Default: `16`. */
+        authTag?: number;
+        /** Custom `Additional Authenticated Data`. */
+        aad?: CoerceToUint8ArrayInput;
+        /** The `AAD` length. Minimum: `16`, Maximum: `128`. Default: `32`. */
+        aadLength?: number;
+    }
+    /**
+     * Resolved Common options.
+     */
+    interface ResolvedOptions<T extends Cph.AesAlgorithm = Cph.AesAlgorithm> extends Required<Omit<Cph.Options<T>, 'aad'>> {
+        /** The symmetric key length. */
+        length: number;
+        aad?: Uint8Array;
+    }
+    namespace Stream {
+        namespace Symmetric {
+            /**
+             * Options for encrypting a stream.
+             */
+            interface EncryptOptions extends Cph.Options<Cph.CBCTypes> {
+                /** The `Readable` Stream from where raw data to encrypt is read. */
+                input: Readable;
+                /** The `Writable` Stream where encrypted data is written. */
+                output: Writable;
+            }
+            /**
+             * Resolved Stream Encrypt options (symmetric and hybrid).
+             */
+            type EncryptResolvedOptions = (Cph.ResolvedOptions & Required<Cph.Stream.Symmetric.EncryptOptions>);
+            /**
+             * Options for decrypting a stream (symmetric).
+             */
+            interface DecryptOptions extends Cph.Stream.Symmetric.EncryptOptions {
+                /** The `Readable` Stream from where encrypted data is read. */
+                input: Readable;
+                /** The `Writable` Stream where decrypted data is written. */
+                output: Writable;
+            }
+            /**
+             * Resolved Stream Decrypt options (symmetric).
+             */
+            type DecryptResolvedOptions = (Cph.ResolvedOptions & Required<Cph.Stream.Symmetric.DecryptOptions>);
+        }
+        namespace Hybrid {
+            /**
+             * Alias for {@link Cph.Stream.Symmetric.EncryptOptions}
+             */
+            type EncryptOptions = Cph.Stream.Symmetric.EncryptOptions;
+            /**
+             * Alias for {@link Cph.Stream.Symmetric.EncryptResolvedOptions}
+             */
+            type EncryptResolvedOptions = Cph.Stream.Symmetric.EncryptResolvedOptions;
+            /**
+             * Options for decrypting a stream.
+             */
+            interface DecryptOptions extends Cph.Stream.Symmetric.DecryptOptions {
+                /** The RSA key length in bytes used while encrypting data. This is used to properly extract the encrypted Cipher Key and Initialization Vector. */
+                rsaKeyLength: number;
+            }
+            /**
+             * Resolved Stream Decrypt options.
+             */
+            type DecryptResolvedOptions = (Cph.ResolvedOptions & Required<Cph.Stream.Hybrid.DecryptOptions>);
+        }
+    }
+}
+
+export { Cph };

package/dist/types.js

@@ -0,0 +1 @@
+'use strict';

package/license.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Alessio Frittoli.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.