Geralt
  • Introduction
  • Random data
  • Constant time
  • Secure memory
  • Encoding
  • Padding
  • Hashing
  • Message authentication
  • Password hashing
  • Key derivation
  • Authenticated encryption
    • Stream and file encryption
    • AEGIS-128L
    • AEGIS-256
    • ChaCha20-Poly1305
    • XChaCha20-Poly1305
  • Key exchange
  • Digital signatures
  • Advanced
    • Validation
    • Concat
    • ChaCha20
    • XChaCha20
    • HChaCha20
    • Poly1305
    • Ed25519 to X25519
Powered by GitBook
On this page
  • Purpose
  • Usage
  • Fill
  • Encrypt
  • Decrypt
  • Constants
  • Notes
  1. Advanced

XChaCha20

Last updated 1 year ago

Purpose

is an unauthenticated stream cipher constructed using and . 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 instead, which also ensures a message has not been tampered with. This class MUST only be used for custom constructions (e.g. ).

The nonce MUST NOT be repeated or reused with the same key. You MUST or 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.Fill(Span<byte> buffer, ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> key)

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.

XChaCha20.Encrypt(Span<byte> ciphertext, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> key, ulong counter = 0)

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.

XChaCha20.Decrypt(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> key, ulong counter = 0)

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.

public const int KeySize = 32;
public const int NonceSize = 24;
public const int BlockSize = 64;

Notes

This is NOT an authenticated encryption algorithm. This class MUST only be used if you know what you are doing and apply authentication using keyed as a MAC.

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

As a general rule, avoid compression before encryption. It can and has been the cause of .

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

ArgumentOutOfRangeException
CryptographicException
ArgumentOutOfRangeException
ArgumentOutOfRangeException
ArgumentOutOfRangeException
CryptographicException
ArgumentOutOfRangeException
ArgumentOutOfRangeException
ArgumentOutOfRangeException
CryptographicException
yourself
BLAKE2b
leak information
several attacks
XChaCha20
ChaCha20
HChaCha20
XChaCha20-Poly1305
Encrypt-then-MAC
XChaCha20-Poly1305
ArgumentOutOfRangeException
ArgumentOutOfRangeException
KDF
Encrypt-then-MAC
randomly generated
randomly generate
increment
XChaCha20-Poly1305 Notes