nestjs-cryptography 2.2.2 → 3.0.0

package/wiki/docs/guides/key-derivation.mdx

@@ -0,0 +1,101 @@
+---
+title: Key Derivation
+sidebar_label: Key Derivation
+sidebar_position: 2
+description: Methods to use KDF (Key Derivation Function)
+---
+
+import RequiredLabel from '@site/src/components/RequiredLabel';
+import Tips from '@site/src/common/tips.mdx'
+
+
+The upcoming section will delve into methods for generating cryptographically secure keys from user-provided passwords.
+This process is crucial because raw passwords are often not secure enough for cryptographic purposes
+due to their relatively low entropy. By using a key derivation function, we can transform these passwords
+into secure keys that are suitable for encryption, hashing, or other cryptographic operations.
+
+We will be using **Argon2** for this purpose, which is one of the most secure and modern key derivation functions available.
+Argon2 is specifically designed to resist attacks such as brute force and side-channel attacks
+by incorporating memory-hard and CPU-intensive computations. This makes it an ideal choice for
+converting user passwords into robust cryptographic keys.
+
+
+
+## Derive a key
+
+Method to derive a user supplied key into a cryptographically secure one.
+
+### `deriveMasterKey`
+
+
+```typescript
+public deriveMasterKey (
+  masterKey: string | Buffer,
+  salt: Buffer,
+  length: number,
+): Promise<Buffer>;
+```
+
+
+#### **Parameters:**
+
+| Name                           | Type             | Default                    | Description                                         |
+|--------------------------------|------------------|----------------------------|-----------------------------------------------------|
+| **masterKey** <RequiredLabel/> | string \| Buffer | false                      | String or buffer of the key to derive               |
+| **salt** <RequiredLabel/>      | Buffer           | false                      | Salt to increase the security of the key derivation |
+| **length**                     | number           | [`kdf.outputKeyLength`][3] | The desired derived output key length               |
+
+
+#### **Module Parameters:**
+
+:::info
+
+Internally, this method uses certain parameters that are defined at the module level during initialization,
+as we have seen [previously][2]. The internal parameters used and their corresponding configuration keys are as follows:
+
+  - **hashLength**: Specifies the length of the resulting derived key.
+      If this option is not provided, then it is set via [`kdf.outputKeyLength`][3]
+and determines the size of the final hash in bytes.
+
+  - **type**: Defines the variant of Argon2 to use (_argon2i_, _argon2d_, or _argon2id_).
+This is configured using [`kdf.argon2Type`][4].
+
+  - **memoryCost**: Sets the amount of memory (in KB) that the algorithm will use during the hashing process.
+This value is determined by [`kdf.memoryCost`][5] and plays a critical role in resisting brute-force attacks.
+
+  - **timeCost**: Specifies the number of iterations or the amount of computational work Argon2 will perform.
+It is defined via [`kdf.timeCost`][6] to ensure a balance between security and performance.
+
+:::
+
+
+#### **Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+
+#### **Usage:**
+```typescript
+async deriveSecureKeyFromMasterKey(
+  key: string,
+): Promise<string> {
+  const keyBuffer = Buffer.from(key, 'utf-8');
+  const salt = this.cryptographyService.generateSymmetricKey(128);
+  const derivedKey = await this.cryptographyService.deriveMasterKey(keyBuffer, salt.export(), 256)
+  return derivedKey.toString('hex')
+}
+```
+
+
+
+
+<Tips />
+
+
+
+[1]: https://nodejs.org/api/buffer.html
+[2]: ../intro#configuration
+[3]: ../api-reference/settings#outputkeylength
+[4]: ../api-reference/settings#argon2type
+[5]: ../api-reference/settings#memorycost
+[6]: ../api-reference/settings#timecost

package/wiki/docs/guides/password-hashing.mdx

