README.md (3973B)
1 # sha256 2 3 [](https://hackage.haskell.org/package/ppad-sha256) 4  5 [](https://docs.ppad.tech/sha256) 6 7 A Haskell implementation of SHA-256 and HMAC-SHA256 on strict and lazy 8 ByteStrings, as specified by RFC's [6234][r6234] and [2104][r2104], that 9 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.SHA256 as SHA256 20 > 21 > -- 'hash' and 'hmac' operate on strict bytestrings 22 > -- 'hmac' returns a value of type 'MAC' with a constant-time Eq instance 23 > 24 > let hash_s = SHA256.hash "strict bytestring input" 25 > let hmac_s = SHA256.hmac "strict secret" "strict bytestring input" 26 > 27 > -- 'hash_lazy' and 'hmac_lazy' operate on lazy bytestrings 28 > -- but note that the key for HMAC is always strict 29 > 30 > let hash_l = SHA256.hash_lazy "lazy bytestring input" 31 > let MAC hmac_l = SHA256.hmac_lazy "strict secret" "lazy bytestring input" 32 > 33 > -- digests are always unformatted 256-bit (32-byte) strict bytestrings 34 > 35 > import qualified Data.ByteString as BS 36 > 37 > BS.take 10 hash_s 38 "1\223\152Ha\USB\171V\a" 39 > BS.take 10 hmac_l 40 "\DELSOk\180\242\182'v\187" 41 > 42 > -- you can use third-party libraries for rendering if needed 43 > -- e.g., using ppad-base16: 44 > 45 > import qualified Data.ByteString.Base16 as B16 46 > 47 > B16.encode hash_s 48 "31df9848611f42ab5607ea9e6de84b05d5259085abb30a7917d85efcda42b0e3" 49 > B16.encode hmac_l 50 "7f534f6bb4f2b62776bba3d6466e384505f2ff89c91f39800d7a0d4623a4711e" 51 ``` 52 53 ## Documentation 54 55 Haddocks (API documentation, etc.) are hosted at 56 [docs.ppad.tech/sha256][hadoc]. 57 58 ## Performance 59 60 The aim is best-in-class performance. Current benchmark figures on an 61 M4 Silicon MacBook Air, where we avail of hardware acceleration via 62 ARM cryptography extensions, look like (use `cabal bench` to run the 63 benchmark suite): 64 65 ``` 66 benchmarking ppad-sha256/SHA256 (32B input)/hash 67 time 48.14 ns (48.12 ns .. 48.18 ns) 68 1.000 R² (1.000 R² .. 1.000 R²) 69 mean 48.17 ns (48.10 ns .. 48.22 ns) 70 std dev 196.5 ps (107.8 ps .. 358.1 ps) 71 72 benchmarking ppad-sha256/HMAC-SHA256 (32B input)/hmac 73 time 193.1 ns (192.9 ns .. 193.5 ns) 74 1.000 R² (1.000 R² .. 1.000 R²) 75 mean 193.4 ns (193.2 ns .. 193.7 ns) 76 std dev 767.2 ps (507.4 ps .. 1.233 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-SHA256 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-sha256 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/sha256 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