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

      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 an M4 Silicon 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                 957.1 ns   (956.3 ns .. 957.7 ns)
     67                        1.000 R²   (1.000 R² .. 1.000 R²)
     68   mean                 956.1 ns   (955.6 ns .. 956.6 ns)
     69   std dev              1.714 ns   (1.436 ns .. 2.174 ns)
     70 
     71   benchmarking ppad-sha512/HMAC-SHA512 (32B input)/hmac
     72   time                 3.460 μs   (3.448 μs .. 3.475 μs)
     73                        1.000 R²   (1.000 R² .. 1.000 R²)
     74   mean                 3.474 μs   (3.468 μs .. 3.478 μs)
     75   std dev              16.60 ns   (11.71 ns .. 24.66 ns)
     76 ```
     77 
     78 Compare this to Hackage's venerable SHA package:
     79 
     80 ```
     81   benchmarking ppad-sha512/SHA512 (32B input)/SHA.sha512
     82   time                 1.437 μs   (1.436 μs .. 1.437 μs)
     83                        1.000 R²   (1.000 R² .. 1.000 R²)
     84   mean                 1.440 μs   (1.435 μs .. 1.452 μs)
     85   std dev              23.57 ns   (11.13 ns .. 43.08 ns)
     86 
     87   benchmarking ppad-sha512/HMAC-SHA512 (32B input)/SHA.hmacSha512
     88   time                 5.164 μs   (5.162 μs .. 5.166 μs)
     89                        1.000 R²   (1.000 R² .. 1.000 R²)
     90   mean                 5.159 μs   (5.157 μs .. 5.161 μs)
     91   std dev              6.522 ns   (5.534 ns .. 7.662 ns)
     92 ```
     93 
     94 ## Security
     95 
     96 This library aims at the maximum security achievable in a
     97 garbage-collected language under an optimizing compiler such as GHC, in
     98 which strict constant-timeness can be challenging to achieve.
     99 
    100 The HMAC-SHA512 functions within pass all [Wycheproof vectors][wyche],
    101 as well as various other useful unit test vectors found around the
    102 internet.
    103 
    104 If you discover any vulnerabilities, please disclose them via
    105 security@ppad.tech.
    106 
    107 ## Development
    108 
    109 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
    110 development shell with:
    111 
    112 ```
    113 $ nix develop
    114 ```
    115 
    116 Then do e.g.:
    117 
    118 ```
    119 $ cabal repl ppad-sha512
    120 ```
    121 
    122 to get a REPL for the main library.
    123 
    124 ## Attribution
    125 
    126 This implementation has benefitted immensely from the [SHA][hacka]
    127 package available on Hackage, which was used as a reference during
    128 development. Many parts wound up being direct translations.
    129 
    130 [nixos]: https://nixos.org/
    131 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
    132 [hadoc]: https://docs.ppad.tech/sha512
    133 [hacka]: https://hackage.haskell.org/package/SHA
    134 [r6234]: https://datatracker.ietf.org/doc/html/rfc6234
    135 [r2104]: https://datatracker.ietf.org/doc/html/rfc2104
    136 [noble]: https://github.com/paulmillr/noble-hashes
    137 [wyche]: https://github.com/C2SP/wycheproof