README.md (2836B)
1 # pbkdf 2 3 [](https://hackage.haskell.org/package/ppad-pbkdf) 4  5 [](https://docs.ppad.tech/pbkdf) 6 7 A password-based key derivation function (PBKDF2) per 8 [RFC2898](https://datatracker.ietf.org/doc/html/rfc2898). 9 10 ## Usage 11 12 A sample GHCi session: 13 14 ``` 15 > :set -XOverloadedStrings 16 > -- import qualified 17 > import qualified Crypto.KDF.PBKDF as KDF 18 > 19 > -- supply your own HMAC function 20 > import qualified Crypto.Hash.SHA256 as SHA256 21 > 22 > -- derive a 32-byte key from a secret 23 > KDF.derive SHA256.hmac "my password" "my salt" 100 32 24 Just "\"\NAKqxp\165S\t\212i\139\SUB(\132\176\204\224<\164\177\144\&1D\209\175\145\139[K\159h\205" 25 ``` 26 27 ## Documentation 28 29 Haddocks (API documentation, etc.) are hosted at 30 [docs.ppad.tech/pbkdf][hadoc]. 31 32 ## Performance 33 34 The aim is best-in-class performance for pure, highly-auditable Haskell 35 code. 36 37 Current benchmark figures on an M4 Silicon MacBook Air look like (use 38 `cabal bench` to run the benchmark suite): 39 40 ``` 41 benchmarking ppad-pbkdf/PBKDF-SHA256/derive (outlen 32) 42 time 216.9 μs (216.3 μs .. 217.3 μs) 43 1.000 R² (1.000 R² .. 1.000 R²) 44 mean 215.7 μs (215.3 μs .. 216.1 μs) 45 std dev 1.446 μs (1.275 μs .. 1.819 μs) 46 47 benchmarking ppad-pbkdf/PBKDF-SHA512/derive (outlen 32) 48 time 113.5 μs (113.3 μs .. 113.6 μs) 49 1.000 R² (1.000 R² .. 1.000 R²) 50 mean 113.4 μs (113.3 μs .. 113.5 μs) 51 std dev 303.1 ns (256.5 ns .. 398.4 ns) 52 ``` 53 54 ## Security 55 56 This library aims at the maximum security achievable in a 57 garbage-collected language under an optimizing compiler such as GHC, in 58 which strict constant-timeness can be [challenging to achieve][const]. 59 60 The PBKDF implementation within has been tested against the [Project 61 Wycheproof vectors][wyche] available for SHA-256 and SHA-512, using 62 the HMAC functions from [ppad-sha256][sh256] and [ppad-sha512][sh512] 63 respectively. 64 65 If you discover any vulnerabilities, please disclose them via 66 security@ppad.tech. 67 68 ## Development 69 70 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 71 development shell with: 72 73 ``` 74 $ nix develop 75 ``` 76 77 Then do e.g.: 78 79 ``` 80 $ cabal repl ppad-pbkdf 81 ``` 82 83 to get a REPL for the main library. 84 85 [nixos]: https://nixos.org/ 86 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 87 [hadoc]: https://docs.ppad.tech/pbkdf 88 [sh256]: https://git.ppad.tech/sha256 89 [sh512]: https://git.ppad.tech/sha512 90 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html 91 [wyche]: https://github.com/C2SP/wycheproof