chacha

The ChaCha20 stream cipher (docs.ppad.tech/chacha).
git clone git://git.ppad.tech/chacha.git
Log | Files | Refs | README | LICENSE

README.md (2907B)


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