README.md (2945B)
1 # hkdf 2 3 [](https://hackage.haskell.org/package/ppad-hkdf) 4  5 [](https://docs.ppad.tech/hkdf) 6 7 A HMAC-based key derivation function (HKDF) per 8 [RFC5869](https://datatracker.ietf.org/doc/html/rfc5869). 9 10 ## Usage 11 12 A sample GHCi session: 13 14 ``` 15 > :set -XOverloadedStrings 16 > -- import qualified 17 > import qualified Crypto.KDF.HMAC 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 salt" "my optional info" 32 "my secret input" 24 "\EM\232\v\140\202\230\f2:\221n\221\209\233\US\209>\174_!\138\255\\C\150\237^X\226\tt\252" 25 ``` 26 27 ## Documentation 28 29 Haddocks (API documentation, etc.) are hosted at 30 [docs.ppad.tech/hkdf][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-hkdf/HKDF-SHA256/derive (outlen 32) 42 time 12.69 μs (12.58 μs .. 12.84 μs) 43 0.999 R² (0.999 R² .. 1.000 R²) 44 mean 12.82 μs (12.75 μs .. 12.89 μs) 45 std dev 231.0 ns (190.1 ns .. 299.9 ns) 46 variance introduced by outliers: 16% (moderately inflated) 47 48 benchmarking ppad-hkdf/HKDF-SHA512/derive (outlen 32) 49 time 12.24 μs (12.16 μs .. 12.31 μs) 50 1.000 R² (1.000 R² .. 1.000 R²) 51 mean 12.27 μs (12.22 μs .. 12.32 μs) 52 std dev 172.4 ns (131.6 ns .. 246.5 ns) 53 variance introduced by outliers: 11% (moderately 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 HKDF 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-hkdf 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/hkdf 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