hkdf

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

README.md (2695B)

      1 # ppad-hkdf
      2 
      3 A HMAC-based key derivation function (HKDF) per
      4 [RFC5869](https://datatracker.ietf.org/doc/html/rfc5869).
      5 
      6 ## Usage
      7 
      8 A sample GHCi session:
      9 
     10 ```
     11   > :set -XOverloadedStrings
     12   > -- import qualified
     13   > import qualified Crypto.KDF.HMAC as KDF
     14   >
     15   > -- supply your own HMAC function
     16   > import qualified Crypto.Hash.SHA256 as SHA256
     17   >
     18   > -- derive a 32-byte key from a secret
     19   > KDF.derive SHA256.hmac "my salt" "my optional info" 32 "my secret input"
     20   "\EM\232\v\140\202\230\f2:\221n\221\209\233\US\209>\174_!\138\255\\C\150\237^X\226\tt\252"
     21 ```
     22 
     23 ## Documentation
     24 
     25 Haddocks (API documentation, etc.) are hosted at
     26 [docs.ppad.tech/hkdf][hadoc].
     27 
     28 ## Performance
     29 
     30 The aim is best-in-class performance for pure, highly-auditable Haskell
     31 code.
     32 
     33 Current benchmark figures on my mid-2020 MacBook Air look like (use
     34 `cabal bench` to run the benchmark suite):
     35 
     36 ```
     37   benchmarking ppad-hkdf/HKDF-SHA256/derive (outlen 32)
     38   time                 12.69 μs   (12.58 μs .. 12.84 μs)
     39                        0.999 R²   (0.999 R² .. 1.000 R²)
     40   mean                 12.82 μs   (12.75 μs .. 12.89 μs)
     41   std dev              231.0 ns   (190.1 ns .. 299.9 ns)
     42   variance introduced by outliers: 16% (moderately inflated)
     43 
     44   benchmarking ppad-hkdf/HKDF-SHA512/derive (outlen 32)
     45   time                 12.24 μs   (12.16 μs .. 12.31 μs)
     46                        1.000 R²   (1.000 R² .. 1.000 R²)
     47   mean                 12.27 μs   (12.22 μs .. 12.32 μs)
     48   std dev              172.4 ns   (131.6 ns .. 246.5 ns)
     49   variance introduced by outliers: 11% (moderately inflated)
     50 ```
     51 
     52 ## Security
     53 
     54 This library aims at the maximum security achievable in a
     55 garbage-collected language under an optimizing compiler such as GHC, in
     56 which strict constant-timeness can be [challenging to achieve][const].
     57 
     58 The HKDF implementation within has been tested against the [Project
     59 Wycheproof vectors][wyche] available for SHA-256 and SHA-512, using
     60 the HMAC functions from [ppad-sha256][sh256] and [ppad-sha512][sh512]
     61 respectively.
     62 
     63 If you discover any vulnerabilities, please disclose them via
     64 security@ppad.tech.
     65 
     66 ## Development
     67 
     68 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     69 development shell with:
     70 
     71 ```
     72 $ nix develop
     73 ```
     74 
     75 Then do e.g.:
     76 
     77 ```
     78 $ cabal repl ppad-hkdf
     79 ```
     80 
     81 to get a REPL for the main library.
     82 
     83 [nixos]: https://nixos.org/
     84 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
     85 [hadoc]: https://docs.ppad.tech/hkdf
     86 [sh256]: https://git.ppad.tech/sha256
     87 [sh512]: https://git.ppad.tech/sha512
     88 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html
     89 [wyche]: https://github.com/C2SP/wycheproof