1 # XChaCha20 - Extended Nonce Version of ChaCha20
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.
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.
22 [IETF XChaCha20 Draft](https://tools.ietf.org/html/draft-arciszewski-xchacha-03)
24 [Bernstein's ChaCha Web page](http://cr.yp.to/chacha.html)
26 [Libsodium Documentation](https://libsodium.gitbook.io/doc/advanced/stream_ciphers/xchacha20)
28 [Crypto++ Documentation](https://www.cryptopp.com/wiki/XChaCha20)
30 [Wikipedia](https://en.wikipedia.org/wiki/Salsa20)
34 I am not a cryptographer so use this library at your own risk.
39 Import the library into your project
42 #include "xchacha20.h"
45 Create a XChaCha context
51 Set up the 256-bit encryption key and the 192-bit nonce to be used.
54 xchacha_keysetup(&ctx, key, nonce);
57 Optionally, set the counter to a different starting value other than zero.
60 xchacha_set_counter(&ctx, 0x1);
63 Then use xchacha_encrypt_bytes or xchacha_encrypt_blocks to encrypt data
66 xchacha_encrypt_bytes(&ctx, plaintext, ciphertext, sizeof(plaintext));
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.
78 To make the test program simply run make
82 Then run the test program
86 The program will produce the following output if successful:
88 Cryptographic tests passed
90 If this library failed to generate the correct ciphertexts, then something
91 is wrong with the library and you will see this output:
93 Cryptographic tests failed!
98 - [x] Add a program to calculate and compare test vectors
99 - [ ] Find and add more test vectors for XChaCha20
104 Pull requests, new feature suggestions, and bug reports/issues are
110 This project uses semantic versioning 2.0. Version numbers follow the
111 MAJOR.MINOR.PATCH format.
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)