sha512

A pure Haskell implementation of SHA-512 and HMAC-SHA512 on strict and lazy ByteStrings, as specified by RFC's 6234 and 2104, that uses ARM SHA2 or x86 SHA512 intrinsics when available.

Usage

A sample GHCi session:

  > :set -XOverloadedStrings
  >
  > -- import qualified
  > import qualified Crypto.Hash.SHA512 as SHA512
  >
  > -- 'hash' and 'hmac' operate on strict bytestrings
  >
  > let hash_s = SHA512.hash "strict bytestring input"
  > let hmac_s = SHA512.hmac "strict secret" "strict bytestring input"
  >
  > -- 'hash_lazy' and 'hmac_lazy' operate on lazy bytestrings
  > -- but note that the key for HMAC is always strict
  >
  > let hash_l = SHA512.hash_lazy "lazy bytestring input"
  > let hmac_l = SHA512.hmac_lazy "strict secret" "lazy bytestring input"
  >
  > -- results are always unformatted 512-bit (64-byte) strict bytestrings
  >
  > import qualified Data.ByteString as BS
  >
  > BS.take 10 hash_s
  "\189D*\v\166\245N\216\&1\243"
  > BS.take 10 hmac_l
  "#}9\185\179\233[&\246\205"
  >
  > -- you can use third-party libraries for rendering if needed
  > -- e.g., using base64-bytestring:
  >
  > import qualified Data.ByteString.Base64 as B64
  >
  > B64.encode (BS.take 16 hash_s)
  "vUQqC6b1Ttgx8+ydx4MmtQ=="
  > B64.encode (BS.take 16 hmac_l)
  "I305ubPpWyb2zUi4pwDkrw=="

Documentation

Haddocks (API documentation, etc.) are hosted at docs.ppad.tech/sha512.

Performance

The aim is best-in-class performance. We avail of hardware acceleration via the ARM SHA512 extensions on aarch64, and the x86 SHA512 extensions on x86_64, whenever the CPU supports them. Current benchmark figures on an M4 Silicon MacBook Air look like (use cabal bench to run the benchmark suite):

  benchmarking ppad-sha512/SHA512 (32B input)/hash
  time                 129.7 ns   (129.1 ns .. 130.3 ns)
                       1.000 R²   (1.000 R² .. 1.000 R²)
  mean                 130.1 ns   (129.9 ns .. 130.3 ns)
  std dev              668.1 ps   (432.4 ps .. 974.3 ps)

  benchmarking ppad-sha512/HMAC-SHA512 (32B input)/hmac
  time                 359.6 ns   (356.2 ns .. 365.1 ns)
                       0.998 R²   (0.994 R² .. 1.000 R²)
  mean                 360.3 ns   (356.3 ns .. 371.5 ns)
  std dev              18.82 ns   (2.196 ns .. 34.70 ns)
  variance introduced by outliers: 70% (severely inflated)

You should compile with the 'llvm' flag for maximum performance.

Security

The security properties of this library have been examined and defended in a security analysis at ppad.tech.

The HMAC-SHA512 functions within pass all Wycheproof vectors, as well as various other useful unit test vectors found around the internet.

If you discover any vulnerabilities, please disclose them via security@ppad.tech.

Development

You'll require Nix with flake support enabled. Enter a development shell with:

$ nix develop

Then do e.g.:

$ cabal repl ppad-sha512

to get a REPL for the main library.

Attribution

This implementation has benefitted immensely from the SHA package available on Hackage, which was used as a reference during development. Many parts wound up being direct translations.