sha512

Pure Haskell SHA-512, HMAC-SHA512 (docs.ppad.tech/sha512).
git clone git://git.ppad.tech/sha512.git
Log | Files | Refs | README | LICENSE

README.md (4845B)


      1 # sha512
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-sha512?color=blue)](https://hackage.haskell.org/package/ppad-sha512)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-sha512-lightblue)](https://docs.ppad.tech/sha512)
      6 
      7 A pure Haskell implementation of SHA-512 and HMAC-SHA512 on strict and
      8 lazy ByteStrings, as specified by RFC's [6234][r6234] and [2104][r2104].
      9 
     10 ## Usage
     11 
     12 A sample GHCi session:
     13 
     14 ```
     15   > :set -XOverloadedStrings
     16   >
     17   > -- import qualified
     18   > import qualified Crypto.Hash.SHA512 as SHA512
     19   >
     20   > -- 'hash' and 'hmac' operate on strict bytestrings
     21   >
     22   > let hash_s = SHA512.hash "strict bytestring input"
     23   > let hmac_s = SHA512.hmac "strict secret" "strict bytestring input"
     24   >
     25   > -- 'hash_lazy' and 'hmac_lazy' operate on lazy bytestrings
     26   > -- but note that the key for HMAC is always strict
     27   >
     28   > let hash_l = SHA512.hash_lazy "lazy bytestring input"
     29   > let hmac_l = SHA512.hmac_lazy "strict secret" "lazy bytestring input"
     30   >
     31   > -- results are always unformatted 512-bit (64-byte) strict bytestrings
     32   >
     33   > import qualified Data.ByteString as BS
     34   >
     35   > BS.take 10 hash_s
     36   "\189D*\v\166\245N\216\&1\243"
     37   > BS.take 10 hmac_l
     38   "#}9\185\179\233[&\246\205"
     39   >
     40   > -- you can use third-party libraries for rendering if needed
     41   > -- e.g., using base64-bytestring:
     42   >
     43   > import qualified Data.ByteString.Base64 as B64
     44   >
     45   > B64.encode (BS.take 16 hash_s)
     46   "vUQqC6b1Ttgx8+ydx4MmtQ=="
     47   > B64.encode (BS.take 16 hmac_l)
     48   "I305ubPpWyb2zUi4pwDkrw=="
     49 ```
     50 
     51 ## Documentation
     52 
     53 Haddocks (API documentation, etc.) are hosted at
     54 [docs.ppad.tech/sha512][hadoc].
     55 
     56 ## Performance
     57 
     58 The aim is best-in-class performance for pure, highly-auditable Haskell
     59 code.
     60 
     61 Current benchmark figures on my mid-2020 MacBook Air look like (use
     62 `cabal bench` to run the benchmark suite):
     63 
     64 ```
     65   benchmarking ppad-sha512/SHA512 (32B input)/hash
     66   time                 1.116 μs   (1.103 μs .. 1.130 μs)
     67                        0.999 R²   (0.999 R² .. 0.999 R²)
     68   mean                 1.142 μs   (1.132 μs .. 1.154 μs)
     69   std dev              37.35 ns   (30.15 ns .. 49.36 ns)
     70   variance introduced by outliers: 45% (moderately inflated)
     71 
     72   benchmarking ppad-sha512/HMAC-SHA512 (32B input)/hmac
     73   time                 4.943 μs   (4.823 μs .. 5.086 μs)
     74                        0.997 R²   (0.994 R² .. 1.000 R²)
     75   mean                 4.878 μs   (4.838 μs .. 4.946 μs)
     76   std dev              180.9 ns   (105.1 ns .. 337.4 ns)
     77   variance introduced by outliers: 48% (moderately inflated)
     78 ```
     79 
     80 Compare this to Hackage's famous SHA package:
     81 
     82 ```
     83   benchmarking ppad-sha512/SHA512 (32B input)/SHA.sha512
     84   time                 2.371 μs   (2.350 μs .. 2.401 μs)
     85                        0.999 R²   (0.999 R² .. 1.000 R²)
     86   mean                 2.422 μs   (2.403 μs .. 2.443 μs)
     87   std dev              69.84 ns   (51.04 ns .. 114.0 ns)
     88   variance introduced by outliers: 37% (moderately inflated)
     89 
     90   benchmarking ppad-sha512/HMAC-SHA512 (32B input)/SHA.hmacSha512
     91   time                 8.832 μs   (8.714 μs .. 8.976 μs)
     92                        0.999 R²   (0.998 R² .. 1.000 R²)
     93   mean                 8.911 μs   (8.834 μs .. 9.006 μs)
     94   std dev              278.9 ns   (215.8 ns .. 365.1 ns)
     95   variance introduced by outliers: 37% (moderately inflated)
     96 ```
     97 
     98 Or the relevant SHA-512-based functions from a library with similar
     99 aims, [noble-hashes][noble] (though with no HMAC-SHA512 benchmark
    100 available):
    101 
    102 ```
    103 SHA512 32B x 217,296 ops/sec @ 4μs/op ± 2.00% (min: 3μs, max: 20ms)
    104 ```
    105 
    106 ## Security
    107 
    108 This library aims at the maximum security achievable in a
    109 garbage-collected language under an optimizing compiler such as GHC, in
    110 which strict constant-timeness can be challenging to achieve.
    111 
    112 The HMAC-SHA512 functions within pass all [Wycheproof vectors][wyche],
    113 as well as various other useful unit test vectors found around the
    114 internet.
    115 
    116 If you discover any vulnerabilities, please disclose them via
    117 security@ppad.tech.
    118 
    119 ## Development
    120 
    121 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
    122 development shell with:
    123 
    124 ```
    125 $ nix develop
    126 ```
    127 
    128 Then do e.g.:
    129 
    130 ```
    131 $ cabal repl ppad-sha512
    132 ```
    133 
    134 to get a REPL for the main library.
    135 
    136 ## Attribution
    137 
    138 This implementation has benefitted immensely from the [SHA][hacka]
    139 package available on Hackage, which was used as a reference during
    140 development. Many parts wound up being direct translations.
    141 
    142 [nixos]: https://nixos.org/
    143 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
    144 [hadoc]: https://docs.ppad.tech/sha512
    145 [hacka]: https://hackage.haskell.org/package/SHA
    146 [r6234]: https://datatracker.ietf.org/doc/html/rfc6234
    147 [r2104]: https://datatracker.ietf.org/doc/html/rfc2104
    148 [noble]: https://github.com/paulmillr/noble-hashes
    149 [wyche]: https://github.com/C2SP/wycheproof