README.md (3985B)
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 or x86 SHA512 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. We avail of hardware 60 acceleration via the ARM SHA512 extensions on aarch64, and the x86 61 SHA512 extensions on x86_64, whenever the CPU supports them. Current 62 benchmark figures on an M4 Silicon MacBook Air look like (use `cabal 63 bench` to run the benchmark suite): 64 65 ``` 66 benchmarking ppad-sha512/SHA512 (32B input)/hash 67 time 129.7 ns (129.1 ns .. 130.3 ns) 68 1.000 R² (1.000 R² .. 1.000 R²) 69 mean 130.1 ns (129.9 ns .. 130.3 ns) 70 std dev 668.1 ps (432.4 ps .. 974.3 ps) 71 72 benchmarking ppad-sha512/HMAC-SHA512 (32B input)/hmac 73 time 359.6 ns (356.2 ns .. 365.1 ns) 74 0.998 R² (0.994 R² .. 1.000 R²) 75 mean 360.3 ns (356.3 ns .. 371.5 ns) 76 std dev 18.82 ns (2.196 ns .. 34.70 ns) 77 variance introduced by outliers: 70% (severely inflated) 78 ``` 79 80 You should compile with the 'llvm' flag for maximum performance. 81 82 ## Security 83 84 The security properties of this library have been examined and defended in 85 a [security analysis](https://ppad.tech/security-analysis-sha2) at 86 [ppad.tech](https://ppad.tech). 87 88 The HMAC-SHA512 functions within pass all [Wycheproof vectors][wyche], 89 as well as various other useful unit test vectors found around the 90 internet. 91 92 If you discover any vulnerabilities, please disclose them via 93 security@ppad.tech. 94 95 ## Development 96 97 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 98 development shell with: 99 100 ``` 101 $ nix develop 102 ``` 103 104 Then do e.g.: 105 106 ``` 107 $ cabal repl ppad-sha512 108 ``` 109 110 to get a REPL for the main library. 111 112 ## Attribution 113 114 This implementation has benefitted immensely from the [SHA][hacka] 115 package available on Hackage, which was used as a reference during 116 development. Many parts wound up being direct translations. 117 118 [nixos]: https://nixos.org/ 119 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 120 [hadoc]: https://docs.ppad.tech/sha512 121 [hacka]: https://hackage.haskell.org/package/SHA 122 [r6234]: https://datatracker.ietf.org/doc/html/rfc6234 123 [r2104]: https://datatracker.ietf.org/doc/html/rfc2104 124 [noble]: https://github.com/paulmillr/noble-hashes 125 [wyche]: https://github.com/C2SP/wycheproof