chacha

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

README.md (2797B)

      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 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   "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 my mid-2020 MacBook Air look like (use `cabal bench` to run the
     44 benchmark suite):
     45 
     46 ```
     47   benchmarking ppad-chacha/cipher
     48   time                 1.554 μs   (1.510 μs .. 1.596 μs)
     49                        0.995 R²   (0.994 R² .. 0.997 R²)
     50   mean                 1.541 μs   (1.511 μs .. 1.579 μs)
     51   std dev              115.1 ns   (95.95 ns .. 139.7 ns)
     52   variance introduced by outliers: 81% (severely inflated)
     53 ```
     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 
     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