README.md (3782B)
1 # sha512 2 3 [](https://hackage.haskell.org/package/ppad-sha512) 4  5 [](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 419.3 ns (419.1 ns .. 419.7 ns) 67 1.000 R² (1.000 R² .. 1.000 R²) 68 mean 420.4 ns (420.1 ns .. 421.1 ns) 69 std dev 1.507 ns (843.5 ps .. 2.705 ns) 70 71 benchmarking ppad-sha512/HMAC-SHA512 (32B input)/hmac 72 time 1.340 μs (1.339 μs .. 1.341 μs) 73 1.000 R² (1.000 R² .. 1.000 R²) 74 mean 1.343 μs (1.342 μs .. 1.347 μs) 75 std dev 8.443 ns (3.955 ns .. 14.85 ns) 76 ``` 77 78 You should compile with the 'llvm' flag for maximum performance. 79 80 ## Security 81 82 This library aims at the maximum security achievable in a 83 garbage-collected language under an optimizing compiler such as GHC, in 84 which strict constant-timeness can be challenging to achieve. 85 86 The HMAC-SHA512 functions within pass all [Wycheproof vectors][wyche], 87 as well as various other useful unit test vectors found around the 88 internet. 89 90 If you discover any vulnerabilities, please disclose them via 91 security@ppad.tech. 92 93 ## Development 94 95 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 96 development shell with: 97 98 ``` 99 $ nix develop 100 ``` 101 102 Then do e.g.: 103 104 ``` 105 $ cabal repl ppad-sha512 106 ``` 107 108 to get a REPL for the main library. 109 110 ## Attribution 111 112 This implementation has benefitted immensely from the [SHA][hacka] 113 package available on Hackage, which was used as a reference during 114 development. Many parts wound up being direct translations. 115 116 [nixos]: https://nixos.org/ 117 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 118 [hadoc]: https://docs.ppad.tech/sha512 119 [hacka]: https://hackage.haskell.org/package/SHA 120 [r6234]: https://datatracker.ietf.org/doc/html/rfc6234 121 [r2104]: https://datatracker.ietf.org/doc/html/rfc2104 122 [noble]: https://github.com/paulmillr/noble-hashes 123 [wyche]: https://github.com/C2SP/wycheproof