Copyright	(C) Hécate Moonlight 2022
License	BSD-3-Clause
Maintainer	The Haskell Cryptography Group
Stability	Stable
Portability	GHC only
Safe Haskell	Trustworthy
Language	Haskell2010

LibSodium.Bindings.Scrypt

Contents

Introduction
Key Derivation
Password storage
Constants

Description

Synopsis

cryptoPWHashScryptSalsa2018SHA256 :: Ptr CUChar -> CULLong -> Ptr CChar -> CULLong -> Ptr CUChar -> CULLong -> CSize -> IO CInt
cryptoPWHashScryptSalsa2018SHA256Str :: Ptr CChar -> Ptr CChar -> CULLong -> CULLong -> CSize -> IO CInt
cryptoPWHashScryptSalsa2018SHA256StrVerify :: Ptr CChar -> Ptr CChar -> CULLong -> IO CInt
cryptoPWHashScryptSalsa2018SHA256BytesMin :: CSize
cryptoPWHashScryptSalsa2018SHA256BytesMax :: CSize
cryptoPWHashScryptSalsa2018SHA256PasswdMin :: CSize
cryptoPWHashScryptSalsa2018SHA256PasswdMax :: CSize
cryptoPWHashScryptSalsa2018SHA256SaltBytes :: CSize
cryptoPWHashScryptSalsa2018SHA256StrBytes :: CSize
cryptoPWHashScryptSalsa2018SHA256StrPrefix :: Ptr CChar
cryptoPWHashScryptSalsa2018SHA256OpsLimitMin :: CSize
cryptoPWHashScryptSalsa2018SHA256OpsLimitMax :: CSize
cryptoPWHashScryptSalsa2018SHA256MemLimitMin :: CSize
cryptoPWHashScryptSalsa2018SHA256MemLimitMax :: CSize
cryptoPWHashScryptSalsa2018SHA256OpsLimitInteractive :: CSize
cryptoPWHashScryptSalsa2018SHA256MemLimitInteractive :: CSize
cryptoPWHashScryptSalsa2018SHA256OpsLimitSensitive :: CSize
cryptoPWHashScryptSalsa2018SHA256MemLimitSensitive :: CSize

Introduction

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 lock to lock memory regions storing plaintext passwords and to call unlock right after cryptoPWHashScryptSalsa2018SHA256Str and cryptoPWHashScryptSalsa2018SHA256StrVerify return.

Key Derivation

cryptoPWHashScryptSalsa2018SHA256 Source #

Arguments

:: Ptr CUChar	A pointer to the computed key.
-> CULLong	The length of the computed key. Should be between `cryptoPWHashScryptSalsa2018SHA256BytesMin` and `cryptoPWHashScryptSalsa2018SHA256BytesMax` (~127 GB).
-> Ptr CChar	A pointer to the password from which the key is derived
-> CULLong	The length of the password. Should be between `cryptoPWHashScryptSalsa2018SHA256PasswdMin` and `cryptoPWHashScryptSalsa2018SHA256PasswdMax`.
-> Ptr CUChar	The salt, of length `cryptoPWHashScryptSalsa2018SHA256SaltBytes`.
-> CULLong	opslimit: The maximum amount of computations to perform. Must be between `cryptoPWHashScryptSalsa2018SHA256OpsLimitMin` and `cryptoPWHashScryptSalsa2018SHA256OpsLimitMax`.
-> 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 `cryptoPWHashScryptSalsa2018SHA256MemLimitMin` and `cryptoPWHashScryptSalsa2018SHA256MemLimitMax`.
-> 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, cryptoPWHashScryptSalsa2018SHA256OpsLimitInteractive and cryptoPWHashScryptSalsa2018SHA256MemLimitInteractive provide a safe baseline to be used. However, using higher values may improve security.

For highly sensitive data, cryptoPWHashScryptSalsa2018SHA256OpsLimitSensitive and cryptoPWHashScryptSalsa2018SHA256MemLimitSensitive 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 cryptoPWHashScryptSalsa2018SHA256SaltBytes 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()

Since: 0.0.1.0

Password storage

cryptoPWHashScryptSalsa2018SHA256Str Source #

Arguments

:: Ptr CChar	A pointer to the buffer receiving the string.
-> Ptr CChar	The password
-> CULLong	Password length
-> CULLong	opslimit: The maximum amount of computations to perform. The `cryptoPWHashScryptSalsa2018SHA256OpsLimitInteractive` constant is a safe baseline value to use.
-> CSize	memlimit: The maximum amount of RAM in bytes that the function will use. The `cryptoPWHashScryptSalsa2018SHA256MemLimitInteractive` constant is a safe baseline value to use.
-> 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()

Since: 0.0.1.0

cryptoPWHashScryptSalsa2018SHA256StrVerify Source #

Arguments

:: Ptr CChar	The password verification C-string, of size `cryptoPWHashScryptSalsa2018SHA256StrBytes` bytes.
-> Ptr CChar	The password.
-> CULLong	The password length.
-> IO CInt	Returns 0 on success, -1 on password verification failure.