# XChaCha20

## Purpose

XChaCha20 is an **unauthenticated** stream cipher constructed using ChaCha20 and HChaCha20. It takes a 256-bit key and 192-bit nonce (**number used only once**) to encrypt/decrypt a message.

The 64-bit internal counter can be changed from the default of 0 to access any block without computing previous ones. However, it should generally not be touched.

You probably want XChaCha20-Poly1305 instead, which also ensures a message has not been tampered with. This class **MUST** only be used for custom constructions (e.g. Encrypt-then-MAC).

The nonce **MUST NOT** be repeated or reused with the same key. You **MUST** increment or randomly generate the nonce for each plaintext message encrypted using the same key.

## Usage

### Fill

Fills a span with pseudorandom bytes computed from a nonce and key. This can be used to compute the Poly1305 key for constructing XChaCha20-Poly1305.

#### Exceptions

`buffer`

has a length of 0.

`nonce`

has a length not equal to `NonceSize`

.

`key`

has a length not equal to `KeySize`

.

Error computing pseudorandom bytes.

### Encrypt

Fills a span with ciphertext computed from a plaintext message, nonce, and key.

#### Exceptions

`ciphertext`

has a length not equal to `plaintext.Length`

.

`nonce`

has a length not equal to `NonceSize`

.

`key`

has a length not equal to `KeySize`

.

Encryption failed.

### Decrypt

Fills a span with plaintext computed from a ciphertext message, nonce, and key.

#### Exceptions

`plaintext`

has a length not equal to `ciphertext.Length`

.

`nonce`

has a length not equal to `NonceSize`

.

`key`

has a length not equal to `KeySize`

.

Decryption failed.

## Constants

These are used for validation and/or save you defining your own constants.

## Notes

The key **MUST** be uniformly random. It can either be randomly generated or the output of a KDF. Furthermore, it **SHOULD** be rotated periodically (e.g. a different key per file).

As a *general* rule, avoid compression before encryption. It can leak information and has been the cause of several attacks.

Even with Encrypt-then-MAC, it is recommended to encrypt data in 16-64 KiB chunks instead of as a single plaintext message. Read the XChaCha20-Poly1305 Notes for more information.

Last updated