README.md (3461B)
1 # ripemd160 2 3 [](https://hackage.haskell.org/package/ppad-ripemd160) 4  5 6 A pure Haskell implementation of [RIPEMD-160][ripem] and HMAC-RIPEMD160 7 on strict and lazy ByteStrings. 8 9 ## Usage 10 11 A sample GHCi session: 12 13 ``` 14 > :set -XOverloadedStrings 15 > 16 > -- import qualified 17 > import qualified Crypto.Hash.RIPEMD160 as RIPEMD160 18 > 19 > -- 'hash' and 'hmac' operate on strict bytestrings 20 > 21 > let hash_s = RIPEMD160.hash "strict bytestring input" 22 > let hmac_s = RIPEMD160.hmac "strict secret" "strict bytestring input" 23 > 24 > -- 'hash_lazy' and 'hmac_lazy' operate on lazy bytestrings 25 > -- but note that the key for HMAC is always strict 26 > 27 > let hash_l = RIPEMD160.hash_lazy "lazy bytestring input" 28 > let hmac_l = RIPEMD160.hmac_lazy "strict secret" "lazy bytestring input" 29 > 30 > -- results are always unformatted 160-bit (20-byte) strict bytestrings 31 > 32 > import qualified Data.ByteString as BS 33 > 34 > BS.take 10 hash_s 35 "=\211\211\197]\NULJ\223n\223" 36 > BS.take 10 hmac_l 37 "\154\248\145[\196\ETX\f\ESC\NULs" 38 > 39 > -- you can use third-party libraries for rendering if needed 40 > -- e.g., using ppad-base16: 41 > 42 > import qualified Data.ByteString.Base16 as B16 43 > 44 > B16.encode hash_s 45 "3dd3d3c55d004adf6edf9e11cb01f9ac9c56441f" 46 > B16.encode hmac_l 47 "9af8915bc4030c1b007323c8531b3129d82f50bd" 48 ``` 49 50 ## Documentation 51 52 Haddocks (API documentation, etc.) are hosted at 53 [docs.ppad.tech/ripemd160][hadoc]. 54 55 ## Performance 56 57 The aim is best-in-class performance for pure, highly-auditable Haskell 58 code. 59 60 Current benchmark figures on my mid-2020 MacBook Air look like (use 61 `cabal bench` to run the benchmark suite): 62 63 ``` 64 benchmarking ppad-ripemd160/RIPEMD160 (32B input)/hash 65 time 786.6 ns (778.0 ns .. 796.7 ns) 66 0.999 R² (0.999 R² .. 1.000 R²) 67 mean 778.6 ns (775.3 ns .. 784.2 ns) 68 std dev 13.85 ns (9.858 ns .. 22.05 ns) 69 variance introduced by outliers: 20% (moderately inflated) 70 71 benchmarking ppad-ripemd160/HMAC-RIPEMD160 (32B input)/hmac 72 time 2.933 μs (2.906 μs .. 2.974 μs) 73 0.999 R² (0.999 R² .. 0.999 R²) 74 mean 3.002 μs (2.978 μs .. 3.022 μs) 75 std dev 74.97 ns (62.74 ns .. 89.91 ns) 76 variance introduced by outliers: 30% (moderately inflated) 77 ``` 78 79 ## Security 80 81 This library aims at the maximum security achievable in a 82 garbage-collected language under an optimizing compiler such as GHC, in 83 which strict constant-timeness can be challenging to achieve. 84 85 The RIPEMD-160 functions pass the vectors present in the [official 86 spec][ripem], and the HMAC-RIPEMD160 functions pass all vectors found 87 contained in [RFC2286][rfc22]. 88 89 If you discover any vulnerabilities, please disclose them via 90 security@ppad.tech. 91 92 ## Development 93 94 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 95 development shell with: 96 97 ``` 98 $ nix develop 99 ``` 100 101 Then do e.g.: 102 103 ``` 104 $ cabal repl ppad-ripemd160 105 ``` 106 107 to get a REPL for the main library. 108 109 [nixos]: https://nixos.org/ 110 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 111 [hadoc]: https://docs.ppad.tech/ripemd160 112 [ripem]: https://homes.esat.kuleuven.be/~bosselae/ripemd160/pdf/AB-9601/AB-9601.pdf 113 [rfc22]: https://www.rfc-editor.org/rfc/rfc2286.html#section-2