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

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