@@ -0,0 +1,136 @@
+---
+title: Password Hashing
+sidebar_label: Password Hashing
+sidebar_position: 4
+description: Methods to securely hash passwords (Argon2)
+---
+
+import RequiredLabel from '@site/src/components/RequiredLabel';
+import RecommendedLabel from '@site/src/components/RecommendedLabel';
+import GenericLabel from '@site/src/components/GenericLabel';
+import Tips from '@site/src/common/tips.mdx'
+import TimingAttack from '@site/src/common/timing-attack.mdx'
+
+In this section, we will explore how to securely hash passwords using [Argon2][2],
+one of the most advanced and secure password-hashing algorithms available today.
+Developed as a winner of the [Password Hashing Competition (PHC)][1], Argon2 is designed to protect against brute-force attacks,
+both by consuming significant computational resources and by utilizing memory-hard functions.
+This makes it a preferred choice for modern security practices.
+
+
+
+## Create Argon2 hash
+
+Method to create a hash of a text/password using Argon2 algorithm.
+
+### `createArgonHashFromPassword`
+
+```typescript
+public createArgonHashFromPassword (
+  data: string | Buffer,
+): string;
+```
+
+
+**Parameters:**
+
+| Name                      | Type             | Default | Description      |
+|---------------------------|------------------|---------|------------------|
+| **data** <RequiredLabel/> | string \| Buffer |         | Password to hash |
+
+
+**Module Parameters:**
+
+:::info
+
+Internally, this method uses certain parameters that are defined at the module level during initialization,
+as we have seen [previously][4]. The internal parameters used and their corresponding configuration keys are as follows:
+
+  - **hashLength**: Specifies the length of the resulting hash.
+      This is set via [`hashing.password.outputKeyLength`][5] and determines the size of the final hash in bytes.
+
+  - **type**: Defines the variant of Argon2 to use (_argon2i_, _argon2d_, or _argon2id_).
+      This is configured using [`hashing.password.argon2Type`][6].
+
+  - **memoryCost**: Sets the amount of memory (in KB) that the algorithm will use during the hashing process.
+      This value is determined by [`hashing.password.memoryCost`][7] and plays a critical role in resisting brute-force attacks.
+
+  - **timeCost**: Specifies the number of iterations or the amount of computational work Argon2 will perform.
+      It is defined via [`hashing.password.timeCost`][8] to ensure a balance between security and performance.
+
+:::
+
+
+**Outputs:**
+
+As output, it will return a string of type: `$argon2i$v=19$m=4096,t=3,p=1$c2g56.....jk7A`
+
+> Where the options `argon2i`, `v=19`, `m=4096`, `t=3` and `p=1` may vary
+depending on the [options][3] supplied to CryptographyModule when it has been [configured][4].
+
+
+**Usage:**
+```typescript
+async secureUserPassword(
+  plainPassword: string,
+): Promise<string> {
+  const _buffer = Buffer.from(plainPassword, 'utf-8');
+  const hashedPassword = await this.cryptographyService.createArgonHashFromPassword(_buffer);
+  return hashedPassword.toString();
+}
+```
+
+
+
+## Verify Argon2 hash
+
+Method to verify if an existing Argon2 hash matches the desired text/password.
+
+### `verifyArgonHashFromPassword`
+
+```typescript
+public verifyArgonHashFromPassword (
+  hash: string,
+  data: string | Buffer,
+): Promise<boolean>;
+```
+
+**Parameters:**
+
+| Name                      | Type             | Default | Description                 |
+|---------------------------|------------------|---------|-----------------------------|
+| **hash** <RequiredLabel/> | string           |         | String of the existing hash |
+| **data** <RequiredLabel/> | string \| Buffer |         | String or buffer to verify  |
+
+**Outputs:**
+
+As output, it will return `true` if both matches, or `false` if not.
+
+
+**Usage:**
+```typescript
+async checkUserPassword(
+  plainPassword: string,
+  hashedPassword: string
+): Promise<boolean> {
+  const _buffer = Buffer.from(plainPassword, 'utf-8');
+  return await this.cryptographyService.verifyArgonHashFromPassword(hashedPassword, plainPassword)
+}
+```
+
+
+<Tips />
+
+
+
+
+[1]: https://www.password-hashing.net
+[2]: https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf
+
+[3]: ../api-reference/settings
+[4]: ../intro#configuration
+
+[5]: ../api-reference/settings#outputkeylength-1
+[6]: ../api-reference/settings#argon2type-1
+[7]: ../api-reference/settings#memorycost-1
+[8]: ../api-reference/settings#timecost-1

package/wiki/docs/guides/symmetric-encryption.mdx

