chacha

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

README.md (2836B)

      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 plaintext"
     24   > ciphertext
     25   "\192*c\248A\204\211n\130y8\197\146k\245\178Y\197=\180_\223\138\146:^\206\&0\v[\201"
     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 plaintext"
     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. Current benchmark figures on the
     40 simple "sunscreen input" from RFC8439 on an M4 Silicon MacBook Air,
     41 where we avail of hardware acceleration via ARM NEON intrinsics, look
     42 like (use `cabal bench` to run the benchmark suite):
     43 
     44 ```
     45   benchmarking ppad-chacha/cipher
     46   time                 267.1 ns   (266.0 ns .. 268.2 ns)
     47                        1.000 R²   (0.999 R² .. 1.000 R²)
     48   mean                 267.1 ns   (264.8 ns .. 270.3 ns)
     49   std dev              8.576 ns   (6.191 ns .. 11.56 ns)
     50 ```
     51 
     52 You should compile with the 'llvm' flag for maximum performance.
     53 
     54 ## Security
     55 
     56 This library aims at the maximum security achievable in a
     57 garbage-collected language under an optimizing compiler such as GHC, in
     58 which strict constant-timeness can be [challenging to achieve][const].
     59 
     60 The ChaCha20 cipher within passes all test vectors from RFC8439,
     61 and the downstream AEAD-ChaCha20-Poly1305 implementation in
     62 [ppad-aead](https://github.com/ppad-tech/aead) passes all the [Project
     63 Wycheproof vectors][wyche].
     64 
     65 If you discover any vulnerabilities, please disclose them via
     66 security@ppad.tech.
     67 
     68 ## Development
     69 
     70 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     71 development shell with:
     72 
     73 ```
     74 $ nix develop
     75 ```
     76 
     77 Then do e.g.:
     78 
     79 ```
     80 $ cabal repl ppad-chacha
     81 ```
     82 
     83 to get a REPL for the main library.
     84 
     85 [8439]: https://datatracker.ietf.org/doc/html/rfc8439
     86 [nixos]: https://nixos.org/
     87 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
     88 [hadoc]: https://docs.ppad.tech/chacha
     89 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html
     90 [wyche]: https://github.com/C2SP/wycheproof