poly1305

The Poly1305 message authentication code (docs.ppad.tech/poly1305).
git clone git://git.ppad.tech/poly1305.git
Log | Files | Refs | README | LICENSE

README.md (2746B)

      1 # poly1305
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-poly1305?color=blue)](https://hackage.haskell.org/package/ppad-poly1305)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-poly1305-lightblue)](https://docs.ppad.tech/poly1305)
      6 
      7 A pure Haskell implementation of the Poly1305 message authentication
      8 code as specified by [RFC8439][8439].
      9 
     10 ## Usage
     11 
     12 A sample GHCi session:
     13 
     14 ```
     15   > :set -XOverloadedStrings
     16   >
     17   > -- import qualified
     18   > import qualified Crypto.MAC.Poly1305 as Poly1305
     19   >
     20   > -- produce a MAC for a message using a secret one-time key
     21   > let key = "i'll never use this key again!!!"
     22   > let msg = "i am a message that is in need of authentication"
     23   > Poly1305.mac key msg
     24   "\247\247\GSZ^\140\168\r\177\197\242\182b#\210g"
     25 ```
     26 
     27 ## Documentation
     28 
     29 Haddocks (API documentation, etc.) are hosted at
     30 [docs.ppad.tech/poly1305][hadoc].
     31 
     32 ## Performance
     33 
     34 The aim is best-in-class performance for pure, highly-auditable Haskell
     35 code.
     36 
     37 Current benchmark figures on the simple "sunscreen input" from RFC8439
     38 on my mid-2020 MacBook Air look like (use `cabal bench` to run the
     39 benchmark suite):
     40 
     41 ```
     42   benchmarking ppad-poly1305/mac
     43   time                 9.880 μs   (9.596 μs .. 10.11 μs)
     44                        0.995 R²   (0.993 R² .. 0.997 R²)
     45   mean                 9.663 μs   (9.471 μs .. 9.879 μs)
     46   std dev              715.4 ns   (629.7 ns .. 828.0 ns)
     47   variance introduced by outliers: 77% (severely inflated)
     48 ```
     49 
     50 ## Security
     51 
     52 This library aims at the maximum security achievable in a
     53 garbage-collected language under an optimizing compiler such as GHC, in
     54 which strict constant-timeness can be [challenging to achieve][const].
     55 
     56 Note that *at present* we use GHC's native variable-length Integer type
     57 internally, and make no guarantees of constant-time execution.
     58 
     59 The Poly1305 MAC function and its internals pass all official
     60 test vectors in RFC8439, and the downstream AEAD-ChaCha20-Poly1305
     61 implementation in [ppad-aead](https://github.com/ppad-tech/aead) passes
     62 all the [Project Wycheproof vectors][wyche].
     63 
     64 If you discover any vulnerabilities, please disclose them via
     65 security@ppad.tech.
     66 
     67 ## Development
     68 
     69 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     70 development shell with:
     71 
     72 ```
     73 $ nix develop
     74 ```
     75 
     76 Then do e.g.:
     77 
     78 ```
     79 $ cabal repl ppad-poly1305
     80 ```
     81 
     82 to get a REPL for the main library.
     83 
     84 [8439]: https://datatracker.ietf.org/doc/html/rfc8439
     85 [nixos]: https://nixos.org/
     86 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
     87 [hadoc]: https://docs.ppad.tech/poly1305
     88 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html
     89 [wyche]: https://github.com/C2SP/wycheproof