chacha

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

README.md (2811B)

      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 pure 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 for pure, highly-auditable Haskell
     40 code.
     41 
     42 Current benchmark figures on the simple "sunscreen input" from RFC8439
     43 on an M4 Silicon MacBook Air look like (use `cabal bench` to run the
     44 benchmark suite):
     45 
     46 ```
     47   benchmarking ppad-chacha/cipher
     48   time                 468.3 ns   (467.9 ns .. 468.8 ns)
     49                        1.000 R²   (1.000 R² .. 1.000 R²)
     50   mean                 468.4 ns   (468.0 ns .. 469.2 ns)
     51   std dev              2.041 ns   (1.317 ns .. 3.539 ns)
     52 ```
     53 
     54 You should compile with the 'llvm' flag for maximum performance.
     55 
     56 ## Security
     57 
     58 This library aims at the maximum security achievable in a
     59 garbage-collected language under an optimizing compiler such as GHC, in
     60 which strict constant-timeness can be [challenging to achieve][const].
     61 
     62 The ChaCha20 cipher within passes all test vectors from RFC8439,
     63 and the downstream AEAD-ChaCha20-Poly1305 implementation in
     64 [ppad-aead](https://github.com/ppad-tech/aead) passes all the [Project
     65 Wycheproof vectors][wyche].
     66 
     67 If you discover any vulnerabilities, please disclose them via
     68 security@ppad.tech.
     69 
     70 ## Development
     71 
     72 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     73 development shell with:
     74 
     75 ```
     76 $ nix develop
     77 ```
     78 
     79 Then do e.g.:
     80 
     81 ```
     82 $ cabal repl ppad-chacha
     83 ```
     84 
     85 to get a REPL for the main library.
     86 
     87 [8439]: https://datatracker.ietf.org/doc/html/rfc8439
     88 [nixos]: https://nixos.org/
     89 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
     90 [hadoc]: https://docs.ppad.tech/chacha
     91 [const]: https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html
     92 [wyche]: https://github.com/C2SP/wycheproof