README.md (3657B)
1 # aead 2 3 [](https://hackage.haskell.org/package/ppad-aead) 4  5 [](https://docs.ppad.tech/aead) 6 7 A pure Haskell implementation of authenticated encryption with 8 associated data (AEAD) using the ChaCha20-Poly1305 configuration, as 9 specified by [RFC8439][8439]. 10 11 ## Usage 12 13 A sample GHCi session: 14 15 ``` 16 > :set -XOverloadedStrings 17 > import qualified Data.ByteString.Base16 as B16 -- just for illustration 18 > 19 > -- import qualified 20 > import qualified Crypto.AEAD.ChaCha20Poly1305 as AEAD 21 > 22 > -- encrypt plaintext with some additional authenticated data, using 23 > -- a secret key and nonce 24 > let key = "don't tell anyone my secret key!" 25 > let non = "or my nonce!" 26 > let msg = "this is my secret message" 27 > let aad = "and i approve it" 28 > 29 > -- encryption produces a 128-bit MAC 30 > let Right (cip, mac) = AEAD.encrypt aad key non msg 31 > B16.encode cip 32 "d6377eab18cad56e8c6176968460e6a548c524b9498c9b993e" 33 > B16.encode mac 34 "48751cc57cf5123bc841239c7d563da0" 35 > 36 > -- supply both to decrypt 37 > AEAD.decrypt aad key non (cip, tag) 38 Right "this is my secret message" 39 > 40 > -- bogus MACs will cause decryption to fail 41 > AEAD.decrypt aad key non (cip, "really i swear!!") 42 Left InvalidMAC 43 ``` 44 45 ## Documentation 46 47 Haddocks (API documentation, etc.) are hosted at 48 [docs.ppad.tech/aead][hadoc]. 49 50 ## Performance 51 52 The aim is best-in-class performance for pure, highly-auditable Haskell 53 code. 54 55 Current benchmark figures on a simple input from the RFC8439 appendices 56 on an M4 Silicon MacBook Air look like (use `cabal bench` to run the 57 benchmark suite): 58 59 ``` 60 benchmarking ppad-aead/encrypt 61 time 10.03 μs (10.02 μs .. 10.03 μs) 62 1.000 R² (1.000 R² .. 1.000 R²) 63 mean 10.04 μs (10.04 μs .. 10.05 μs) 64 std dev 9.024 ns (7.330 ns .. 11.99 ns) 65 66 benchmarking ppad-aead/decrypt 67 time 10.06 μs (10.05 μs .. 10.07 μs) 68 1.000 R² (1.000 R² .. 1.000 R²) 69 mean 10.07 μs (10.06 μs .. 10.08 μs) 70 std dev 26.50 ns (21.66 ns .. 32.02 ns) 71 ``` 72 73 ## Security 74 75 This library aims at the maximum security achievable in a 76 garbage-collected language under an optimizing compiler such as GHC, in 77 which strict constant-timeness can be [challenging to achieve][const]. 78 79 Note that *at present* we use GHC's native variable-length Integer 80 type internally (relevant to Poly1305 MAC handling), and make no "hard" 81 guarantees of constant-time execution. 82 83 The AEAD-ChaCha20-Poly1305 implementation within passes all 84 test vectors from RFC8439, as well as the available [Project 85 Wycheproof vectors][wyche], using the ChaCha20 cipher from 86 [ppad-chacha](https://github.com/ppad-tech/chacha) and the Poly1305 87 MAC from [ppad-poly1305](https://github.com/ppad-tech/poly1305), 88 respectively. 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-aead 106 ``` 107 108 to get a REPL for the main library. 109 110 [8439]: https://datatracker.ietf.org/doc/html/rfc8439 111 [nixos]: https://nixos.org/ 112 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 113 [hadoc]: https://docs.ppad.tech/aead 114 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html 115 [wyche]: https://github.com/C2SP/wycheproof