ripemd160

Pure Haskell RIPEMD-160, HMAC-RIPEMD160 (docs.ppad.tech/ripemd160).
git clone git://git.ppad.tech/ripemd160.git
Log | Files | Refs | README | LICENSE

README.md (3559B)

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