| 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.Low.PwdHash
Contents
Description
This module is based on the Password Based Key Deriviation section of the C++ API reference.
Synopsis
- pwdhash :: PBKDFName -> Int -> Int -> Int -> Int -> ByteString -> ByteString -> IO ByteString
- pwdhashTimed :: PBKDFName -> Int -> Int -> ByteString -> ByteString -> IO (Int, Int, Int, ByteString)
- type PBKDFName = ByteString
- pattern PBKDF2 :: PBKDFName
- pbkdf2 :: HashName -> PBKDFName
- pattern Scrypt :: PBKDFName
- pattern Argon2d :: PBKDFName
- pattern Argon2i :: PBKDFName
- pattern Argon2id :: PBKDFName
- pattern Bcrypt_PBKDF :: PBKDFName
- pattern OpenPGP_S2K :: PBKDFName
- openPGP_S2K :: HashName -> PBKDFName
Documentation
Arguments
| :: PBKDFName | algo: PBKDF algorithm, e.g., Scrypt or "PBKDF2(SHA-256)" |
| -> Int | param1: the first PBKDF algorithm parameter |
| -> Int | param2: the second PBKDF algorithm parameter (may be zero if unneeded) |
| -> Int | param3: the third PBKDF algorithm parameter (may be zero if unneeded) |
| -> Int | out_len: the desired length of the key to produce |
| -> ByteString | passphrase: the password to derive the key from |
| -> ByteString | salt[]: a randomly chosen salt |
| -> IO ByteString | out[]: buffer to store the derived key, must be of out_len bytes |
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.
Arguments
| :: PBKDFName | algo: PBKDF algorithm, e.g., Scrypt or "PBKDF2(SHA-256)" |
| -> Int | msec: the desired runtime in milliseconds |
| -> Int | out_len: the desired length of the key to produce |
| -> ByteString | passphrase: the password to derive the key from |
| -> ByteString | salt[]: a randomly chosen salt |
| -> IO (Int, Int, Int, ByteString) | A tuple of four elements (in order):
|
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, pwdhashTimed returns
parameters in a different order than the order in which they should be passed
to pwdhash. This is a known issue with the Botan C++ library. See
https://github.com/randombit/botan/issues/2144 for more information.
pwdhashTimed always returns parameters in this order:
(iterations, parallelism, memoryParam)
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 can be be manually extended to full
algorithm specification names, or by using utility functions like pbkdf2 that
this module also provides.
See the Available Schemes section of the C++ API reference for more information about available schemes.
type PBKDFName = ByteString Source #
The name of a key derivation scheme used as a PBKDF algorithm
pbkdf2 :: HashName -> PBKDFName Source #
>>>pbkdf2 SHA256"PBKDF2(SHA-256)"
NOTE: "PBKDF(HMAC(SHA-256))" is equivalent to "PBKDF(SHA-256)". pbkdf2
always outputs the latter given a hash function name.
pattern Bcrypt_PBKDF :: PBKDFName Source #
>>>Bcrypt_PBKDF"Bcrypt-PBKDF"
pattern OpenPGP_S2K :: PBKDFName Source #
>>>OpenPGP_S2K"OpenPGP-S2K"
openPGP_S2K :: HashName -> PBKDFName Source #
>>>openPGP_S2K SHA256"OpenPGP-S2K(SHA-256)"