README.md (3916B)
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 that uses ARM SHA2 intrinsics when available. 10 11 ## Usage 12 13 A sample GHCi session: 14 15 ``` 16 > :set -XOverloadedStrings 17 > 18 > -- import qualified 19 > import qualified Crypto.Hash.SHA512 as SHA512 20 > 21 > -- 'hash' and 'hmac' operate on strict bytestrings 22 > 23 > let hash_s = SHA512.hash "strict bytestring input" 24 > let hmac_s = SHA512.hmac "strict secret" "strict bytestring input" 25 > 26 > -- 'hash_lazy' and 'hmac_lazy' operate on lazy bytestrings 27 > -- but note that the key for HMAC is always strict 28 > 29 > let hash_l = SHA512.hash_lazy "lazy bytestring input" 30 > let hmac_l = SHA512.hmac_lazy "strict secret" "lazy bytestring input" 31 > 32 > -- results are always unformatted 512-bit (64-byte) strict bytestrings 33 > 34 > import qualified Data.ByteString as BS 35 > 36 > BS.take 10 hash_s 37 "\189D*\v\166\245N\216\&1\243" 38 > BS.take 10 hmac_l 39 "#}9\185\179\233[&\246\205" 40 > 41 > -- you can use third-party libraries for rendering if needed 42 > -- e.g., using base64-bytestring: 43 > 44 > import qualified Data.ByteString.Base64 as B64 45 > 46 > B64.encode (BS.take 16 hash_s) 47 "vUQqC6b1Ttgx8+ydx4MmtQ==" 48 > B64.encode (BS.take 16 hmac_l) 49 "I305ubPpWyb2zUi4pwDkrw==" 50 ``` 51 52 ## Documentation 53 54 Haddocks (API documentation, etc.) are hosted at 55 [docs.ppad.tech/sha512][hadoc]. 56 57 ## Performance 58 59 The aim is best-in-class performance. Current benchmark figures on an 60 M4 Silicon MacBook Air, where we avail of hardware acceleration via 61 ARM cryptography extensions, look like (use `cabal bench` to run the 62 benchmark suite): 63 64 ``` 65 benchmarking ppad-sha512/SHA512 (32B input)/hash 66 time 111.1 ns (110.2 ns .. 111.6 ns) 67 1.000 R² (0.999 R² .. 1.000 R²) 68 mean 108.6 ns (107.8 ns .. 109.5 ns) 69 std dev 2.951 ns (2.637 ns .. 3.334 ns) 70 variance introduced by outliers: 41% (moderately inflated) 71 72 benchmarking ppad-sha512/HMAC-SHA512 (32B input)/hmac 73 time 469.1 ns (468.2 ns .. 470.0 ns) 74 1.000 R² (1.000 R² .. 1.000 R²) 75 mean 468.6 ns (467.7 ns .. 469.3 ns) 76 std dev 2.809 ns (2.317 ns .. 3.492 ns) 77 ``` 78 79 You should compile with the 'llvm' flag for maximum performance. 80 81 ## Security 82 83 This library aims at the maximum security achievable in a 84 garbage-collected language under an optimizing compiler such as GHC, in 85 which strict constant-timeness can be challenging to achieve. 86 87 The HMAC-SHA512 functions within pass all [Wycheproof vectors][wyche], 88 as well as various other useful unit test vectors found around the 89 internet. 90 91 If you discover any vulnerabilities, please disclose them via 92 security@ppad.tech. 93 94 ## Development 95 96 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 97 development shell with: 98 99 ``` 100 $ nix develop 101 ``` 102 103 Then do e.g.: 104 105 ``` 106 $ cabal repl ppad-sha512 107 ``` 108 109 to get a REPL for the main library. 110 111 ## Attribution 112 113 This implementation has benefitted immensely from the [SHA][hacka] 114 package available on Hackage, which was used as a reference during 115 development. Many parts wound up being direct translations. 116 117 [nixos]: https://nixos.org/ 118 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 119 [hadoc]: https://docs.ppad.tech/sha512 120 [hacka]: https://hackage.haskell.org/package/SHA 121 [r6234]: https://datatracker.ietf.org/doc/html/rfc6234 122 [r2104]: https://datatracker.ietf.org/doc/html/rfc2104 123 [noble]: https://github.com/paulmillr/noble-hashes 124 [wyche]: https://github.com/C2SP/wycheproof