crypto/chacha20/README.md

   1 # XChaCha20 - Extended Nonce Version of ChaCha20
   2
   3 XChaCha20 is a stream cipher based on ChaCha20. XChaCha20 uses a 256-bit
   4 key and a 192-bit nonce. According to an [IETF draft:](https://tools.ietf.org/html/draft-arciszewski-xchacha-02), "The eXtended-nonce ChaCha cipher construction (XChaCha) allows for
   5 ChaCha-based ciphersuites to accept a 192-bit nonce with similar guarantees
   6 to the original construction, except with a much lower probability of
   7 nonce misuse occurring. This enables XChaCha constructions to be stateless,
   8 while retaining the same security assumptions as ChaCha."
   9 Also, XChaCha20 does not use any look up tables and is immune to
  10 timing attacks. This library is based on Daniel J. Bernstein's reference
  11 implementation of the ChaCha stream cipher.
  12
  13 I decided to make this small C library for XChaCha20 because I could not
  14 find one. Unlike some other libraries, it only allows using XChaCha20 with
  15 a 256-bit key and a 192-bit nonce. No other key sizes or nonce sizes are
  16 allowed. A large benefit of using XChaCha20 over the regular ChaCha20 is that
  17 the larger nonce (192 bits v.s. 64 bits) allows the use of random nonces and
  18 is more resistant to nonce misuse.
  19
  20 **More Information**
  21
  22 [IETF XChaCha20 Draft](https://tools.ietf.org/html/draft-arciszewski-xchacha-03)
  23
  24 [Bernstein's ChaCha Web page](http://cr.yp.to/chacha.html)
  25
  26 [Libsodium Documentation](https://libsodium.gitbook.io/doc/advanced/stream_ciphers/xchacha20)
  27
  28 [Crypto++ Documentation](https://www.cryptopp.com/wiki/XChaCha20)
  29
  30 [Wikipedia](https://en.wikipedia.org/wiki/Salsa20)
  31
  32 **WARNING**
  33
  34 I am not a cryptographer so use this library at your own risk.
  35
  36
  37 **Getting Started**
  38
  39 Import the library into your project
  40
  41 ```C
  42     #include "xchacha20.h"
  43 ```
  44
  45 Create a XChaCha context
  46
  47 ```C
  48     XChaCha_ctx ctx;
  49 ```
  50
  51 Set up the 256-bit encryption key and the 192-bit nonce to be used.
  52
  53 ```C
  54     xchacha_keysetup(&ctx, key, nonce);
  55 ```
  56
  57 Optionally, set the counter to a different starting value other than zero.
  58
  59 ```C
  60     xchacha_set_counter(&ctx, 0x1);
  61 ```
  62
  63 Then use xchacha_encrypt_bytes or xchacha_encrypt_blocks to encrypt data
  64
  65 ```C
  66     xchacha_encrypt_bytes(&ctx, plaintext, ciphertext, sizeof(plaintext));
  67 ```
  68
  69
  70 **Test Vectors**
  71
  72 In the src folder is a program named test.c It calculates and compares
  73 XChaCha20 test vectors obtained from two different sources. The test vectors
  74 were borrowed from the IETF draft regarding XChaCha20 and an example from
  75 Crypto++ wikipedia. It will compare the output of this XChaCha20 library with
  76 known good test vectors to ensure this library is working correctly.
  77
  78 To make the test program simply run make
  79
  80     make
  81
  82 Then run the test program
  83
  84     ./test
  85
  86 The program will produce the following output if successful:
  87
  88     Cryptographic tests passed
  89
  90 If this library failed to generate the correct ciphertexts, then something
  91 is wrong with the library and you will see this output:
  92
  93     Cryptographic tests failed!
  94
  95
  96 **To Do**
  97
  98 - [x] Add a program to calculate and compare test vectors
  99 - [ ] Find and add more test vectors for XChaCha20
 100
 101
 102 **Contributing**
 103
 104 Pull requests, new feature suggestions, and bug reports/issues are
 105 welcome.
 106
 107
 108 **Versioning**
 109
 110 This project uses semantic versioning 2.0. Version numbers follow the
 111 MAJOR.MINOR.PATCH format.
 112
 113
 114 **License**
 115
 116 This project is licensed under the 3-Clause BSD License also known as the
 117 *"New BSD License"* or the *"Modified BSD License"*. A copy of the license
 118 can be found in the LICENSE file. A copy can also be found at the
 119 [Open Source Institute](https://opensource.org/licenses/BSD-3-Clause)