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 (2893B)

      1 # hkdf
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-hkdf?color=blue)](https://hackage.haskell.org/package/ppad-hkdf)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-hkdf-lightblue)](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   > Just (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 an M4 Silicon 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                 1.549 μs   (1.547 μs .. 1.553 μs)
     43                        1.000 R²   (1.000 R² .. 1.000 R²)
     44   mean                 1.565 μs   (1.560 μs .. 1.572 μs)
     45   std dev              20.80 ns   (18.40 ns .. 24.68 ns)
     46   variance introduced by outliers: 12% (moderately inflated)
     47 
     48   benchmarking ppad-hkdf/HKDF-SHA512/derive (outlen 32)
     49   time                 2.089 μs   (2.088 μs .. 2.090 μs)
     50                        1.000 R²   (1.000 R² .. 1.000 R²)
     51   mean                 2.090 μs   (2.088 μs .. 2.092 μs)
     52   std dev              5.637 ns   (3.965 ns .. 8.886 ns)
     53 ```
     54 
     55 ## Security
     56 
     57 This library aims at the maximum security achievable in a
     58 garbage-collected language under an optimizing compiler such as GHC, in
     59 which strict constant-timeness can be [challenging to achieve][const].
     60 
     61 The HKDF implementation within has been tested against the [Project
     62 Wycheproof vectors][wyche] available for SHA-256 and SHA-512, using
     63 the HMAC functions from [ppad-sha256][sh256] and [ppad-sha512][sh512]
     64 respectively.
     65 
     66 If you discover any vulnerabilities, please disclose them via
     67 security@ppad.tech.
     68 
     69 ## Development
     70 
     71 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     72 development shell with:
     73 
     74 ```
     75 $ nix develop
     76 ```
     77 
     78 Then do e.g.:
     79 
     80 ```
     81 $ cabal repl ppad-hkdf
     82 ```
     83 
     84 to get a REPL for the main library.
     85 
     86 [nixos]: https://nixos.org/
     87 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
     88 [hadoc]: https://docs.ppad.tech/hkdf
     89 [sh256]: https://git.ppad.tech/sha256
     90 [sh512]: https://git.ppad.tech/sha512
     91 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html
     92 [wyche]: https://github.com/C2SP/wycheproof