nestjs-cryptography 2.2.2 → 3.0.0

package/wiki/versioned_docs/version-2.x/Internals/symmetric-secure-data-encrypt.mdx

@@ -0,0 +1,160 @@
+---
+title: Symmetric Secure Data Encrypt
+sidebar_label: Symmetric Secure Data Encrypt
+sidebar_position: 2
+---
+
+In the following section, you will see a diagram of the cryptographic operations performed when calling the method [`symmetricSecureDataEncrypt`][1]
+
+This method securely encrypts input data by first generating a random 32-byte Data Encryption Key (DEK)
+using a cryptographically secure method. It then encrypts the data using AES-256-GCM with the DEK,
+producing an output that includes the initialization vector (IV), salt, authentication tag, and ciphertext.
+After encrypting the data, the method also encrypts the DEK itself using a master key, and finally,
+it concatenates the encrypted DEK and the encrypted data, returning the complete encrypted result for secure storage or transmission.
+
+## **Diagram**
+
+<div style={{ textAlign: 'center' }}>
+  ```mermaid
+  graph TD
+  A[Input: Data] --> ID
+
+  DEK{Generate DEK} --> SG1
+
+  subgraph SG1[Generate DEK]
+  SG1A1[Generate 64 bytes of random data] --> SG1A1A2[Create Secret Key from random data]
+  SG1A1A2 --> SG1A1A3[Generate another 64 bytes of random data]
+  SG1A1A3 --> SG1A1A4[Use HKDF with sha3-256 to derive IV]
+  end
+
+
+  subgraph ED[Encrypt Data]
+  SG1A1A4 --> DEK1[DEK]
+
+  ID(DATA)
+
+  IV1[IV] --> IV1A1{Generate IV}
+  SALT1[SALT] --> SALT1A1{Generate SALT}
+
+  IV1A1 --> SGIV1
+  SALT1A1 --> SGSALT1
+
+  subgraph SGIV1["Generate IV (12 bytes)"]
+  SGIV1A1[Generate 64 bytes of random data] --> SGIV1A1A2[Create Secret Key from random data]
+  SGIV1A1A2 --> SGIV1A1A3[Generate another 64 bytes of random data]
+  SGIV1A1A3 --> SGIV1A1A4[Use HKDF with sha3-256 to derive IV]
+  end
+
+  subgraph SGSALT1["Generate Salt (64 bytes)"]
+  SGSSALT1A1[Generate 64 bytes of random data] --> SGSSALT1A1A2[Create Secret Key from random data]
+  SGSSALT1A1A2 --> SGSSALT1A1A3[Generate another 64 bytes of random data]
+  SGSSALT1A1A3 --> SGSSALT1A1A4[Use HKDF with sha3-256 to derive SALT]
+  end
+
+  DEK1 --> DERIVEDEK[Securely derive DEK using Argon2 + Salt]
+  DERIVEDEK --> EK1(Encryption Key)
+  SGSSALT1A1A4 --> DERIVEDEK
+
+  SGIV1A1A4 --> FIV1(IV)
+  FIV1 ==> FED{Encrypt Data using AES-256-GCM with Encryption Key + IV}
+  EK1 ==> FED
+  ID ==> FED
+
+  FED -.- FFED["Encrypted Data [IV + Salt + AuthTag + CipherText]"]
+  end
+
+
+  subgraph EDEK[Encrypt DEK]
+  SG1A1A4 --> DEK2(DEK)
+
+  IV2[IV] --> IV2A1{Generate IV}
+  SALT2[SALT] --> SALT2A1{Generate SALT}
+
+  IV2A1 --> SGIV2
+  SALT2A1 --> SGSALT2
+
+  subgraph SGIV2["Generate IV (12 bytes)"]
+  SGIV2A1[Generate 64 bytes of random data] --> SGIV2A1A2[Create Secret Key from random data]
+  SGIV2A1A2 --> SGIV2A1A3[Generate another 64 bytes of random data]
+  SGIV2A1A3 --> SGIV2A1A4[Use HKDF with sha3-256 to derive IV]
+  end
+
+  subgraph SGSALT2["Generate Salt (64 bytes)"]
+  SGSSALT2A1[Generate 64 bytes of random data] --> SGSSALT2A1A2[Create Secret Key from random data]
+  SGSSALT2A1A2 --> SGSSALT2A1A3[Generate another 64 bytes of random data]
+  SGSSALT2A1A3 --> SGSSALT2A1A4[Use HKDF with sha3-256 to derive SALT]
+  end
+
+  MK[MASTER KEY] --> DERIVEMK[Securely derive Master Key using Argon2 + Salt]
+  DERIVEMK --> EK2(Encryption Key)
+  SGSSALT2A1A4 --> DERIVEMK
+
+  SGIV2A1A4 --> FIV2(IV)
+
+  EK2 ==> FEDEK{Encrypt DEK using AES-256-GCM with Encryption Key + IV}
+  DEK2 ==> FEDEK
+  FIV2 ==> FEDEK
+
+  FEDEK -.- FFEDEK["Encrypted DEK [IV + Salt + AuthTag + CipherText]"]
+  end
+
+  FFEDEK -.-> FFDD(["Concatenate Encrypted DEK + Encrypted Data"])
+  FFED -.-> FFDD
+
+
+  %% -----------------
+
+  A:::inputDataStyle
+
+  MK:::masterKeyStyle
+
+  DEK:::dekStyle
+
+  SALT1A1:::saltStyle
+  SALT2A1:::saltStyle
+
+  IV1A1:::ivStyle
+  IV2A1:::ivStyle
+
+  FEDEK:::encryptionStyle
+  FED:::encryptionStyle
+
+  FFEDEK:::resultStyle
+  FFED:::resultStyle
+
+  FFDD:::finalResultStyle
+
+  %% Style definitions
+  classDef inputDataStyle fill:#00ff00,stroke:#333,stroke-width:2px;
+  classDef masterKeyStyle fill:#ff0000,stroke:#333,stroke-width:2px;
+  classDef dekStyle fill:#BCD3A3,stroke:#333,stroke-width:2px;
+  classDef ivStyle fill:#ffcc00,stroke:#333,stroke-width:2px;
+  classDef saltStyle fill:#ff6666,stroke:#333,stroke-width:2px;
+  classDef deriveKeyStyle fill:#66ccff,stroke:#333,stroke-width:2px;
+  classDef secureKeyStyle fill:#66ff66,stroke:#333,stroke-width:2px;
+  classDef encryptionStyle fill:#cc99ff,stroke:#333,stroke-width:2px;
+  classDef resultStyle fill:#ff9966,stroke:#333,stroke-width:2px;
+  classDef finalResultStyle fill:#66ffcc,stroke:#333,stroke-width:2px;
+  ```
+</div>
+
+
+## **Explanation of the Diagram**
+1) Generate DEK:
+    - The internal `createSaferRandomData` method generates a 32-byte **DEK** (Data Encryption Key) using `HKDF(sha3-256 + random_key + random_salt)`.
+2) Encrypt the Input Data:
+    - **Generate IV (12 bytes)**: A 12-byte IV is generated using `HKDF(sha3-256 + random_key + random_salt)`.
+    - **Generate Salt (64 bytes)**: A 64-byte salt is generated, also using `HKDF(sha3-256 + random_key + random_salt)`.
+    - **Derive Secure Encryption Key**: A secure encryption key is derived using **Argon2** with the DEK and salt.
+    - **Encrypt Data**: The input data is encrypted using **AES-256-GCM** with the derived secure encryption key, producing the encrypted result: _IV + Salt + AuthTag + CipherText_.
+3) Encrypt the DEK:
+    - The DEK itself is encrypted using the master key:
+      - **Generate IV (12 bytes)**: A 12-byte IV is generated using `HKDF(sha3-256 + random_key + random_salt)`.
+      - **Generate Salt (64 bytes)**: A 64-byte salt is generated, also using `HKDF(sha3-256 + random_key + random_salt)`.
+      - **Derive Master Key**: A secure encryption key is derived using **Argon2** with the [**MasterKey**][2] and salt.
+      - **Encrypt DEK**: The DEK is encrypted using AES-256-GCM, resulting in the encrypted DEK: _IV + Salt + AuthTag + CipherText_.
+4) Concatenate and Return:
+    - The encrypted DEK and the encrypted input data are concatenated to form the final output, which is then returned.
+
+[1]: ../guides/symmetric-encryption#symmetricsecuredataencrypt
+[2]: ../api-reference/settings#masterkey-1

