pbkdf

Pure Haskell password-based KDF (docs.ppad.tech/pbkdf).
git clone git://git.ppad.tech/pbkdf.git
Log | Files | Refs | README | LICENSE

README.md (2950B)

      1 # pbkdf
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-pbkdf?color=blue)](https://hackage.haskell.org/package/ppad-pbkdf)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-pbkdf-lightblue)](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   "\"\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 my mid-2020 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                 533.2 μs   (490.9 μs .. 579.9 μs)
     43                        0.967 R²   (0.941 R² .. 0.993 R²)
     44   mean                 494.0 μs   (480.3 μs .. 518.3 μs)
     45   std dev              57.73 μs   (38.72 μs .. 98.81 μs)
     46   variance introduced by outliers: 81% (severely inflated)
     47 
     48   benchmarking ppad-pbkdf/PBKDF-SHA512/derive (outlen 32)
     49   time                 241.2 μs   (233.4 μs .. 249.6 μs)
     50                        0.991 R²   (0.987 R² .. 0.995 R²)
     51   mean                 233.6 μs   (227.8 μs .. 240.1 μs)
     52   std dev              20.22 μs   (16.95 μs .. 24.39 μs)
     53   variance introduced by outliers: 74% (severely inflated)
     54 ```
     55 
     56 ## Security
     57 
     58 This library aims at the maximum security achievable in a
     59 garbage-collected language under an optimizing compiler such as GHC, in
     60 which strict constant-timeness can be [challenging to achieve][const].
     61 
     62 The PBKDF implementation within has been tested against the [Project
     63 Wycheproof vectors][wyche] available for SHA-256 and SHA-512, using
     64 the HMAC functions from [ppad-sha256][sh256] and [ppad-sha512][sh512]
     65 respectively.
     66 
     67 If you discover any vulnerabilities, please disclose them via
     68 security@ppad.tech.
     69 
     70 ## Development
     71 
     72 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     73 development shell with:
     74 
     75 ```
     76 $ nix develop
     77 ```
     78 
     79 Then do e.g.:
     80 
     81 ```
     82 $ cabal repl ppad-pbkdf
     83 ```
     84 
     85 to get a REPL for the main library.
     86 
     87 [nixos]: https://nixos.org/
     88 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
     89 [hadoc]: https://docs.ppad.tech/pbkdf
     90 [sh256]: https://git.ppad.tech/sha256
     91 [sh512]: https://git.ppad.tech/sha512
     92 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html
     93 [wyche]: https://github.com/C2SP/wycheproof