README.md (3764B)
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 (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 Just "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 Nothing 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 my mid-2020 MacBook Air look like (use `cabal bench` to run the 57 benchmark suite): 58 59 ``` 60 benchmarking ppad-aead/encrypt 61 time 23.27 μs (22.45 μs .. 24.06 μs) 62 0.993 R² (0.989 R² .. 0.996 R²) 63 mean 22.67 μs (22.17 μs .. 23.21 μs) 64 std dev 1.795 μs (1.486 μs .. 2.180 μs) 65 variance introduced by outliers: 78% (severely inflated) 66 67 benchmarking ppad-aead/decrypt 68 time 25.92 μs (25.15 μs .. 26.64 μs) 69 0.993 R² (0.990 R² .. 0.996 R²) 70 mean 25.88 μs (25.23 μs .. 26.56 μs) 71 std dev 2.183 μs (1.860 μs .. 2.642 μs) 72 variance introduced by outliers: 80% (severely inflated) 73 ``` 74 75 ## Security 76 77 This library aims at the maximum security achievable in a 78 garbage-collected language under an optimizing compiler such as GHC, in 79 which strict constant-timeness can be [challenging to achieve][const]. 80 81 Note that *at present* we use GHC's native variable-length Integer 82 type internally (relevant to Poly1305 MAC handling), and make no "hard" 83 guarantees of constant-time execution. 84 85 The AEAD-ChaCha20-Poly1305 implementation within passes all 86 test vectors from RFC8439, as well as the available [Project 87 Wycheproof vectors][wyche], using the ChaCha20 cipher from 88 [ppad-chacha](https://github.com/ppad-tech/chacha) and the Poly1305 89 MAC from [ppad-poly1305](https://github.com/ppad-tech/poly1305), 90 respectively. 91 92 If you discover any vulnerabilities, please disclose them via 93 security@ppad.tech. 94 95 ## Development 96 97 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 98 development shell with: 99 100 ``` 101 $ nix develop 102 ``` 103 104 Then do e.g.: 105 106 ``` 107 $ cabal repl ppad-aead 108 ``` 109 110 to get a REPL for the main library. 111 112 [8439]: https://datatracker.ietf.org/doc/html/rfc8439 113 [nixos]: https://nixos.org/ 114 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 115 [hadoc]: https://docs.ppad.tech/aead 116 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html 117 [wyche]: https://github.com/C2SP/wycheproof