hmac-drbg

Pure Haskell HMAC-DRBG (docs.ppad.tech/hmac-drbg).
git clone git://git.ppad.tech/hmac-drbg.git
Log | Files | Refs | README | LICENSE

README.md (4716B)

      1 # hmac-drbg
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-hmac-drbg?color=blue)](https://hackage.haskell.org/package/ppad-hmac-drbg)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-hmac-drbg-lightblue)](https://docs.ppad.tech/hmac-drbg)
      6 
      7 A pure Haskell implementation of the HMAC-DRBG cryptographically-secure PRNG,
      8 as specified by [NIST SP 800-90A][sp800].
      9 
     10 ## Usage
     11 
     12 A sample GHCi session:
     13 
     14 ```
     15   > -- extensions/b16 import just for illustration here; not required for use
     16   > :set -XOverloadedStrings
     17   > :set -XRankNTypes
     18   > import qualified Data.ByteString.Base16 as B16
     19   >
     20   > -- import qualified
     21   > import qualified Crypto.DRBG.HMAC as DRBG
     22   >
     23   > -- supply your own HMAC function
     24   > import qualified Crypto.Hash.SHA256 as SHA256
     25   >
     26   > -- instantiate a DRBG
     27   > let entropy = "very random"
     28   > let nonce = "very unused"
     29   > let personalization_string = "very personal"
     30   >
     31   > drbg <- DRBG.new SHA256.hmac entropy nonce personalization_string
     32   >
     33   > -- use it to generate some bytes
     34   >
     35   > fmap B16.encode (DRBG.gen mempty 32 drbg)
     36   "e4d17210810c4b343f6eae2c19e3d82395b555294b1b16a85f91dbea67e5f277"
     37   >
     38   > -- reuse the generator to get more; the state is updated automatically
     39   >
     40   > fmap B16.encode (DRBG.gen mempty 16 drbg)
     41   "5d867730d99eb5335f16b1d622f03023"
     42   >
     43   > -- this DRBG was instantiated in the IO monad:
     44   >
     45   > :t drbg
     46   drbg :: DRBG.DRBG ghc-prim:GHC.Prim.RealWorld
     47   >
     48   > -- but you can also use use ST to keep things pure:
     49   >
     50   > import Control.Monad.ST
     51   >
     52   > :{
     53   ghci| let drbg_pure = DRBG.new SHA256.hmac mempty mempty mempty ::
     54   ghci|                   forall s. ST s (DRBG.DRBG s)
     55   ghci| :}
     56   >
     57   > :t drbg_pure
     58   drbg_pure :: ST s (DRBG.DRBG s)
     59   >
     60   > runST $ drbg_pure >>= fmap B16.encode . DRBG.gen mempty 16
     61   "b44299907e4e42aa4fded5d6153e8bac"
     62 ```
     63 
     64 ## Documentation
     65 
     66 Haddocks (API documentation, etc.) are hosted at
     67 [docs.ppad.tech/hmac-drbg][hadoc].
     68 
     69 ## Performance
     70 
     71 The aim is best-in-class performance for pure, highly-auditable Haskell
     72 code.
     73 
     74 Current benchmark figures on my mid-2020 MacBook Air look like (use
     75 `cabal bench` to run the benchmark suite):
     76 
     77 ```
     78   benchmarking ppad-hmac-drbg/HMAC-SHA256/new
     79   time                 20.86 μs   (20.78 μs .. 20.94 μs)
     80                        1.000 R²   (1.000 R² .. 1.000 R²)
     81   mean                 20.82 μs   (20.72 μs .. 20.93 μs)
     82   std dev              370.6 ns   (299.3 ns .. 456.6 ns)
     83   variance introduced by outliers: 15% (moderately inflated)
     84 
     85   benchmarking ppad-hmac-drbg/HMAC-SHA256/reseed
     86   time                 13.98 μs   (13.83 μs .. 14.18 μs)
     87                        0.999 R²   (0.998 R² .. 1.000 R²)
     88   mean                 13.89 μs   (13.79 μs .. 14.03 μs)
     89   std dev              398.9 ns   (296.7 ns .. 580.8 ns)
     90   variance introduced by outliers: 32% (moderately inflated)
     91 
     92   benchmarking ppad-hmac-drbg/HMAC-SHA256/gen (32B)
     93   time                 21.10 μs   (20.95 μs .. 21.25 μs)
     94                        1.000 R²   (0.999 R² .. 1.000 R²)
     95   mean                 21.19 μs   (21.06 μs .. 21.36 μs)
     96   std dev              509.2 ns   (390.7 ns .. 812.2 ns)
     97   variance introduced by outliers: 24% (moderately inflated)
     98 
     99   benchmarking ppad-hmac-drbg/HMAC-SHA256/gen (256B)
    100   time                 68.17 μs   (67.62 μs .. 68.82 μs)
    101                        1.000 R²   (0.999 R² .. 1.000 R²)
    102   mean                 68.74 μs   (68.42 μs .. 69.09 μs)
    103   std dev              1.172 μs   (1.022 μs .. 1.410 μs)
    104   variance introduced by outliers: 12% (moderately inflated)
    105 ```
    106 
    107 ## Security
    108 
    109 This library aims at the maximum security achievable in a
    110 garbage-collected language under an optimizing compiler such as GHC, in
    111 which strict constant-timeness can be [challenging to achieve][const].
    112 
    113 The HMAC-DRBG implementation within has been tested against the
    114 NIST DRBGVS vectors available for SHA-256 and SHA-512, using the
    115 HMAC functions from [ppad-sha256][sh256] and [ppad-sha512][sh512]
    116 respectively.
    117 
    118 If you discover any vulnerabilities, please disclose them via
    119 security@ppad.tech.
    120 
    121 ## Development
    122 
    123 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
    124 development shell with:
    125 
    126 ```
    127 $ nix develop
    128 ```
    129 
    130 Then do e.g.:
    131 
    132 ```
    133 $ cabal repl ppad-hmac-drbg
    134 ```
    135 
    136 to get a REPL for the main library.
    137 
    138 [sp800]: https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf
    139 [nixos]: https://nixos.org/
    140 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
    141 [hadoc]: https://docs.ppad.tech/hmac-drbg
    142 [sh256]: https://git.ppad.tech/sha256
    143 [sh512]: https://git.ppad.tech/sha512
    144 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html