nestjs-cryptography 2.2.2 → 3.0.0

package/wiki/docs/Internals/create-safe-random-data.mdx

@@ -0,0 +1,41 @@
+---
+title: Create Safe Random Data
+sidebar_label: Create Safe Random Data
+sidebar_position: 2
+description: Internals of createSafeRandomData
+---
+
+In the following section, you will see a diagram of the cryptographic operations performed when calling the method [`createSafeRandomData`][1]
+
+This method generate a cryptographically secure random bytes of the desired lengths using **HKDF**
+with `sha3-256` digest algorithm using the following params:
+ - Generate a random key using the secure random bytes' generator.
+ - Generate a salt using the secure random bytes' generator.
+
+
+<div style={{ textAlign: 'center' }}>
+  ```mermaid
+  graph TD
+    A[Key Length: length]
+
+    A --> CRB[Create Random Bytes: 64 bytes]
+    CRB --> CSK[Create Secret Key]
+    CSK ==> SK(SECRET_KEY)
+
+    A --> CRB2[Create Random Bytes: 64 bytes]
+    CRB2 ==> RB[RANDOM_BYTES]
+
+    SK -.-> HKDF["HKDF ( sha3-256 + SECRET_KEY + RANDOM_BYTES + length )"]
+    RB -.-> HKDF --> F([Return Secure Random Bytes])
+
+
+    style CRB fill:#f9f,stroke:#333,stroke-width:2px
+    style CRB2 fill:#f9f,stroke:#333,stroke-width:2px
+    style SK fill:#bbf,stroke:#333,stroke-width:2px
+    style RB fill:#bbf,stroke:#333,stroke-width:2px
+    style HKDF fill:#bfb,stroke:#333,stroke-width:2px
+    style F fill:#00f0f0,stroke:#F0000,stroke-width:2px
+  ```
+</div>
+
+[1]: ../guides/generics#generate-secure-random-data

package/wiki/docs/Internals/create-secure-hmac.mdx

@@ -0,0 +1,31 @@
+---
+title: Create Secure HMAC
+sidebar_label: Create Secure HMAC
+sidebar_position: 1
+description: Internals of createSecureHmac
+---
+
+In the following section, you will see a diagram of the cryptographic operations performed when calling the method [`createSecureHmac`][1]
+
+This method performs several cryptographic operations, including generating a salt,
+deriving a secure key using HKDF with the sha3-256 hashing algorithm, creating an HMAC,
+and returning the concatenated salt and HMAC result. The diagram will illustrate these steps clearly.
+
+<div style={{ textAlign: 'center' }}>
+  ```mermaid
+  graph TD
+      A[Input Data: data] --> B[Generate Master Key from Options]
+      B --> C[Generate Random Salt: 16 bytes]
+      C --> D[Use HKDF with sha3-256, Master Key, and Salt]
+      D --> E[Generate Secure Key: 64 bytes]
+      E --> F[Create HMAC with sha3-256, Secure Key, and Data]
+      F --> G[Concatenate Salt and HMAC]
+      G --> H[Return Combined Buffer: Salt + HMAC]
+
+      style B fill:#f9f,stroke:#333,stroke-width:2px
+      style D fill:#bbf,stroke:#333,stroke-width:2px
+      style F fill:#bfb,stroke:#333,stroke-width:2px
+  ```
+</div>
+
+[1]: ../guides/hmac#create-a-secure-hmac

package/wiki/docs/Internals/symmetric-data-encrypt.mdx

