nestjs-cryptography 2.2.2 → 3.0.0

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

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

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

@@ -0,0 +1,198 @@
+---
+title: HMAC
+sidebar_label: HMAC
+sidebar_position: 5
+description: Methods to create generic and secure HMACs
+---
+
+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 [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
+
+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: Buffer,
+  data: string,
+): Buffer;
+```
+
+**Parameters:**
+
+| Name                           | Type   | Default | Description                                            |
+|--------------------------------|--------|---------|--------------------------------------------------------|
+| **algorithm** <RequiredLabel/> | string |         | Digest algorithm to use (`sha1, sha256, sha3-256,...`) |
+| **key** <RequiredLabel/>       | Buffer |         | Secret key to use on the hmac                          |
+| **data** <RequiredLabel/>      | string |         | String to hmac                                         |
+
+**Outputs:**
+
+As output, it will return a [Buffer][1] `<Buffer cc 2b.....cd a1 08>`
+
+#### **Usage:**
+```typescript
+async exampleHmac(
+  data: string,
+): string {
+  const key = this.cryptographyService.generateSymmetricKey(128);
+  const hmacResult = this.cryptographyService.createCustomHmac('sha-512', key, data);
+  return hmacResult.toString('hex')
+}
+```
+
+
+[//]: #--------------------#
+
+
+## Verify a custom HMAC
+
+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: Buffer,
+  data: string,
+  oldHmac: string | Buffer,
+): boolean;
+```
+
+**Parameters:**
+
+| Name                           | Type             | Default | Description                                            |
+|--------------------------------|------------------|---------|--------------------------------------------------------|
+| **algorithm** <RequiredLabel/> | string           |         | Digest algorithm to use (`sha1, sha256, sha3-256,...`) |
+| **key** <RequiredLabel/>       | Buffer           |         | Secret key to use on the hmac                          |
+| **data** <RequiredLabel/>      | string           |         | String to hmac                                         |
+| **oldHmac** <RequiredLabel/>   | string \| Buffer |         | Buffer or string of the existing hmac                  |
+
+**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');
+  const bufferOldKey = Buffer.from(oldKey, 'hex');
+  return this.cryptographyService.verifyCustomHmac('sha-512', bufferOldKey, data, bufferExistingHmac);
+}
+```
+
+
+[//]: #--------------------#
+
+
+## Create a secure HMAC
+
+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;
+```
+
+**Parameters:**
+
+| Name                           | Type   | Default | Description                                                                                                 |
+|--------------------------------|--------|---------|-------------------------------------------------------------------------------------------------------------|
+| **data** <RequiredLabel/>      | string |         | String to hmac                                                                                              |
+
+**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);
+  return hmacResult.toString('hex')
+}
+```
+
+
+[//]: #--------------------#
+
+
+## Verify a secure HMAC
+
+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,
+  oldHmac: string | Buffer
+): boolean;
+```
+
+**Parameters:**
+
+| Name                         | Type             | Default | Description                           |
+|------------------------------|------------------|---------|---------------------------------------|
+| **data** <RequiredLabel/>    | string           |         | String to hmac                        |
+| **oldHmac** <RequiredLabel/> | Buffer \| string |         | Buffer or string of the existing hmac |
+
+**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);
+}
+```
+
+
+[//]: #--------------------#
+
+
+
+
+<Tips />
+
+
+
+[1]: https://nodejs.org/api/buffer.html
+[2]: https://en.wikipedia.org/wiki/HMAC

package/wiki/versioned_docs/version-2.x/guides/key-derivation.mdx

@@ -0,0 +1,98 @@
+---
+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/> | boolean | false   | MasterKey of password to derive                     |
+| **salt** <RequiredLabel/>      | Buffer  | false   | Salt to increase the security of the key derivation |
+| **length** <RequiredLabel/>    | number  | false   | 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.
+      This is set via [`kdf.defaultOutputKeyLength`][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#defaultoutputkeylength
+[4]: ../api-reference/settings#argon2type
+[5]: ../api-reference/settings#memorycost
+[6]: ../api-reference/settings#timecost

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

@@ -0,0 +1,132 @@
+---
+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 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/> | Buffer \| string |         | Buffer or string 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
+[6]: ../api-reference/settings#argon2type-1
+[7]: ../api-reference/settings#memorycost-1
+[8]: ../api-reference/settings#timecost-1