\n\n
\n\n---\n\nType parameters
\n\n| Parameter | Default | Description |\n| --------- | ------------------ | -------------------------------------------------------------------------------------- |\n| `T` | `Cph.AesAlgorithm` | Accepted algorithm in `Cph.Options`. This is usefull to constraint specifc algorithms. |\n\n\n\n
\n\n---\n\n##### `Cph.Stream.EncryptOptions`\n\nStream symmetric encryption options.\n\nProperties
\n\n| Property | Type | Default | Description |\n| ----------- | ------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `algorithm` | `T` | `aes-256-gcm \\| aes-256-cbc` | Accepted algorithms. |\n| `salt` | `number` | `32` | The `salt` length in bytes. Minimum: `16`, Maximum: `64`. |\n| `iv` | `number` | `16` | The Initialization Vector length in bytes. Minimum: `8`, Maximum: `32`. |\n| `authTag` | `number` | `16` | The `authTag` length in bytes. Minimum: `4`, Maximum: `16`. |\n| `aad` | `CoerceToUint8ArrayInput` | - | Custom Additional Authenticated Data. `aadLength` is then automatically resolved. If not provided, a random AAD is generated with a max length of `aadLength`. |\n| `aadLength` | `number` | `32` | The auto generated AAD length in bytes. Minimum: `16`, Maximum: `128`. |\n\n\n\n
\n\n---\n\n##### `Cph.Stream.DecryptOptions`\n\nStream symmetric decryption options.\n\n- Alias of [`Cph.Stream.EncryptOptions`](#cphstreamencryptoptions).\n\nProperties
\n\n| Property | Type | Description |\n| ----------- | -------------- | ------------------------------------------------------------- |\n| `input` | `Readable` | The `Readable` Stream from where raw data to encrypt is read. |\n| `output` | `Writable` | The `Writable` Stream where encrypted data is written. |\n| `algorithm` | `Cph.CBCTypes` | One of the Cipher Block Chaining algorithm. |\n\n\n\n
\n\n---\n\n##### `Cph.PrivateKey`\n\nThe RSA Private Key.\n\nIt could be:\n\n- a `crypto.KeyLike`\n- an object defining `key` and `passphrase` where `key` is a `crypto.KeyLike`\n\n---\n\n### Examples\n\n#### In-memory data buffer encryption/decryption\n\nThe simpliest way to encrypt/decrypt in-memory data buffers.\n\n```ts\n// encrypt\nconst data = \"my top-secret data\";\nconst password = \"my-very-strong-password\";\n\nconst encrypted = Cipher.Encrypt(data, password);\n\n// decrypt\nconst decrypted = Cipher.Decrypt(encrypted, password);\nconsole.log(decrypted); // Outputs: my top-secret data\n```\n\n---\n\n#### In-memory data buffer hybrid encryption/decryption\n\nHybrid encryption offers an higher level of security since only the RSA Private Key owner will be able to decrypt the data.\n\n> [!WARNING]\n> Please, note that when using hybrid encryption/decryption algorithms:\n>\n> - an RSA keypair is required.\n> - if a passphrase is set for the Private Key, please make sure to use one of the Cipher Block Chaining algorithm or `chacha20-poly1305` algorithm:\n> - aes-128-cbc (`type` can be `pkcs1` or `pkcs8`)\n> - aes-192-cbc (`type` can be `pkcs1` or `pkcs8`)\n> - aes-256-cbc (`type` can be `pkcs1` or `pkcs8`)\n> - chacha20-poly1305 (`type` can only be `pkcs1`)\n\n##### Keypair\n\n```ts\nimport { Cipher } from \"@alessiofrittoli/crypto-cipher\";\n\nconst keyPair = crypto.generateKeyPairSync(\"rsa\", {\n modulusLength: 512 * 8, // 4096 bits\n publicKeyEncoding: { type: \"spki\", format: \"pem\" },\n privateKeyEncoding: { type: \"pkcs1\", format: \"pem\" },\n});\n\n// or you can optionally set a custom passphrase\nconst passphrase = \"custompassphrase\";\n\nconst keyPair = crypto.generateKeyPairSync(\"rsa\", {\n modulusLength: 512 * 8, // 4096 bits\n publicKeyEncoding: { type: \"spki\", format: \"pem\" },\n privateKeyEncoding: {\n type: \"pkcs1\",\n format: \"pem\",\n passphrase,\n cipher: Cipher.ALGORITHM.CHACHA_20_POLY,\n },\n});\n```\n\n```ts\nimport { Cipher } from \"@alessiofrittoli/crypto-cipher\";\n\n// encrypt\nconst data = \"my top-secret data\";\nconst encrypted = Cipher.HybridEncrypt(data, keypair.publicKey);\n\n// decrypt\nconst decrypted = Cipher.HybridDecrypt(encrypted, {\n key: keypair.privateKey,\n passphrase,\n});\n```\n\n---\n\n#### In-memory data stream encryption/decryption\n\nThe in-memory data stream comes pretty handy when, for example, we need to stream encrypted data within a Server Response or to decrypt stream data from a Server Response.\n\n##### Streaming\n\n```ts\n// /api/stream-encrypt\n\nimport { Readable, Writable } from \"stream\";\nimport { Stream } from \"@alessiofrittoli/stream-writer\";\n\nconst routeHandler = () => {\n const password = \"my-very-strong-password\";\n const stream = new Stream();\n const headers = new Headers(stream.headers);\n\n const input = Readable.from([\n Buffer.from(\"Chunk n.1\"),\n Buffer.from(\"Chunk n.2\"),\n Buffer.from(\"Chunk n.3\"),\n Buffer.from(\"Chunk n.4\"),\n ]);\n\n // `Writable` Stream where encrypted data is written\n const output = new Writable({\n async write(chunk, encoding, callback) {\n await new Promise((resolve) => setTimeout(resolve, 2000));\n await stream.write(chunk);\n callback();\n },\n async final(callback) {\n await stream.close();\n callback();\n },\n });\n\n Cipher.stream.Encrypt(password, { input, output }).catch(async () => {\n await stream.close();\n });\n\n return (\n // encrypted stream\n new Response(stream.readable, { headers })\n );\n};\n```\n\n##### Decrypting received stream\n\n```ts\n// /api/stream-decrypt\n\nimport { Transform, Writable } from \"stream\";\nimport { Cipher } from \"@alessiofrittoli/crypto-cipher\";\nimport { StreamReader } from \"@alessiofrittoli/stream-reader\";\n\nconst password = \"my-very-strong-password\";\n\nconst routeHandler = () =>\n fetch(\"/api/stream-encrypt\").then((response) => {\n if (!response.body) {\n return new Respone(null, { status: 400 });\n }\n\n // web stream where decrypted data is written\n const stream = new StreamProperties
\n\n| Property | Type | Description |\n| ----------- | -------------- | -------------------------------------------------------- |\n| `input` | `Readable` | The `Readable` Stream from where encrypted data is read. |\n| `output` | `Writable` | The `Writable` Stream where decrypted data is written. |\n| `algorithm` | `Cph.CBCTypes` | One of the Cipher Block Chaining algorithm. |\n\n\n  \n | \n \n
| \n