Copyright	(c) 2023-2024 Apotheca Labs (c) 2024-2025 Haskell Foundation
License	BSD-3-Clause
Maintainer	joris@well-typed.com, leo@apotheca.io
Stability	experimental
Portability	POSIX
Safe Haskell	Safe-Inferred
Language	GHC2021

Botan.Bindings.PwdHash

Contents

Available schemes

Description

This module is based on the Password Based Key Deriviation section of the C++ API reference.

Synopsis

botan_pwdhash :: ConstPtr CChar -> CSize -> CSize -> CSize -> Ptr Word8 -> CSize -> ConstPtr CChar -> CSize -> ConstPtr Word8 -> CSize -> IO CInt
botan_pwdhash_timed :: ConstPtr CChar -> Word32 -> Ptr CSize -> Ptr CSize -> Ptr CSize -> Ptr Word8 -> CSize -> ConstPtr CChar -> CSize -> ConstPtr Word8 -> CSize -> IO CInt
pattern BOTAN_PBKDF_PBKDF2 :: (Eq a, IsString a) => a
pattern BOTAN_PBKDF_SCRYPT :: (Eq a, IsString a) => a
pattern BOTAN_PBKDF_ARGON2D :: (Eq a, IsString a) => a
pattern BOTAN_PBKDF_ARGON2I :: (Eq a, IsString a) => a
pattern BOTAN_PBKDF_ARGON2ID :: (Eq a, IsString a) => a
pattern BOTAN_PBKDF_BCRYPT_PBKDF :: (Eq a, IsString a) => a
pattern BOTAN_PBKDF_OPENPGP_S2K :: (Eq a, IsString a) => a

Documentation

botan_pwdhash Source #

Arguments

:: ConstPtr CChar	algo: PBKDF algorithm, e.g., "PBKDF2(SHA-256)" or Scrypt
-> CSize	param1: the first PBKDF algorithm parameter
-> CSize	param2: the second PBKDF algorithm parameter (may be zero if unneeded)
-> CSize	param3: the third PBKDF algorithm parameter (may be zero if unneeded)
-> Ptr Word8	out[]: buffer to store the derived key, must be of out_len bytes
-> CSize	out_len: the desired length of the key to produce
-> ConstPtr CChar	passphrase: the password to derive the key from
-> CSize	passphrase_len: if > 0, specifies length of password. If len == 0, then strlen will be called on passphrase to compute the length.
-> ConstPtr Word8	salt[]: a randomly chosen salt
-> CSize	salt_len: length of salt in bytes
-> IO CInt	0 on success, a negative value on failure

Derive a cryptographic key from a passphrase using algorithm-specific parameters

NOTE: the interpretation of parameters param1, param2, and param3 are different depending on the PBKDF algorithm that is picked. See the documentation of the from_params C++ function for more information about the meaning of the parameters.

botan_pwdhash_timed Source #

Arguments

:: ConstPtr CChar	algo: PBKDF algorithm, e.g., Scrypt or "PBKDF2(SHA-256)"
-> Word32	msec: the desired runtime in milliseconds
-> Ptr CSize	param1: will be set to the first PBKDF algorithm parameter
-> Ptr CSize	param2: will be set to the second PBKDF algorithm parameter (may be zero if unneeded)
-> Ptr CSize	param3: will be set to the third PBKDF algorithm parameter (may be zero if unneeded)
-> Ptr Word8	out[]: buffer to store the derived key, must be of out_len bytes
-> CSize	out_len: the desired length of the key to produce
-> ConstPtr CChar	passphrase: the password to derive the key from
-> CSize	passphrase_len: if > 0, specifies length of password. If len == 0, then strlen will be called on passphrase to compute the length.
-> ConstPtr Word8	salt[]: a randomly chosen salt
-> CSize	salt_len: length of salt in bytes
-> IO CInt	0 on success, a negative value on failure

Derive a cryptographic key from a passphrase using algorithm-specific parameters that are tuned automatically for a desired running time of the algorithm.

NOTE: for the Argon2 and Scrypt PBKDF algorithms, botan_pwdhash_timed returns parameters in a different order than the order in which they should be passed to botan_pwdhash. This is a known issue with the Botan C++ library. See https://github.com/randombit/botan/issues/2144 for more information.

botan_pwdhash_timed always returns parameters in this order:

(iterations, parallelism, memoryParam)

botan_pwdhash shoulds be given parameters in this order for the Argon2 and Scrypt algorithms:

param1 = memoryParam
param2 = iterations
param3 = parallelism

Available schemes

A number of algorithms are available to be used as password derivation schemes. An algorithm is selected by passing the algorithm specification name of the algorithm as a string to the password hashing functions. In some cases an algorithm specification name is just the algorithm name, like Scrypt. In other cases an algorithm specification name is a combination of an algorithm name paired with some parameters, such as "PKBDF2(SHA-256)" where PBKDF2 is the algorithm name followed by a single parameter. Pattern synonyms are included for each available algorithm name. Where necessary, such as in the PBKDF2 case, these algorithm names should be manually extended to full algorithm specification names.

See the Available Schemes section of the C++ API reference for more information about available schemes.

pattern BOTAN_PBKDF_PBKDF2 :: (Eq a, IsString a) => a Source #

>>> BOTAN_PBKDF_PBKDF2 @String
"PBKDF2"

pattern BOTAN_PBKDF_SCRYPT :: (Eq a, IsString a) => a Source #

>>> BOTAN_PBKDF_SCRYPT @String
"Scrypt"

pattern BOTAN_PBKDF_ARGON2D :: (Eq a, IsString a) => a Source #

>>> BOTAN_PBKDF_ARGON2D @String
"Argon2d"

pattern BOTAN_PBKDF_ARGON2I :: (Eq a, IsString a) => a Source #

>>> BOTAN_PBKDF_ARGON2I @String
"Argon2i"

pattern BOTAN_PBKDF_ARGON2ID :: (Eq a, IsString a) => a Source #

>>> BOTAN_PBKDF_ARGON2ID @String
"Argon2id"

pattern BOTAN_PBKDF_BCRYPT_PBKDF :: (Eq a, IsString a) => a Source #

>>> BOTAN_PBKDF_BCRYPT_PBKDF @String
"Bcrypt-PBKDF"

pattern BOTAN_PBKDF_OPENPGP_S2K :: (Eq a, IsString a) => a Source #

>>> BOTAN_PBKDF_OPENPGP_S2K @String
"OpenPGP-S2K"