README.md (3640B)
1 # poly1305 2 3 [](https://hackage.haskell.org/package/ppad-poly1305) 4  5 [](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 Just "\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 Haskell code. 35 36 Current benchmark figures on the simple "sunscreen input" from RFC8439 37 on an M4 Silicon MacBook Air look like (use `cabal bench` to run the 38 benchmark suite): 39 40 ``` 41 benchmarking ppad-poly1305/mac (big key) 42 time 125.1 ns (124.9 ns .. 125.4 ns) 43 1.000 R² (1.000 R² .. 1.000 R²) 44 mean 125.4 ns (125.0 ns .. 126.2 ns) 45 std dev 1.530 ns (216.3 ps .. 2.693 ns) 46 ``` 47 48 ## Security 49 50 This library aims at the maximum security achievable in a 51 garbage-collected language under an optimizing compiler such as GHC, in 52 which strict constant-timeness can be [challenging to achieve][const]. 53 54 The Poly1305 MAC function and its internals pass all official 55 test vectors in RFC8439, and the downstream AEAD-ChaCha20-Poly1305 56 implementation in [ppad-aead](https://github.com/ppad-tech/aead) passes 57 all the [Project Wycheproof vectors][wyche]. 58 59 Fixed-width words and constant-time primitives are supplied by 60 [ppad-fixed][fixed]. Criterion benchmarks provide sanity checks of 61 constant-time execution: 62 63 ``` 64 benchmarking ppad-poly1305/mac (small key) 65 time 125.1 ns (124.9 ns .. 125.4 ns) 66 1.000 R² (1.000 R² .. 1.000 R²) 67 mean 125.1 ns (125.0 ns .. 125.4 ns) 68 std dev 524.6 ps (180.6 ps .. 1.132 ns) 69 70 benchmarking ppad-poly1305/mac (mid key) 71 time 125.2 ns (124.9 ns .. 125.4 ns) 72 1.000 R² (1.000 R² .. 1.000 R²) 73 mean 125.1 ns (125.1 ns .. 125.3 ns) 74 std dev 441.3 ps (195.0 ps .. 755.1 ps) 75 76 benchmarking ppad-poly1305/mac (big key) 77 time 125.1 ns (124.9 ns .. 125.4 ns) 78 1.000 R² (1.000 R² .. 1.000 R²) 79 mean 125.4 ns (125.0 ns .. 126.2 ns) 80 std dev 1.530 ns (216.3 ps .. 2.693 ns) 81 variance introduced by outliers: 12% (moderately inflated) 82 ``` 83 84 If you discover any vulnerabilities, please disclose them via 85 security@ppad.tech. 86 87 ## Development 88 89 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 90 development shell with: 91 92 ``` 93 $ nix develop 94 ``` 95 96 Then do e.g.: 97 98 ``` 99 $ cabal repl ppad-poly1305 100 ``` 101 102 to get a REPL for the main library. 103 104 [8439]: https://datatracker.ietf.org/doc/html/rfc8439 105 [nixos]: https://nixos.org/ 106 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 107 [hadoc]: https://docs.ppad.tech/poly1305 108 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html 109 [wyche]: https://github.com/C2SP/wycheproof 110 [fixed]: https://github.com/ppad-tech/fixed