README.md (4349B)
1 # poly1305 2 3 [](https://hackage.haskell.org/package/ppad-poly1305) 4  5 [](https://docs.ppad.tech/poly1305) 6 7 A fast 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. Current benchmark figures on the 35 simple "sunscreen input" from RFC8439 on an M4 Silicon MacBook Air, 36 where we avail of hardware acceleration via ARM NEON intrinsics, look 37 like (use `cabal bench` to run the benchmark suite): 38 39 ``` 40 benchmarking ppad-poly1305/mac (big key) 41 time 67.61 ns (67.41 ns .. 67.86 ns) 42 1.000 R² (1.000 R² .. 1.000 R²) 43 mean 67.67 ns (67.50 ns .. 67.96 ns) 44 std dev 742.4 ps (489.7 ps .. 1.169 ns) 45 ``` 46 47 On longer inputs the NEON 4-way parallel kernel kicks in, with 48 correspondingly better throughput: 49 50 ``` 51 benchmarking ppad-poly1305/mac (1024B msg) 52 time 224.9 ns (224.5 ns .. 225.5 ns) 53 1.000 R² (1.000 R² .. 1.000 R²) 54 mean 224.9 ns (224.6 ns .. 225.5 ns) 55 std dev 1.300 ns (577.5 ps .. 2.512 ns) 56 57 benchmarking ppad-poly1305/mac (4096B msg) 58 time 827.1 ns (824.4 ns .. 831.0 ns) 59 1.000 R² (1.000 R² .. 1.000 R²) 60 mean 825.1 ns (824.3 ns .. 826.7 ns) 61 std dev 3.649 ns (2.093 ns .. 6.829 ns) 62 ``` 63 64 You should compile with the 'llvm' flag for maximum performance. 65 66 ## Security 67 68 This library aims at the maximum security achievable in a 69 garbage-collected language under an optimizing compiler such as GHC, in 70 which strict constant-timeness can be [challenging to achieve][const]. 71 72 The Poly1305 MAC function and its internals pass all official 73 test vectors in RFC8439, and the downstream AEAD-ChaCha20-Poly1305 74 implementation in [ppad-aead](https://github.com/ppad-tech/aead) passes 75 all the [Project Wycheproof vectors][wyche]. 76 77 Fixed-width words and constant-time primitives are supplied by 78 [ppad-fixed][fixed]. Criterion benchmarks provide sanity checks of 79 constant-time execution: 80 81 ``` 82 benchmarking ppad-poly1305/mac (small key) 83 time 67.91 ns (67.56 ns .. 68.30 ns) 84 1.000 R² (1.000 R² .. 1.000 R²) 85 mean 67.60 ns (67.47 ns .. 67.77 ns) 86 std dev 505.8 ps (380.4 ps .. 754.9 ps) 87 88 benchmarking ppad-poly1305/mac (mid key) 89 time 67.72 ns (67.52 ns .. 68.03 ns) 90 1.000 R² (0.999 R² .. 1.000 R²) 91 mean 68.07 ns (67.72 ns .. 69.24 ns) 92 std dev 1.978 ns (619.1 ps .. 4.006 ns) 93 94 benchmarking ppad-poly1305/mac (big key) 95 time 67.61 ns (67.41 ns .. 67.86 ns) 96 1.000 R² (1.000 R² .. 1.000 R²) 97 mean 67.67 ns (67.50 ns .. 67.96 ns) 98 std dev 742.4 ps (489.7 ps .. 1.169 ns) 99 ``` 100 101 If you discover any vulnerabilities, please disclose them via 102 security@ppad.tech. 103 104 ## Development 105 106 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 107 development shell with: 108 109 ``` 110 $ nix develop 111 ``` 112 113 Then do e.g.: 114 115 ``` 116 $ cabal repl ppad-poly1305 117 ``` 118 119 to get a REPL for the main library. 120 121 [8439]: https://datatracker.ietf.org/doc/html/rfc8439 122 [nixos]: https://nixos.org/ 123 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 124 [hadoc]: https://docs.ppad.tech/poly1305 125 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html 126 [wyche]: https://github.com/C2SP/wycheproof 127 [fixed]: https://github.com/ppad-tech/fixed