https://github.com/ppad-tech/aead
Haskell AEAD-ChaCha20-Poly1305
https://github.com/ppad-tech/aead
aead chacha20 cryptography haskell poly1305
Last synced: about 2 months ago
JSON representation
Haskell AEAD-ChaCha20-Poly1305
- Host: GitHub
- URL: https://github.com/ppad-tech/aead
- Owner: ppad-tech
- License: mit
- Created: 2025-03-11T05:45:45.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-06-22T18:54:12.000Z (4 months ago)
- Last Synced: 2025-08-25T20:05:15.899Z (about 2 months ago)
- Topics: aead, chacha20, cryptography, haskell, poly1305
- Language: Haskell
- Homepage:
- Size: 77.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- License: LICENSE
Awesome Lists containing this project
README
# aead
[](https://hackage.haskell.org/package/ppad-aead)
[](https://docs.ppad.tech/aead)
A pure Haskell implementation of authenticated encryption with
associated data (AEAD) using the ChaCha20-Poly1305 configuration, as
specified by [RFC8439][8439].
## Usage
A sample GHCi session:
```
> :set -XOverloadedStrings
> import qualified Data.ByteString.Base16 as B16 -- just for illustration
>
> -- import qualified
> import qualified Crypto.AEAD.ChaCha20Poly1305 as AEAD
>
> -- encrypt plaintext with some additional authenticated data, using
> -- a secret key and nonce
> let key = "don't tell anyone my secret key!"
> let non = "or my nonce!"
> let msg = "this is my secret message"
> let aad = "and i approve it"
>
> -- encryption produces a 128-bit MAC
> let Right (cip, mac) = AEAD.encrypt aad key non msg
> B16.encode cip
"d6377eab18cad56e8c6176968460e6a548c524b9498c9b993e"
> B16.encode mac
"48751cc57cf5123bc841239c7d563da0"
>
> -- supply both to decrypt
> AEAD.decrypt aad key non (cip, tag)
Right "this is my secret message"
>
> -- bogus MACs will cause decryption to fail
> AEAD.decrypt aad key non (cip, "really i swear!!")
Left InvalidMAC
```
## Documentation
Haddocks (API documentation, etc.) are hosted at
[docs.ppad.tech/aead][hadoc].
## Performance
The aim is best-in-class performance for pure, highly-auditable Haskell
code.
Current benchmark figures on a simple input from the RFC8439 appendices
on an M4 Silicon MacBook Air look like (use `cabal bench` to run the
benchmark suite):
```
benchmarking ppad-aead/encrypt
time 10.03 μs (10.02 μs .. 10.03 μs)
1.000 R² (1.000 R² .. 1.000 R²)
mean 10.04 μs (10.04 μs .. 10.05 μs)
std dev 9.024 ns (7.330 ns .. 11.99 ns)
benchmarking ppad-aead/decrypt
time 10.06 μs (10.05 μs .. 10.07 μs)
1.000 R² (1.000 R² .. 1.000 R²)
mean 10.07 μs (10.06 μs .. 10.08 μs)
std dev 26.50 ns (21.66 ns .. 32.02 ns)
```
## Security
This library aims at the maximum security achievable in a
garbage-collected language under an optimizing compiler such as GHC, in
which strict constant-timeness can be [challenging to achieve][const].
Note that *at present* we use GHC's native variable-length Integer
type internally (relevant to Poly1305 MAC handling), and make no "hard"
guarantees of constant-time execution.
The AEAD-ChaCha20-Poly1305 implementation within passes all
test vectors from RFC8439, as well as the available [Project
Wycheproof vectors][wyche], using the ChaCha20 cipher from
[ppad-chacha](https://github.com/ppad-tech/chacha) and the Poly1305
MAC from [ppad-poly1305](https://github.com/ppad-tech/poly1305),
respectively.
If you discover any vulnerabilities, please disclose them via
security@ppad.tech.
## Development
You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
development shell with:
```
$ nix develop
```
Then do e.g.:
```
$ cabal repl ppad-aead
```
to get a REPL for the main library.
[8439]: https://datatracker.ietf.org/doc/html/rfc8439
[nixos]: https://nixos.org/
[flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
[hadoc]: https://docs.ppad.tech/aead
[const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html
[wyche]: https://github.com/C2SP/wycheproof