nestjs-cryptography 2.2.2 → 3.0.0

package/wiki/versioned_docs/version-2.x/guides/symmetric-encryption.mdx

@@ -0,0 +1,107 @@
+---
+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 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
+
+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, 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,
+): Promise<Buffer>;
+```
+
+**Parameters:**
+
+| Name                      | Type             | Default | Description                 |
+|---------------------------|------------------|---------|-----------------------------|
+| **data** <RequiredLabel/> | string \| Buffer |         | String or buffer to encrypt |
+
+**Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+#### **Usage:**
+```typescript
+async exampleEncrypt(
+  data: string,
+): Promise<string> {
+  const bufferData = Buffer.from(data, 'utf-8');
+  const encryptedData = await this.cryptographyService.symmetricSecureDataEncrypt(data);
+  return encryptedData.toString('hex')
+}
+```
+
+
+[//]: #--------------------#
+
+
+## Symmetric secure data encrypt
+
+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 (
+  ata: string | Buffer
+): Promise<Buffer>;
+```
+
+**Parameters:**
+
+| Name                      | Type             | Default | Description                 |
+|---------------------------|------------------|---------|-----------------------------|
+| **data** <RequiredLabel/> | string \| Buffer |         | String or buffer to decrypt |
+
+**Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+
+#### **Usage:**
+```typescript
+async exampleDecrypt(
+  data: string,
+): Promise<string> {
+  const bufferData = Buffer.from(data, 'hex');
+  const decryptedData = await this.cryptographyService.symmetricSecureDataDecrypt(data);
+  return decryptedData.toString('utf-8')
+}
+```
+
+
+<Tips />
+
+
+
+
+[1]: https://nodejs.org/api/buffer.html
+[2]: symmetric-encryption#symmetricsecuredataencrypt

package/wiki/versioned_docs/version-2.x/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

package/wiki/versioned_sidebars/version-2.x-sidebars.json

@@ -0,0 +1,8 @@
+{
+  "tutorialSidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}

package/wiki/versions.json

@@ -0,0 +1,3 @@
+[
+  "2.x"
+]