syn.crypt.derive

Functions

key

string syn.crypt.derive.key(len: uint, key: string, sub_key_id: uint, context: string)

Derives a cryptographic key from another key specified - len specifies the length of the generated key, sub_key_id is the index of the key to generate, and context is a 8-byte string that uniquely identifies the script that is generating this key.

The context string can be any 8 ASCII characters. Some examples are SynapseX, MyScript, and _Script_.

Note: Due to Lua's usage of 64 bit floating point numbers, the maximum safe integer to pass to sub_key_id is 2^52. Passing a larger number will result in undefined behavior.

(Uses libsodium key derivation.)

string syn.crypt.derive.key(len: uint, key: string, id: string)

Alternatively, you can derive a cryptographic key from key with len length from a simple ID passed into id. This can be a message of any length.

(Uses libsodium generic hashing, with the key being used for a keyed hash.)

password

string syn.crypt.derive.password(len: uint, password: string, salt: string, mode: PasswordDerivationMode) [yields]

Derives a cryptographic key from a user-entered password. Due to passwords usually being low-complexity and easy to crack, this function uses a password hashing function to achieve its goals.

In order to use this function, you must pass a 16-byte salt. You can generate this via syn.crypt.random.

Password hashing functions are deliberately slow - this is to make bruteforce attacks harder. The mode (or opslimit/memlimit) parameter allows you to specify how much security you want your derived key to have. You should choose the mode you wish to use based on how acceptable the wait for function completion is for your application, and what the security requirements for your application are.

Warning: Using the higher security PasswordDerivationMode options (or a memlimit parameter higher then 512MiB) with more then one password hash being processed at once can cause crashes due to high-memory requirements for the hash function.

(Uses libsodium password hashing.)

PasswordDerivationMode

string syn.crypt.derive.password(len: uint, password: string, salt: string, ops_limit: uint, mem_limit: uint) [yields]