@@ -0,0 +1,103 @@
+---
+title: Symmetric Data Encrypt
+sidebar_label: Symmetric Data Encrypt
+sidebar_position: 4
+description: Internals of symmetricDataEncrypt
+---
+
+In the following section, you will see a diagram of the cryptographic operations performed when calling the method [`symmetricDataEncrypt`][1]
+
+This method securely encrypts input data by first generating a 12-byte Initialization Vector **(IV)**
+and a 64-byte **salt** using the `HKDF(sha3-256 + random_key + random_salt)` technique.
+It then derives a secure encryption key from the salt using the **Argon2** algorithm.
+The actual data is encrypted using **AES-256-GCM** with the derived key,
+resulting in an output that includes the IV, salt, authentication tag, and ciphertext.
+This comprehensive approach ensures the integrity and confidentiality of the data during storage or transmission.
+
+## **Diagram**
+
+<div style={{ textAlign: 'center' }}>
+  ```mermaid
+  graph TD
+
+  A[Input: Data] --> ID
+  B[Input: Key] --> IK
+
+  subgraph ED[Encrypt Data]
+
+    ID(DATA)
+    IK(KEY)
+
+    subgraph IVGENERATIONGRAPH["Generate IV (12 bytes)"]
+      IVL[Key Length: length] --> CRB[Create Random Bytes: 64 bytes]
+      CRB --> CSK[Create Secret Key]
+      CSK ==> SK(SECRET_KEY)
+
+      IVL --> CRB2[Create Random Bytes: 64 bytes]
+      CRB2 ==> RB[RANDOM_BYTES]
+
+      SK -.-> HKDF["HKDF ( sha3-256 + SECRET_KEY + RANDOM_BYTES + length )"]
+      RB -.-> HKDF --> F([Return Secure Random Bytes])
+    end
+
+    subgraph SALTGENERATIONGRAPH["Generate Salt (64 bytes)"]
+      IVL2[Key Length: length] --> CRB23[Create Random Bytes: 64 bytes]
+      CRB23 --> CSK2[Create Secret Key]
+      CSK2 ==> SK2(SECRET_KEY)
+
+      IVL2 --> CRB22[Create Random Bytes: 64 bytes]
+      CRB22 ==> RB2[RANDOM_BYTES]
+
+      SK2 -.-> HKDF2["HKDF ( sha3-256 + SECRET_KEY + RANDOM_BYTES + length )"]
+      RB2 -.-> HKDF2 --> F2([Return Secure Random Bytes])
+    end
+
+    F --> FIV(IV)
+
+    F2 --> DERIVEDEK[Securely derive DEK using Argon2 + Salt]
+    DERIVEDEK --> EK1(ENCRYPTION_KEY)
+    IK --> DERIVEDEK
+
+    FIV ==> FED([Encrypt DATA using AES-256-GCM with ENCRYPTION_KEY + IV])
+    EK1 ==> FED
+    ID ==> FED
+
+  end
+
+  FED -.- FFED["Encrypted data [IV + Salt + AuthTag + CipherText]"]
+
+
+  %% Style definitions
+  style ID fill:#BCD3A3,stroke:#333,stroke-width:2px;
+  style FIV fill:#ffcc00,stroke:#333,stroke-width:2px;
+  style EK1 fill:#66ff66,stroke:#333,stroke-width:2px;
+  style FED fill:#cc99ff,stroke:#333,stroke-width:2px;
+  style FFED fill:#ff9966,stroke:#333,stroke-width:2px;
+
+  style CRB fill:#f9f,stroke:#333,stroke-width:2px
+  style CRB2 fill:#f9f,stroke:#333,stroke-width:2px
+  style SK fill:#bbf,stroke:#333,stroke-width:2px
+  style RB fill:#bbf,stroke:#333,stroke-width:2px
+  style HKDF fill:#bfb,stroke:#333,stroke-width:2px
+  style F fill:#00f0f0,stroke:#F0000,stroke-width:2px
+
+  style CRB23 fill:#f9f,stroke:#333,stroke-width:2px
+  style CRB22 fill:#f9f,stroke:#333,stroke-width:2px
+  style SK2 fill:#bbf,stroke:#333,stroke-width:2px
+  style RB2 fill:#bbf,stroke:#333,stroke-width:2px
+  style HKDF2 fill:#bfb,stroke:#333,stroke-width:2px
+  style F2 fill:#00f0f0,stroke:#F0000,stroke-width:2px
+  ```
+</div>
+
+
+## **Explanation of the Diagram**
+1) **Generate IV (12 bytes)**: A 12-byte IV is generated using `HKDF(sha3-256 + random_key + random_salt)`.
+2) **Generate Salt (64 bytes)**: A 64-byte salt is generated, also using `HKDF(sha3-256 + random_key + random_salt)`.
+3) **Derive Secure Encryption Key**: A secure encryption key is derived using **Argon2** with the _Key_ and **Salt**.
+4) **Encrypt Data**: The _input data_ is encrypted using **AES-256-GCM** with the derived secure encryption key,
+producing the encrypted result in format: `[IV + Salt + AuthTag + CipherText]`.
+
+
+[1]: ../guides/symmetric-encryption#symmetricdataencrypt
+[2]: ../api-reference/settings#masterkey-1

package/wiki/docs/Internals/symmetric-secure-data-encrypt.mdx

@@ -0,0 +1,161 @@
+---
+title: Symmetric Secure Data Encrypt
+sidebar_label: Symmetric Secure Data Encrypt
+sidebar_position: 3
+description: Internals of symmetricSecureDataEncrypt
+---
+
+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 `createSafeRandomData` 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/docs/api-reference/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "API Reference",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+  }
+}

package/wiki/docs/api-reference/settings.mdx

@@ -0,0 +1,199 @@
+---
+title: Configuration Options
+sidebar_label: Configuration Options
+sidebar_position: 1
+description: Module configuration options
+
+---
+
+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,
+          outputKeyLength: 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>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.
+
+---
+
+## `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/docs/guides/_category_.json

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