HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Modulelibsodium-bindings-0.0.1.1Haskell2010

LibSodium.Bindings.Scrypt

  • 18 values

Introduction

0 declarations

This is an implementation of the scrypt password hashing function. However, unless you have specific reasons to use scrypt, you should instead consider the default function Argon2.

Glossary

  • opslimit: The maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key.

  • memlimit: The maximum amount of RAM in bytes that the function will use.

Guidelines for choosing scrypt parameters

Start by determining how much memory the scrypt function can use.

  • What will be the highest number of threads/processes evaluating the function simultaneously (ideally, no more than 1 per CPU core)?

  • How much physical memory is guaranteed to be available? The memlimit parameter should be a power of 2.

Do not use anything less than 16 MiB, even for interactive use. A reasonable starting point for opslimit is memlimit / 32. Measure how long the scrypt function needs to hash a password. If this is way too long for your application, reduce memlimit and adjust opslimit using the above formula. If the function is so fast that you can afford it to be more computationally intensive without any usability issues, increase opslimit. For online use (e.g. logging in on a website), a 1 second computation is likely to be the acceptable maximum. For interactive use (e.g. a desktop application), a 5 second pause after having entered a password is acceptable if the password doesn't need to be entered more than once per session. For non-interactive and infrequent use (e.g. restoring an encrypted backup), an even slower computation can be an option. However, the best defense against brute-force password cracking is to use strong passwords. Libraries such as passwdqc can help enforce this.

Notes

Do not use constants to verify a password or produce a deterministic output. Save the parameters alongside the hash instead. By doing so, passwords can be rehashed using different parameters if required later on.

By design, a password whose length is 65 bytes or more is reduced to SHA-256(password). This can have security implications if the password is present in another password database using raw, unsalted SHA-256 or when upgrading passwords previously hashed with unsalted SHA-256 to scrypt.

It is highly recommended to use LibSodium.Bindings.SecureMemory.lock to lock memory regions storing plaintext passwords and to call LibSodium.Bindings.SecureMemory.unlock right after cryptoPWHashScryptSalsa208SHA256Str and cryptoPWHashScryptSalsa208SHA256StrVerify return.

Key Derivation

1 declaration
valuecryptoPWHashScryptSalsa208SHA256
  1. :: Ptr CUChar

    A pointer to the computed key.

  2. -> CULLong

    The length of the computed key. Should be between cryptoPWHashScryptSalsa208SHA256BytesMin and cryptoPWHashScryptSalsa208SHA256BytesMax (~127 GB).

  3. -> Ptr CChar

    A pointer to the password from which the key is derived

  4. -> CULLong

    The length of the password. Should be between cryptoPWHashScryptSalsa208SHA256PasswdMin and cryptoPWHashScryptSalsa208SHA256PasswdMax.

  5. -> Ptr CUChar

    The salt, of length cryptoPWHashScryptSalsa208SHA256SaltBytes.

  6. -> CULLong

    opslimit: The maximum amount of computations to perform. Must be between cryptoPWHashScryptSalsa208SHA256OpsLimitMin and cryptoPWHashScryptSalsa208SHA256OpsLimitMax.

  7. -> CSize

    memlimit: The maximum amount of RAM in bytes that the function will use. It is highly recommended to allow the function to use at least 16 MiB. This number must be between cryptoPWHashScryptSalsa208SHA256MemLimitMin and cryptoPWHashScryptSalsa208SHA256MemLimitMax.

  8. -> IO CInt

    Returns 0 on success, -1 if the computation didn't complete, usually because the operating system refused to allocate the amount of requested memory.

#

Derive a key from a password.

For interactive, online operations, cryptoPWHashScryptSalsa208SHA256OpsLimitInteractive and cryptoPWHashScryptSalsa208SHA256MemLimitInteractive provide a safe baseline to be used. However, using higher values may improve security.

For highly sensitive data, cryptoPWHashScryptSalsa208SHA256OpsLimitSensitive and cryptoPWHashScryptSalsa208SHA256MemLimitSensitive can be used as an alternative. However, with these parameters, deriving a key takes about 2 seconds on a 2.8 GHz Core i7 CPU and requires up to 1 GiB of dedicated RAM.

The salt should be unpredictable. randombytesBuf is the easiest way to fill the cryptoPWHashScryptSalsa208SHA256SaltBytes bytes of the salt.

Keep in mind that to produce the same key from the same password, the same salt, opslimit, and memlimit values must be used. Therefore, these parameters must be stored for each user.

See: crypto_pwhash_scryptsalsa208sha256()

Password storage

2 declarations
valuecryptoPWHashScryptSalsa208SHA256Str
  1. :: Ptr CChar

    A pointer to the buffer receiving the string.

  2. -> Ptr CChar

    The password

  3. -> CULLong

    Password length

  4. -> CULLong

    opslimit: The maximum amount of computations to perform. The cryptoPWHashScryptSalsa208SHA256OpsLimitInteractive constant is a safe baseline value to use.

  5. -> CSize

    memlimit: The maximum amount of RAM in bytes that the function will use. The cryptoPWHashScryptSalsa208SHA256MemLimitInteractive constant is a safe baseline value to use.

  6. -> IO CInt

    Returns 0 on success, -1 on error.

#

Generate an ASCII C-String string which includes:

  • The result of a memory-hard, CPU-intensive hash function applied to the password;

  • The automatically generated salt used for the previous computation;

  • The other parameters required to verify the password: opslimit and memlimit.

See: crypto_pwhash_scryptsalsa208sha256_str()

Constants

15 declarations