README.md (2907B)
1 # chacha 2 3 [](https://hackage.haskell.org/package/ppad-chacha) 4  5 [](https://docs.ppad.tech/chacha) 6 7 A fast Haskell implementation of the ChaCha20 stream cipher as specified 8 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.Cipher.ChaCha20 as ChaCha20 19 > 20 > -- encrypt some plaintext using a secret key and nonce 21 > let key = "don't tell anyone my secret key!" 22 > let non = "or my nonce!" 23 > let Right ciphertext = ChaCha20.cipher key 1 non "but you can share the ciphertext" 24 > ciphertext 25 "\192*c\248A\204\211n\130y8\197\146k\245\178Y\197=\180_\223\153\151+_\197\&6\SUBF\197\160" 26 > 27 > -- use the cipher with the same key, counter, and nonce to decrypt the ciphertext 28 > ChaCha20.cipher key 1 non ciphertext 29 Right "but you can share the ciphertext" 30 ``` 31 32 ## Documentation 33 34 Haddocks (API documentation, etc.) are hosted at 35 [docs.ppad.tech/chacha][hadoc]. 36 37 ## Performance 38 39 The aim is best-in-class performance. We avail of hardware 40 acceleration via ARM NEON on aarch64, and x86 SSE2 on x86_64, along 41 with AVX2 whenever the CPU supports it. Current benchmark figures on 42 the simple "sunscreen input" from RFC8439 on an M4 Silicon MacBook Air 43 look like (use `cabal bench` to run the benchmark suite): 44 45 ``` 46 benchmarking ppad-chacha/cipher 47 time 267.1 ns (266.0 ns .. 268.2 ns) 48 1.000 R² (0.999 R² .. 1.000 R²) 49 mean 267.1 ns (264.8 ns .. 270.3 ns) 50 std dev 8.576 ns (6.191 ns .. 11.56 ns) 51 ``` 52 53 You should compile with the 'llvm' flag for maximum performance. 54 55 ## Security 56 57 This library aims at the maximum security achievable in a 58 garbage-collected language under an optimizing compiler such as GHC, in 59 which strict constant-timeness can be [challenging to achieve][const]. 60 61 The ChaCha20 cipher within passes all test vectors from RFC8439, 62 and the downstream AEAD-ChaCha20-Poly1305 implementation in 63 [ppad-aead](https://github.com/ppad-tech/aead) passes all the [Project 64 Wycheproof vectors][wyche]. 65 66 If you discover any vulnerabilities, please disclose them via 67 security@ppad.tech. 68 69 ## Development 70 71 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a 72 development shell with: 73 74 ``` 75 $ nix develop 76 ``` 77 78 Then do e.g.: 79 80 ``` 81 $ cabal repl ppad-chacha 82 ``` 83 84 to get a REPL for the main library. 85 86 [8439]: https://datatracker.ietf.org/doc/html/rfc8439 87 [nixos]: https://nixos.org/ 88 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html 89 [hadoc]: https://docs.ppad.tech/chacha 90 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html 91 [wyche]: https://github.com/C2SP/wycheproof