nestjs-cryptography 2.2.2 → 3.0.0

package/wiki/docs/guides/generics.mdx

@@ -0,0 +1,170 @@
+---
+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 | boolean | false   | Decide to use a more secure generation, preventing the use of an entropy cache |
+
+
+**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 secure random data
+
+Method to generate a secure random data of the desired length.
+
+### `createSafeRandomData`
+
+```tsx
+public createSafeRandomData (
+  length: number
+): Buffer;
+```
+
+**Parameters:**
+
+| Name                    | Type   | Default | Description                            |
+|-------------------------|--------|---------|----------------------------------------|
+| length <RequiredLabel/> | number |         | The random data output length in bytes |
+
+
+**Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+
+[//]: #--------------------#
+
+
+## Generate random password
+
+Method to generate a random password with this set of characters: `A-Z a-z 0-9 + = /`.
+
+### `genRandomPassword`
+
+```tsx
+public genRandomPassword (
+  length: number
+): string;
+```
+
+**Parameters:**
+
+| Name                      | Type          | Default | Description                                      |
+|---------------------------|---------------|---------|--------------------------------------------------|
+| length <RequiredLabel/>   | number        |         | The password output length                       |
+
+
+**Outputs:**
+
+As output, it will return a string of this format: `jh2EducrV7yH8tGAc8Jkdcso`
+
+**Usage:**
+```typescript
+async createUserPassword(): Promise<string> {
+  const newPassword = this.cryptographyService.genRandomPassword(24);
+  ...
+  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/docs/guides/hashing.mdx

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

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