@@ -0,0 +1,272 @@
+---
+title: Symmetric Encryption
+sidebar_label: Symmetric Encryption
+sidebar_position: 6
+description: Methods to securely encrypt data (AES-256-GCM)
+---
+
+import RequiredLabel from '@site/src/components/RequiredLabel';
+import RecommendedLabel from '@site/src/components/RecommendedLabel';
+import GenericLabel from '@site/src/components/GenericLabel';
+import Tips from '@site/src/common/tips.mdx'
+import TimingAttack from '@site/src/common/timing-attack.mdx'
+
+In this section, we will discuss symmetric encryption and decryption using AES-256-GCM,focusing on best practices to ensure robust security.
+AES-256-GCM is a widely used and highly secure cryptographic algorithm, but its strength depends heavily on proper implementation.
+Key best practices include never reusing initialization vectors (IVs), as doing so can compromise the encryption's integrity.
+It is also crucial to always derive a secure encryption key from the user-provided key using a strong key derivation function
+like Argon2 or HKDF. In certain cases, it’s recommended to encapsulate the Data Encryption Key (DEK) by encrypting it separately,
+providing an additional layer of security for sensitive operations.
+Following these principles ensures that your symmetric encryption implementations remain secure and resilient against common cryptographic attacks.
+
+
+## Symmetric secure data encrypt
+
+#### <RecommendedLabel />
+
+Method to encrypt data using AES-256-GCM with a randomly generated Data Encryption Key (DEK).
+It ensures security by generating unique IVs and salts using the [`createSafeRandomData`][4], securely deriving encryption keys,
+and encrypting the DEK using a master key.
+The final output is a concatenation of the encrypted DEK and the encrypted data,
+ensuring both confidentiality and key encapsulation.
+
+### `symmetricSecureDataEncrypt`
+
+```typescript
+public symmetricSecureDataEncrypt (
+  data: string | Buffer,
+  options?: GenericOptionsInterface,
+): Promise<Buffer>;
+```
+
+**Parameters:**
+
+| Name                      | Type                       | Default | Description                                                      |
+|---------------------------|----------------------------|---------|------------------------------------------------------------------|
+| **data** <RequiredLabel/> | string \| Buffer           |         | String or buffer to encrypt                                      |
+| **options**               | [GenericOptions](#options) | `{}`    | Optional configuration object for input data encoding and output |
+
+#### **Options:**
+
+| Name              | Type                  | Default | Description                                                       |
+|-------------------|-----------------------|---------|-------------------------------------------------------------------|
+| inputDataEncoding | [`BufferEncoding`][3] |         | Specifies the encoding of the input data (e.g., 'hex', 'base64'). |
+
+**Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+:::info
+
+The resulting buffer contains: `[CIPHERED_DEK + CIPHERED_DATA]`
+ - And **CIPHERED_DEK** buffer part contains: `[IV + SALT + AUTH_TAG + CIPHERED_DATA]`
+ - And **CIPHERED_DATA** buffer part contains: `[IV + SALT + AUTH_TAG + CIPHERED_DATA]`
+
+[Click here to see more in deep how it works][6]
+
+:::
+
+#### **Usage:**
+```typescript
+async exampleEncrypt(
+  data: string,
+): Promise<string> {
+  const encryptedData = await this.cryptographyService.symmetricSecureDataEncrypt(
+      data,
+      {
+        inputDataEncoding: 'utf-8',
+      },
+    );
+  return encryptedData.toString('hex')
+}
+```
+
+
+[//]: #--------------------#
+
+
+## Symmetric secure data decrypt
+
+#### <RecommendedLabel />
+
+Method to decrypt data that was encrypted using the method [`symmetricSecureDataEncrypt`][2]
+
+:::warning
+
+Remember that the previous data must have been encrypted using [`symmetricSecureDataEncrypt`][2] method.
+
+:::
+
+
+### `symmetricSecureDataDecrypt`
+
+```typescript
+public symmetricSecureDataDecrypt (
+  data: string | Buffer
+): Promise<Buffer>;
+```
+
+**Parameters:**
+
+| Name                      | Type                         | Default | Description                                                      |
+|---------------------------|------------------------------|---------|------------------------------------------------------------------|
+| **data** <RequiredLabel/> | string \| Buffer             |         | String or buffer to decrypt                                      |
+| **options**               | [GenericOptions](#options-1) | `{}`    | Optional configuration object for input data encoding and output |
+
+#### **Options:**
+
+| Name              | Type                  | Default | Description                                                       |
+|-------------------|-----------------------|---------|-------------------------------------------------------------------|
+| inputDataEncoding | [`BufferEncoding`][3] |         | Specifies the encoding of the input data (e.g., 'hex', 'base64'). |
+
+**Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+
+#### **Usage:**
+```typescript
+async exampleDecrypt(
+  data: string,
+): Promise<string> {
+  const decryptedData = await this.cryptographyService.symmetricSecureDataDecrypt(
+      data,
+      {
+        inputDataEncoding: 'hex',
+      },
+    );
+  return decryptedData.toString('utf-8')
+}
+```
+
+
+[//]: #--------------------#
+
+
+## Symmetric data encrypt
+
+#### <GenericLabel />
+
+Method to encrypt data using AES-256-GCM and using unique IVs and salts using the [`createSafeRandomData`][4],
+and deriving the encryption key using Argon2 KDF.
+
+This is the internal method used to encrypt the data and the DEK when using [`symmetricSecureDataEncrypt`](#symmetricsecuredataencrypt)
+
+### `symmetricDataEncrypt`
+
+```typescript
+public symmetricDataEncrypt (
+  data: string | Buffer,
+  key: string | Buffer,
+  options?: GenericOptionsInterface,
+): Promise<Buffer>;
+```
+
+**Parameters:**
+
+| Name                      | Type                         | Default | Description                                                      |
+|---------------------------|------------------------------|---------|------------------------------------------------------------------|
+| **data** <RequiredLabel/> | string \| Buffer             |         | String or buffer to encrypt                                      |
+| **key** <RequiredLabel/>  | string \| Buffer             |         | String or buffer of the key to use                               |
+| **options**               | [GenericOptions](#options-2) | `{}`    | Optional configuration object for input data encoding and output |
+
+#### **Options:**
+
+| Name              | Type                  | Default | Description                                                       |
+|-------------------|-----------------------|---------|-------------------------------------------------------------------|
+| inputDataEncoding | [`BufferEncoding`][3] |         | Specifies the encoding of the input data (e.g., 'hex', 'base64'). |
+| inputKeyEncoding  | [`BufferEncoding`][3] |         | Specifies the encoding of the input key (e.g., 'hex', 'base64').  |
+
+**Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+:::info
+
+The resulting buffer contains: `[IV + SALT + AUTH_TAG + CIPHERED_DATA]`
+
+:::
+
+#### **Usage:**
+```typescript
+async exampleEncrypt(
+  data: string,
+): Promise<string> {
+  const encryptedData = await this.cryptographyService.symmetricDataEncrypt(
+      data,
+      'secret_key',
+      {
+        inputDataEncoding: 'utf-8',
+        inputKeyEncoding: 'utf-8'
+      },
+    );
+  return encryptedData.toString('hex')
+}
+```
+
+
+[//]: #--------------------#
+
+
+## Symmetric data decrypt
+
+#### <GenericLabel />
+
+Method to decrypt data that was encrypted using the method [`symmetricDataEncrypt`][5]
+
+### `symmetricDataDecrypt`
+
+```typescript
+public symmetricDataDecrypt (
+  data: string | Buffer,
+  key: string | Buffer,
+  options?: GenericOptionsInterface,
+): Promise<Buffer>;
+```
+
+**Parameters:**
+
+| Name                      | Type                         | Default | Description                                                      |
+|---------------------------|------------------------------|---------|------------------------------------------------------------------|
+| **data** <RequiredLabel/> | string \| Buffer             |         | String or buffer to decrypt                                      |
+| **key** <RequiredLabel/>  | string \| Buffer             |         | String or buffer of the key to use                               |
+| **options**               | [GenericOptions](#options-3) | `{}`    | Optional configuration object for input data encoding and output |
+
+#### **Options:**
+
+| Name              | Type                  | Default | Description                                                       |
+|-------------------|-----------------------|---------|-------------------------------------------------------------------|
+| inputDataEncoding | [`BufferEncoding`][3] |         | Specifies the encoding of the input data (e.g., 'hex', 'base64'). |
+
+**Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+#### **Usage:**
+```typescript
+async exampleDecrypt(
+  data: string,
+): Promise<string> {
+  const decryptedData = await this.cryptographyService.symmetricDataDecrypt(
+      data,
+      'secret_key'
+      {
+        inputDataEncoding: 'hex',
+        inputKeyEncoding: 'utf-8',
+      },
+    );
+  return decryptedData.toString('utf-8')
+}
+```
+
+<Tips />
+
+
+
+
+[1]: https://nodejs.org/api/buffer.html
+[2]: #symmetricsecuredataencrypt
+[3]: https://nodejs.org/api/buffer.html#buffers-and-character-encodings
+[4]: generics#generate-secure-random-data
+[5]: #symmetricdataencrypt
+[6]: ../internals/symmetric-secure-data-encrypt

package/wiki/docs/intro.mdx

@@ -0,0 +1,148 @@
+---
+sidebar_position: 1
+title: Getting Started
+sidebar_label: Getting Started
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Introduction
+
+This library was created to address a common problem encountered when performing cryptographic operations in our projects.
+It simplifies and streamlines the process, making it easier to implement secure and efficient cryptographic solutions.
+Additionally, it helps avoid common mistakes,
+such as the _**[reuse of initialization vectors][1]**_,
+_**[reuse of encryption keys][2]**_,
+or simple the use of _**[keys that are not cryptographically secure][3]**_.
+
+
+Our library employs modern cryptographic standards to provide robust security and protect your data against advanced threats. We utilize a suite of trusted algorithms and practices recognized in the cryptographic community:
+
+ - **Argon2**: A cutting-edge key derivation function designed to resist GPU and ASIC attacks, making it highly effective against brute-force attempts. It offers configurable memory and time costs to balance performance and security.
+ - **SHA3**: The latest member of the Secure Hash Algorithm family, SHA3 provides enhanced security over its predecessors (SHA-1 and SHA-2) and is resilient against known cryptographic attacks.
+ - **AES-256-GCM**: Advanced Encryption Standard with a 256-bit key in Galois/Counter Mode ensures both data confidentiality and integrity. AES-256-GCM is widely used and trusted for its high level of security and performance.
+ - **SHAKE256**: A versatile extendable-output function (XOF) from the SHA-3 family, SHAKE256 allows for variable-length output, making it suitable for a variety of cryptographic applications like key generation and hashing.
+ - **HKDF-SHA3-256**: A HMAC-based Key Derivation Function using SHA3-256 as the underlying hash function. HKDF-SHA3-256 ensures secure and reliable derivation of cryptographic keys from a master secret.
+ - **HMAC-SHA3-256**: A mechanism for message authentication using SHA3-256. HMAC-SHA3-256 provides data integrity and authenticity by allowing verification that a message has not been altered.
+ - **Constant-Time Secret Comparisons**: To protect against timing attacks, our library implements constant-time algorithms for comparing secrets. This means the time taken to perform the comparison does not depend on the data being compared, preventing attackers from inferring information based on execution time.
+
+## Installation
+
+This package are available on the [npm][4] registry.
+
+<Tabs
+  groupId="language"
+  defaultValue="npm"
+  values={[
+    { label: 'Yarn', value: 'yarn', },
+    { label: 'NPM', value: 'npm', }
+  ]
+  }>
+  <TabItem value="yarn">
+    ```bash
+    yarn add nestjs-cryptography
+    ```
+  </TabItem>
+  <TabItem value="npm">
+    ```bash
+    npm install nestjs-cryptography
+    ```
+  </TabItem>
+</Tabs>
+
+
+## Usage on Services
+To access cryptography methods from our `CryptographyService`, you could inject it using standard constructor injection
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { CryptographyService } from 'nestjs-cryptography';
+
+@Injectable()
+export class SomeService {
+  constructor(
+    // Inject using constructor injection
+    private readonly cryptographyService: CryptographyService
+  ) {}
+
+  async someMethod(): Promise<string> {
+    // Access service methods
+    return this.cryptographyService.genUUID();
+  }
+}
+```
+
+
+## Configuration
+
+Once the installation is complete, the `CryptographyModule` can be configured as any other
+Nest package with _`forRoot`_ or _`forRootAsync`_ methods.
+
+You could see the complete available settings [here][5]
+
+```typescript title="app.module.ts"
+import {
+  CryptographyModule,
+  CryptographyOptionsInterface,
+} from 'nestjs-cryptography';
+
+@Module({
+  imports: [
+    CryptographyModule.forRoot<CryptographyOptionsInterface>({
+      // The rest of the configuration
+      encryption: {
+        symmetric: {
+          masterKey: '5f7f...46bf'
+        }
+      }
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+:::info
+
+Like other factory providers, our factory function can be async and can inject dependencies through inject.
+
+For example, you mat want to get the configuration using the `ConfigurationModule`,
+so to do this you would use the _`forRootAsync`_ method ⬇️⬇️⬇️.
+
+:::
+
+```typescript title="app.module.ts"
+import {
+  CryptographyModule,
+  CryptographyOptionsInterface,
+} from 'nestjs-cryptography';
+
+@Module({
+  imports: [
+    CryptographyModule.forRootAsync<CryptographyOptionsInterface>({
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => ({
+        // The rest of the configuration
+        encryption: {
+          symmetric: {
+            masterKey: configService.get<string>('CRYPTOGRAPHY.MASTER_KEY')
+          }
+        }
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+
+The _`forRoot()`_ and _`forRootAsync`_ method takes an options object as an argument.
+These options are passed through to the underlying cryptographic operations of the instance module.
+
+
+[1]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf#page=26
+[2]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf#page=27
+[3]: https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r5.pdf#page=112
+[4]: https://www.npmjs.com/package/nestjs-cryptography
+[5]: api-reference/settings