chacha

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

README.md (2746B)

      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                 770.2 ns   (769.9 ns .. 770.5 ns)
     49                        1.000 R²   (1.000 R² .. 1.000 R²)
     50   mean                 770.2 ns   (770.0 ns .. 770.5 ns)
     51   std dev              794.7 ps   (653.0 ps .. 999.5 ps)
     52 ```
     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 
     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