package/wiki/versioned_docs/version-2.x/api-reference/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "API Reference",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "5 minutes to learn the most important Docusaurus concepts."
+  }
+}

package/wiki/versioned_docs/version-2.x/api-reference/settings.mdx

@@ -0,0 +1,197 @@
+---
+title: Configuration Options
+sidebar_label: Configuration Options
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import GenerateHexButton from '@site/src/components/GenerateHexButton';
+
+<details>
+  <summary>👨‍🔧 Let me help you a bit....</summary>
+
+  <div>
+
+    :::info
+
+    If at any point you need to securely generate a secret key for the following configuration, you can do so as follows.
+
+    <Tabs
+      defaultValue="linux"
+      values={[
+        { label: 'Linux / macOS', value: 'linux', },
+        { label: 'Windows / Others', value: 'windows', }
+      ]
+      }>
+      <TabItem value="linux">
+        Type this on the terminal:
+        ```bash
+        openssl rand -hex 32
+        ```
+      </TabItem>
+      <TabItem value="windows">
+        <GenerateHexButton />
+      </TabItem>
+    </Tabs>
+
+
+    :::
+
+  </div>
+</details>
+
+<details>
+  <summary>Example Usage</summary>
+
+  <div>
+
+```typescript title="app.module.ts"
+import { Module } from '@nestjs/common';
+import * as argon2 from 'argon2';
+import {
+  CryptographyModule,
+  CryptographyOptionsInterface,
+} from 'nestjs-cryptography';
+
+@Module({
+imports: [
+  CryptographyModule.registerAsync({
+    imports: [ConfigModule],
+    isGlobal: true,
+    useFactory: (configService: ConfigService) =>
+      ({
+        isGlobal: true,
+        kdf: {
+          timeCost: 32,
+          memoryCost: 131072,
+          argon2Type: argon2.argon2i,
+          defaultOutputKeyLength: 32,
+        },
+        hashing: {
+          password: {
+            timeCost: 10,
+            memoryCost: 65536,
+            argon2Type: argon2.argon2id,
+            outputKeyLength: 64,
+          },
+          hmac: {
+            // ‼️ change me please ‼️
+            masterKey: '6c0504d3836ab96a25daeb61c44f6d6345d99a746f6a776290c48d9a5ba8b124',
+          },
+        },
+        encryption: {
+          symmetric: {
+            // ‼️ change me please ‼️
+            masterKey: '1538755db39d3d98115af5be688b1486673910f7d2630fc48dd27c1a1ace2631',
+          },
+        },
+      }) as CryptographyOptionsInterface,
+      inject: [ConfigService],
+  }),
+],
+export class AppModule {}
+```
+
+  </div>
+</details>
+
+## `kdf`
+
+Settings for the Key Derivation Function.
+
+  - ### <u>defaultOutputKeyLength</u>
+      > `type: number` | **required**
+
+    The default length (in bytes) of the derived key.
+
+  - ### <u>argon2Type</u>
+      > `type: Argon2Type` | **required**
+
+    The variant of the Argon2 algorithm to use (Argon2d, Argon2i, or Argon2id)
+
+  - ### <u>memoryCost</u>
+      > `type: number` | **required**
+
+    Memory usage (in kilobytes) for the algorithm.
+
+  - ### <u>timeCost</u>
+      > `type: number` | **required**
+
+    Number of iterations to perform.
+
+---
+
+## `hashing`
+
+Settings for hashing operations.
+
+### `password`
+
+Configuration for password hashing.
+
+  - ### <u>outputKeyLength</u>
+      > `type: number` | **required**
+
+    The default length (in bytes) of the derived key.
+
+  - ### <u>argon2Type</u>
+      > `type: Argon2Type` | **required**
+
+    The variant of the Argon2 algorithm to use (Argon2d, Argon2i, or Argon2id)
+
+  - ### <u>memoryCost</u>
+      > `type: number` | **required**
+
+    Memory usage (in kilobytes) for the algorithm.
+
+  - ### <u>timeCost</u>
+      > `type: number` | **required**
+
+    Number of iterations to perform.
+
+### `hmac`
+
+Configuration for HMAC (Hash-Based Message Authentication Code).
+
+  - ### <u>masterKey</u>
+      > `type: string` | **required**
+
+    The secret key used for generating HMACs.
+
+---
+
+## `encryption`
+
+Settings for encryption operations.
+
+### `symmetric`
+
+Configuration for symmetric encryption.
+
+  - ### <u>masterKey</u>
+      > `type: string` | **required**
+
+    The secret key used for encryption and decryption.
+
+:::danger
+
+Note: Always ensure that secret keys are generated securely and stored safely.
+Do not hard-code them into your source files or expose them in version control systems.
+
+:::
+
+## Additional Information
+
+- **Argon2Type**: An enumeration defining the type of Argon2 algorithm to use.
+The options typically include `Argon2d`, `Argon2i`, and `Argon2id`.
+[Choose the one that best fits your security requirements][3].
+
+- **Security Considerations**: Adjust `memoryCost` and `timeCost`
+according to the desired balance between performance and security.
+Higher values increase security but require more resources.
+You could se more information on [owasp][1] or the [official specs][2]
+
+[1]: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id
+[2]: https://www.password-hashing.net/argon2-specs.pdf#page=15
+[3]: https://en.wikipedia.org/wiki/Argon2

