# ChaCha20

## Purpose

ChaCha20 is an **unauthenticated** stream cipher that uses a 256-bit key and 96-bit nonce (**number used only once**) to encrypt/decrypt a message.

The 32-bit internal counter can be changed from the default of 0 to 1 for constructing ChaCha20-Poly1305. Otherwise, it should generally be left alone.

You probably want ChaCha20-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 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 ChaCha20-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 or counter overflow prevented.

### 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 or counter overflow prevented.

## 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 ChaCha20-Poly1305 Notes for more information.

Last updated