Skip to content

Derive

The key derivation functions are provided under the crypt.derive namespace.

key

function crypt.derive.key(length: number, key: string, sub_key_id: number, context: string): string

Derives a key from another key using HKDF.

Example

local derived_key = crypt.derive.key(32, master_key, 1, "encryption")

id

function crypt.derive.id(length: number, key: string, id: string): string

Derives a key from a key and an identifier.

Example

local derived_key = crypt.derive.id(32, master_key, "user123")

password

function crypt.derive.password(length: number, password: string, salt: string, iterations: number|string): string

Derives a key from a password using PBKDF2.

Parameters

  • length: Desired length of the derived key
  • password: The password to derive from
  • salt: A random salt (16 bytes recommended)
  • iterations: Number of iterations or a string: "Interactive", "Moderate", or "Sensitive"

Predefined Iteration Counts

Mode Iterations Description
Interactive 10,000 Suitable for interactive logins, providing a balance between security and user experience
Moderate 100,000 Provides stronger security, suitable for moderate sensitivity data
Sensitive 1,000,000 Highest security, suitable for highly sensitive data, but with longer computation time

The predefined modes offer different levels of security and performance:

  • Interactive: Designed for scenarios where quick response is needed, such as user logins. It provides a good balance between security and user experience.
  • Moderate: Offers increased security at the cost of longer computation time. Suitable for protecting moderately sensitive data or in scenarios where the extra time is acceptable.
  • Sensitive: Provides the highest level of security but takes significantly longer to compute. This mode should be used for highly sensitive data and in scenarios where the additional time is not a concern.

Example

local salt = crypt.generatebytes(16)  -- Generate a 16-byte salt
local derived_key = crypt.derive.password(32, "mypassword", salt, "Moderate")

In this example, we use the "Moderate" security level, which will perform 100,000 iterations.

Custom Iteration Count

You can also specify a custom iteration count if the predefined modes don't suit your needs:

local custom_iterations = 50000
local derived_key = crypt.derive.password(32, "mypassword", salt, custom_iterations)

Remember that higher iteration counts provide better security but require more computational time.