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