nestjs-cryptography 3.0.0 → 3.1.1

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

@@ -1,197 +0,0 @@
----
-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

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

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

@@ -1,133 +0,0 @@
----
-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

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

@@ -1,229 +0,0 @@
----
-title: Hashing
-sidebar_label: Hashing
-sidebar_position: 3
-description: Methods to create generic and secure digests
----
-
-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 dive into various methods for applying cryptographic [hashes][2] both generically and securely.
-We will cover best practices to ensure that the hashing process is robust against common vulnerabilities.
-Additionally, we will explore secure techniques for comparing hash values,
-focusing on the use of time-safe comparison functions to prevent timing attacks.
-These methods are crucial for ensuring the integrity and security of sensitive data in cryptographic operations.
-
-## Create a custom HASH
-
-Method to create a hash of a text where you could choose the desires hash algorithm to use `sha1, sha256, sha3-256,...`
-
-### `createCustomHash`
-
-```typescript
-public createCustomHash (
-  algorithm: string,
-  data: string,
-  outputLength: number = 0,
-): Buffer;
-```
-
-#### **Parameters:**
-
-| Name                           | Type   | Default | Description                                                                                                 |
-|--------------------------------|--------|---------|-------------------------------------------------------------------------------------------------------------|
-| **algorithm** <RequiredLabel/> | string |         | Digest algorithm to use (`sha1, sha256, sha3-256,...`)                                                      |
-| **data** <RequiredLabel/>      | string |         | String to hash                                                                                              |
-| **outputLength**               | number | 0       | Option to specify the desired output length in bytes when using XOF hash functions. For example: `shake256` |
-
-#### **Outputs:**
-
-As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
-
-#### **Usage:**
-```typescript
-async hashUserPasswrd(
-  plainPassword: string,
-): string {
-  const hashedPassword = this.cryptographyService.createCustomHash('sha-256', plainPassword);
-  return hashedPassword.toString('hex')
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Verify a custom HASH
-
-Method to verify if an existing hash matches the hash of the desired text.
-You need choose the existing hash algorithm type used `sha1, sha256, sha3-256,...`
-
-### `verifyCustomHash`
-
-```typescript
-public verifyCustomHash (
-  algorithm: string,
-  data: string,
-  oldHash: string | Buffer,
-  outputLength: number = 0,
-): boolean;
-```
-
-#### **Parameters:**
-
-| Name                           | Type             | Default | Description                                                                                                 |
-|--------------------------------|------------------|---------|-------------------------------------------------------------------------------------------------------------|
-| **algorithm** <RequiredLabel/> | string           |         | Digest algorithm to use (`sha1, sha256, sha3-256,...`)                                                      |
-| **data** <RequiredLabel/>      | string           |         | String to hash                                                                                              |
-| **oldHash** <RequiredLabel/>   | Buffer \| string |         | Buffer or string of the existing hash                                                                       |
-| **outputLength**               | number           | 0       | Option to specify the desired output length in bytes when using XOF hash functions. For example: `shake256` |
-
-#### **Outputs:**
-
-As output, it will return `true` if both matches, or `false` if not.
-<TimingAttack/>
-
-#### **Usage:**
-```typescript
-async checkUserPassword(
-  plainPassword: string,
-  hashedPassword: string,
-): boolean {
-  const bufferExistingHash = Buffer.from(hashedPassword, 'utf-8');
-  return this.cryptographyService.verifyCustomHash('sha-256', plainPassword, bufferExistingHash);
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Create a secure HASH
-
-Method to create an extra secure hash of a text.
-
-In this case the XOF hash function `shake256` will be used, producing and output of **384 bits** length.
-
-### `createSecureHash`
-
-```typescript
-public createCustomHash (
-  data: string
-): Buffer;
-```
-
-#### **Parameters:**
-
-| Name                           | Type   | Default | Description                                                                                                 |
-|--------------------------------|--------|---------|-------------------------------------------------------------------------------------------------------------|
-| **data** <RequiredLabel/>      | string |         | String to hash                                                                                              |
-
-#### **Outputs:**
-
-As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
-
-#### **Usage:**
-```typescript
-async secureHashUserPasswrd(
-  plainPassword: string,
-): string {
-  const hashedPassword = this.cryptographyService.createSecureHash(plainPassword);
-  return hashedPassword.toString('hex')
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Verify a secure HASH
-
-Method to verify if an existing hash matches the hash of the desired text.
-:::warning
-Remember that the previous hash must have been generated using [`createSecureHash`](hashing#createsecurehash) method.
-:::
-
-
-### `verifySecureHash`
-
-```typescript
-public verifySecureHash (
-  data: string,
-  oldHash: string | Buffer
-): boolean;
-```
-
-#### **Parameters:**
-
-| Name                         | Type             | Default | Description                           |
-|------------------------------|------------------|---------|---------------------------------------|
-| **data** <RequiredLabel/>    | string           |         | String to hash                        |
-| **oldHash** <RequiredLabel/> | Buffer \| string |         | Buffer or string of the existing hash |
-
-#### **Outputs:**
-
-As output, it will return `true` if both matches, or `false` if not.
-
-<TimingAttack/>
-
-#### **Usage:**
-```typescript
-async checkUserPassword(
-  plainPassword: string,
-  hashedPassword: string,
-): boolean {
-  const bufferExistingHash = Buffer.from(hashedPassword, 'utf-8');
-  return this.cryptographyService.verifySecureHash(plainPassword, bufferExistingHash);
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Create insecure fast HASH
-
-Method to create an insecure but fast hash using the _**sha1**_ digest algorithm.
-
-:::danger
-This method should not be used if you want to guarantee good security.
-
-[Read this article][3]
-:::
-
-### `createInsecureFastHash`
-
-```typescript
-public createInsecureFastHash (
-  data: string
-): Buffer;
-```
-
-#### **Parameters:**
-
-| Name                         | Type             | Default | Description                           |
-|------------------------------|------------------|---------|---------------------------------------|
-| **data** <RequiredLabel/>    | string           |         | String to hash                        |
-
-#### **Outputs:**
-
-As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
-
-#### **Usage:**
-```typescript
-async exampleFastHashSHA1(): string {
-  const sha1Hash = this.cryptographyService.createInsecureFastHash('this is not a secret');
-  return sha1Hash.toString('base64')
-}
-```
-
-
-
-
-<Tips />
-
-[1]: https://nodejs.org/api/buffer.html
-[2]: https://en.wikipedia.org/wiki/Hash_function
-[3]: https://www.schneier.com/blog/archives/2005/02/sha1_broken.html