nestjs-cryptography 3.0.0 → 3.1.0

package/wiki/docs/guides/hashing.mdx

@@ -1,258 +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 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 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
-
-#### <GenericLabel />
-
-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 | Buffer,
-  options?: GenericOptionsInterface,
-): Buffer;
-```
-
-#### **Parameters:**
-
-| Name                           | Type                       | Default | Description                                                      |
-|--------------------------------|----------------------------|---------|------------------------------------------------------------------|
-| **algorithm** <RequiredLabel/> | string                     |         | Digest algorithm to use (`sha1, sha256, sha3-256,...`)           |
-| **data** <RequiredLabel/>      | string \| Buffer           |         | String or buffer to hash                                         |
-| **options**                    | [GenericOptions](#options) | `{}`    | Optional configuration object for input data encoding and output |
-
-#### **Options:**
-
-| Name              | Type                  | Default | Description                                                                                                 |
-|-------------------|-----------------------|---------|-------------------------------------------------------------------------------------------------------------|
-| inputDataEncoding | [`BufferEncoding`][4] |         | Specifies the encoding of the input data (e.g., 'hex', 'base64').                                           |
-| outputLength      | number                |         | 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(
-      'sha256',
-      plainPassword,
-      {
-        inputDataEncoding: 'utf-8',
-      }
-  );
-  return hashedPassword.toString('hex')
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Verify a custom HASH
-
-#### <GenericLabel />
-
-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 | Buffer,
-  oldHash: string | Buffer,
-  options?: GenericOptionsInterface,
-): boolean;
-```
-
-#### **Parameters:**
-
-| Name                           | Type                         | Default | Description                                                      |
-|--------------------------------|------------------------------|---------|------------------------------------------------------------------|
-| **algorithm** <RequiredLabel/> | string                       |         | Digest algorithm to use (`sha1, sha256, sha3-256,...`)           |
-| **data** <RequiredLabel/>      | string \| Buffer             |         | String or buffer to hash                                         |
-| **oldHash** <RequiredLabel/>   | string \| Buffer             |         | String or buffer of the existing hash                            |
-| **options**                    | [GenericOptions](#options-1) | `{}`    | Optional configuration object for input data encoding and output |
-
-#### **Options:**
-
-| Name              | Type                  | Default | Description                                                                                                 |
-|-------------------|-----------------------|---------|-------------------------------------------------------------------------------------------------------------|
-| inputDataEncoding | [`BufferEncoding`][4] |         | Specifies the encoding of the input data (e.g., 'hex', 'base64').                                           |
-| outputLength      | number                |         | 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 {
-  return this.cryptographyService.verifyCustomHash(
-      'sha256',
-      Buffer.from(plainPassword, 'utf-8'),
-      Buffer.from(bufferExistingHash, 'hex'),
-    );
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Create a secure HASH
-
-#### <RecommendedLabel />
-
-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,
-  options?: GenericOptionsInterface,
-): Buffer;
-```
-
-#### **Parameters:**
-
-| Name                      | Type                         | Default | Description                                                      |
-|---------------------------|------------------------------|---------|------------------------------------------------------------------|
-| **data** <RequiredLabel/> | string \| Buffer             |         | String or buffer to hash                                         |
-| **options**               | [GenericOptions](#options-2) | `{}`    | Optional configuration object for input data encoding and output |
-
-#### **Options:**
-
-| Name              | Type                  | Default | Description                                                       |
-|-------------------|-----------------------|---------|-------------------------------------------------------------------|
-| inputDataEncoding | [`BufferEncoding`][4] |         | 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 secureHashUserPasswrd(
-  plainPassword: string,
-): string {
-  const hashedPassword = this.cryptographyService.createSecureHash(
-      plainPassword,
-      {
-        inputDataEncoding: 'utf-8',
-      }
-    );
-  return hashedPassword.toString('hex')
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Verify a secure HASH
-
-#### <RecommendedLabel />
-
-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 | Buffer,
-  oldHash: string | Buffer,
-  options?: GenericOptionsInterface,
-): boolean;
-```
-
-#### **Parameters:**
-
-| Name                         | Type                         | Default | Description                                                      |
-|------------------------------|------------------------------|---------|------------------------------------------------------------------|
-| **data** <RequiredLabel/>    | string \| Buffer             |         | String or buffer to hash                                         |
-| **oldHash** <RequiredLabel/> | string \| Buffer             |         | String or buffer of the existing hash                            |
-| **options**                  | [GenericOptions](#options-3) | `{}`    | Optional configuration object for input data encoding and output |
-
-#### **Options:**
-
-| Name              | Type                  | Default | Description                                                       |
-|-------------------|-----------------------|---------|-------------------------------------------------------------------|
-| inputDataEncoding | [`BufferEncoding`][4] |         | Specifies the encoding of the input data (e.g., 'hex', 'base64'). |
-
-#### **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, 'hex');
-  const bufferPlainPassword = Buffer.from(plainPassword, 'utf-8');
-
-  return this.cryptographyService.verifySecureHash(
-    bufferPlainPassword,
-    bufferExistingHash
-  );
-}
-```
-
-
-[//]: #--------------------#
-
-
-<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
-[4]: https://nodejs.org/api/buffer.html#buffers-and-character-encodings
-

package/wiki/docs/guides/hmac.mdx

@@ -1,271 +0,0 @@
----
-title: HMAC
-sidebar_label: HMAC
-sidebar_position: 5
-description: Methods to create generic and secure HMACs
----
-
-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 dive into various methods for applying cryptographic [HMAC hash-based message authentication code][2]
-both generically and securely.
-We will cover best practices to ensure that the hmac process is robust against common vulnerabilities.
-Additionally, we will explore secure techniques for comparing hmac 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 HMAC
-
-#### <GenericLabel />
-
-Method to create a hmac of a text where you could choose the desired digest algorithm to use `sha1, sha256, sha3-256,...`
-
-### `createCustomHmac`
-
-```typescript
-public createCustomHmac (
-  algorithm: string,
-  key: string | Buffer,
-  data: string | Buffer,
-  options?: GenericOptionsInterface,
-): Buffer;
-```
-
-**Parameters:**
-
-| Name                           | Type                       | Default | Description                                                      |
-|--------------------------------|----------------------------|---------|------------------------------------------------------------------|
-| **algorithm** <RequiredLabel/> | string                     |         | Digest algorithm to use (`sha1, sha256, sha3-256,...`)           |
-| **key** <RequiredLabel/>       | string \| Buffer           |         | Secret key to use on the hmac                                    |
-| **data** <RequiredLabel/>      | string \| Buffer           |         | String or buffer to hmac                                         |
-| **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'). |
-| 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>`
-
-#### **Usage:**
-```typescript
-async exampleHmac(
-  data: string,
-): string {
-  const hmacResult = this.cryptographyService.createCustomHmac(
-      'sha512',
-      'strong_key',
-      'test',
-      {
-        inputDataEncoding: 'utf-8',
-        inputKeyEncoding: 'utf-8',
-      }
-    );
-  return hmacResult.toString('hex')
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Verify a custom HMAC
-
-#### <GenericLabel />
-
-Method to verify if an existing hmac matches the hmac of the desired text.
-You need choose the existing hmac algorithm type used `sha1, sha256, sha3-256,...`
-
-### `verifyCustomHmac`
-
-```typescript
-public verifyCustomHmac (
-  algorithm: string,
-  key: string | Buffer,
-  data: string | Buffer,
-  oldHmac: string | Buffer,
-  options?: GenericOptionsInterface,
-): boolean;
-```
-
-**Parameters:**
-
-| Name                           | Type                         | Default | Description                                                      |
-|--------------------------------|------------------------------|---------|------------------------------------------------------------------|
-| **algorithm** <RequiredLabel/> | string                       |         | Digest algorithm to use (`sha1, sha256, sha3-256,...`)           |
-| **key** <RequiredLabel/>       | string \| Buffer             |         | Secret key to use on the hmac                                    |
-| **data** <RequiredLabel/>      | string \| Buffer             |         | String or buffer to hmac                                         |
-| **oldHmac** <RequiredLabel/>   | string \| Buffer             |         | String or buffer of the existing hmac                            |
-| **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'). |
-| inputKeyEncoding  | [`BufferEncoding`][3] |         | Specifies the encoding of the input key (e.g., 'hex', 'base64').  |
-
-**Outputs:**
-
-As output, it will return `true` if both matches, or `false` if not.
-
-<TimingAttack/>
-
-#### **Usage:**
-```typescript
-async checkHmac(
-  oldKey: string,
-  existingHmac: string,
-  data: string,
-): boolean {
-  const bufferExistingHmac = Buffer.from(existingHmac, 'hex');
-  return this.cryptographyService.verifyCustomHmac(
-      'sha512',
-      oldKey,
-      data,
-      bufferExistingHmac,
-      {
-        inputDataEncoding: 'utf-8',
-        inputKeyEncoding: 'hex',
-      },
-    );
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Create a secure HMAC
-
-#### <RecommendedLabel />
-
-Method to create an extra secure hmac of a text.
-
-In this case the `sha3-256` digest algorithm will be used.
-
-### `createSecureHmac`
-
-```typescript
-public createSecureHmac (
-  data: string | Buffer,
-  options?: GenericOptionsInterface,
-): Buffer;
-```
-
-**Parameters:**
-
-| Name                      | Type                         | Default | Description                                                      |
-|---------------------------|------------------------------|---------|------------------------------------------------------------------|
-| **data** <RequiredLabel/> | string \| Buffer             |         | String or buffer to hmac                                         |
-| **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'). |
-
-**Outputs:**
-
-As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
-
-#### **Usage:**
-```typescript
-async exampleSecureHmac(
-  data: string,
-): string {
-  const hmacResult = this.cryptographyService.createSecureHmac(
-      data,
-      {
-        inputDataEncoding: 'utf-8',
-      },
-    );
-  return hmacResult.toString('hex')
-}
-```
-
-
-[//]: #--------------------#
-
-
-## Verify a secure HMAC
-
-#### <RecommendedLabel />
-
-Method to verify if an existing hmac matches the hmac of the desired text.
-:::warning
-
-Remember that the previous hmac must have been generated using [`createSecureHmac`](hmac#createsecurehmac) method.
-
-:::
-
-
-### `verifySecureHmac`
-
-```typescript
-public verifySecureHmac (
-  data: string | Buffer,
-  oldHmac: string | Buffer,
-  options?: GenericOptionsInterface,
-): boolean;
-```
-
-**Parameters:**
-
-| Name                         | Type                         | Default | Description                                                      |
-|------------------------------|------------------------------|---------|------------------------------------------------------------------|
-| **data** <RequiredLabel/>    | string \| Buffer             |         | String or buffer to hmac                                         |
-| **oldHmac** <RequiredLabel/> | string \| Buffer             |         | String or buffer of the existing hmac                            |
-| **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 `true` if both matches, or `false` if not.
-
-<TimingAttack/>
-
-#### **Usage:**
-```typescript
-async exampleVerifySecureHmac(
-  data: string,
-  existingHmac: string,
-): boolean {
-  const bufferExistingHmac = Buffer.from(existingHmac, 'hex');
-  return this.cryptographyService.verifySecureHmac(
-    data,
-    bufferExistingHmac,
-    {
-      inputDataEncoding: 'utf-8',
-    },
-  );
-}
-```
-
-
-[//]: #--------------------#
-
-
-
-
-<Tips />
-
-
-
-[1]: https://nodejs.org/api/buffer.html
-[2]: https://en.wikipedia.org/wiki/HMAC
-[3]: https://nodejs.org/api/buffer.html#buffers-and-character-encodings

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

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