aead

Pure Haskell AEAD-ChaCha20-Poly1305 (docs.ppad.tech/aead).
git clone git://git.ppad.tech/aead.git
Log | Files | Refs | README | LICENSE

README.md (3764B)


      1 # aead
      2 
      3 [![](https://img.shields.io/hackage/v/ppad-aead?color=blue)](https://hackage.haskell.org/package/ppad-aead)
      4 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      5 [![](https://img.shields.io/badge/haddock-aead-lightblue)](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