package/wiki/versioned_docs/version-2.x/guides/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Guides",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}

package/wiki/versioned_docs/version-2.x/guides/generics.mdx

@@ -0,0 +1,133 @@
+---
+title: Generics
+sidebar_label: Generics
+sidebar_position: 1
+description: Methods to perform typical operations UUID, randomPassword, ...
+---
+
+import RequiredLabel from '@site/src/components/RequiredLabel';
+import Tips from '@site/src/common/tips.mdx'
+
+This section contains some generic methods to perform typical operations
+
+## Generate an UUIDv4
+
+Method to generate a UUID version 4.
+
+### `genUUID`
+
+```tsx
+public genUUID (
+  secure = false
+): string;
+```
+
+**Parameters:**
+
+| Name                    | Type    | Default | Description                                          |
+|-------------------------|---------|---------|------------------------------------------------------|
+| secure <RequiredLabel/> | boolean | false   | Decide to use a more secure generation using entropy |
+
+
+**Outputs:**
+
+As output, it will return a string of this format `0E928AD4-4D11-4C7C-A83A-8DD7361FFC01`
+
+
+**Usage:**
+```typescript
+async someAwesomeMethod(): Promise<string> {
+  const newUUID = this.cryptographyService.genUUID(true);
+  ...
+  return newUUID;
+}
+```
+
+## Generate random password
+
+Method to generate a random password with this set of characters:
+`a-z 0-9` if _**hex**_ used, or `A-Z a-z 0-9 + = /` if _**base64**_ used.
+
+### `genRandomPassword`
+
+```tsx
+public genRandomPassword (
+  length: number,
+  encoding: 'base64' | 'hex'
+): string;
+```
+
+**Parameters:**
+
+| Name                      | Type          | Default | Description                                      |
+|---------------------------|---------------|---------|--------------------------------------------------|
+| length <RequiredLabel/>   | number        |         | The password output length                       |
+| encoding <RequiredLabel/> | base64 \| hex |         | The password output format hexadecimal or base64 |
+
+
+**Outputs:**
+
+As output, it will return a string of this format:
+  - base64: `jh2EducrV7yH8tGAc8Jkdcso`
+  - hex: `b4da8e4aba39c9f70dde717d`
+
+**Usage:**
+```typescript
+async createUserPassword(): Promise<string> {
+  const newPassword = this.cryptographyService.genRandomPassword(24, 'base64');
+  ...
+  return newPassword;
+}
+```
+
+## Generate symmetric key
+
+Method to generate a cryptographically secure SymmetricKey in [KeyObject][1] format
+to use in subsequent encryption/decryption operations.
+
+### `generateSymmetricKey`
+
+```tsx
+public generateSymmetricKey (
+  length: number = 256
+): KeyObject;
+```
+
+**Parameters:**
+
+| Name   | Type   | Default | Description                     |
+|--------|--------|---------|---------------------------------|
+| length | number | 256     | The symmetric key output length |
+
+
+**Outputs:**
+
+As output, it will return an object of type [KeyObject][1].
+
+:::info
+ If you want to export this KeyObject to different types, you can access the `.export` [method][2]
+:::
+
+**Usage:**
+```typescript
+async createSymmetricKey(): Promise<void> {
+  const new32KeySize = this.cryptographyService.generateSymmetricKey(32);
+  console.log(new32KeySize.export().toString('hex'));  // f32.....4ee
+
+  const aes128KeySize = this.cryptographyService.generateSymmetricKey(128);
+  console.log(aes128KeySize.export().toString('hex'));  // e89.....41e
+
+  const aes192KeySize = this.cryptographyService.generateSymmetricKey(192);
+  console.log(aes192KeySize.export().toString('base64'));  // 8OI.....ZQ=
+
+  const aes256KeySize = this.cryptographyService.generateSymmetricKey(256);
+  console.log(aes256KeySize.export());  // <Buffer cc 2b.....cd a1 08>
+}
+```
+
+
+<Tips />
+
+
+[1]: https://nodejs.org/api/crypto.html#class-keyobject
+[2]: https://nodejs.org/api/crypto.html#keyobjectexportoptions