sha256

Pure Haskell SHA-256, HMAC-SHA256 (docs.ppad.tech/sha256).
git clone git://git.ppad.tech/sha256.git
Log | Files | Refs | README | LICENSE

README.md (4036B)


      1 # sha256
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-sha256?color=blue)](https://hackage.haskell.org/package/ppad-sha256)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-sha256-lightblue)](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 or x86 SHA 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. We avail of hardware
     61 acceleration via the ARM SHA2 extensions on aarch64, and the x86 SHA
     62 extensions on x86_64, whenever the CPU supports them. Current benchmark
     63 figures on an M4 Silicon MacBook Air look like (use `cabal bench` to run
     64 the benchmark suite):
     65 
     66 ```
     67   benchmarking ppad-sha256/SHA256 (32B input)/hash
     68   time                 65.85 ns   (65.76 ns .. 65.95 ns)
     69                        1.000 R²   (1.000 R² .. 1.000 R²)
     70   mean                 65.90 ns   (65.80 ns .. 65.99 ns)
     71   std dev              307.5 ps   (256.0 ps .. 392.9 ps)
     72 
     73   benchmarking ppad-sha256/HMAC-SHA256 (32B input)/hmac
     74   time                 135.7 ns   (135.2 ns .. 136.1 ns)
     75                        1.000 R²   (1.000 R² .. 1.000 R²)
     76   mean                 136.3 ns   (135.9 ns .. 136.7 ns)
     77   std dev              1.298 ns   (1.141 ns .. 1.474 ns)
     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-SHA256 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-sha256
    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/sha256
    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