---
name: "Crypt::AuthEnc::XChaCha20Poly1305"
section: "3pm"
platform: "linux"
package: "perl-cryptx"
version: "0.091-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Crypt::AuthEnc::XChaCha20Poly1305"
---

# Crypt::AuthEnc::XChaCha20Poly1305(3pm)

Authenticated encryption in XChaCha20-Poly1305 mode

## NAME

Crypt::AuthEnc::XChaCha20Poly1305 - Authenticated encryption in XChaCha20-Poly1305 mode

## SYNOPSIS

```
 ### OO interface
 use Crypt::AuthEnc::XChaCha20Poly1305;
 my $key = '...';
 my $nonce = '...';
 my $expected_tag = '...';
 # encrypt and authenticate
 my $ae_enc = Crypt::AuthEnc::XChaCha20Poly1305->new($key, $nonce);
 $ae_enc->adata_add('additional_authenticated_data1');
 $ae_enc->adata_add('additional_authenticated_data2');
 my $ct = $ae_enc->encrypt_add('data1');
 $ct .= $ae_enc->encrypt_add('data2');
 my $tag = $ae_enc->encrypt_done();
 # decrypt and verify
 my $ae_dec = Crypt::AuthEnc::XChaCha20Poly1305->new($key, $nonce);
 $ae_dec->adata_add('additional_authenticated_data1');
 my $pt = $ae_dec->decrypt_add($ct);
 die "decrypt failed" unless $ae_dec->decrypt_done($tag);
 ### functional interface
 use Crypt::AuthEnc::XChaCha20Poly1305 qw(
   xchacha20poly1305_encrypt_authenticate
   xchacha20poly1305_decrypt_verify
 );
 my $key = '...';
 my $nonce = '...';
 my $adata = '...';
 my $plaintext = '...';
 my ($ciphertext, $tag) = xchacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
 my $decrypted = xchacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag);
```

## DESCRIPTION

*Since: CryptX-0.089*

Provides encryption and authentication based on XChaCha20 + Poly1305 using the extended 192-bit (24-byte) nonce variant of ChaCha20-Poly1305.

This is a stateful API. Build one message by calling, in order: `"new"` or `"set_iv"`, optional `"adata_add"`, zero or more `"encrypt_add"` or `"decrypt_add"` calls, then `"encrypt_done"` or `"decrypt_done"`.

Use a fresh object per message. If you construct with `new($key)` you must call `set_iv($nonce)` before adding AAD or processing plaintext/ciphertext. When verifying, `decrypt_done($expected_tag)` is the safer one-step form; `decrypt_done()` without arguments only returns the calculated tag. The first `"encrypt_done"` / `"decrypt_done"` call finalizes the object. After that, further `"set_iv"`, `"adata_add"`, `"encrypt_add"`, `"decrypt_add"`, `"encrypt_done"`, and `"decrypt_done"` calls croak.

## EXPORT

Nothing is exported by default.

You can export selected functions:

```
  use Crypt::AuthEnc::XChaCha20Poly1305 qw(
    xchacha20poly1305_encrypt_authenticate
    xchacha20poly1305_decrypt_verify
  );
```

## FUNCTIONS

### xchacha20poly1305\_encrypt\_authenticate

```
 my ($ciphertext, $tag) = xchacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
 # $key ..... [binary string] encryption key (256 bits / 32 bytes)
 # $nonce ... [binary string] extended nonce (192 bits / 24 bytes)
 # $adata ... [binary string] additional authenticated data (optional)
```

Invalid key or nonce lengths croak. String-overloaded objects are accepted for `$key` and `$nonce`.

### xchacha20poly1305\_decrypt\_verify

my `$plaintext` = xchacha20poly1305\_decrypt\_verify($key, `$nonce`, `$adata`, `$ciphertext`, `$tag`);\
  \# on error returns undef

Invalid key or nonce lengths croak. String-overloaded objects are accepted for `$key` and `$nonce`.

## METHODS

Unless noted otherwise, assume `$ae` is an existing AEAD object created via `"new"`, for example:

```
 my $ae = Crypt::AuthEnc::XChaCha20Poly1305->new($key, $nonce);
```

### new

```
 my $ae = Crypt::AuthEnc::XChaCha20Poly1305->new($key, $nonce);
 my $ae = Crypt::AuthEnc::XChaCha20Poly1305->new($key);
 # $key ..... [binary string] encryption key (256 bits / 32 bytes)
 # $nonce ... [binary string] extended nonce (192 bits / 24 bytes)
```

### adata\_add

Add **additional authenticated data**. Can be called only before the first `"encrypt_add"` or `"decrypt_add"`. Returns the object itself (for chaining).

```
 $ae->adata_add($aad_data);                     # can be called multiple times
```

### encrypt\_add

Returns a binary string of ciphertext (raw bytes).

```
 my $ciphertext = $ae->encrypt_add($data);      # can be called multiple times
```

### encrypt\_done

Returns the authentication tag as a binary string (raw bytes). This call finalizes the current message.

```
 my $tag = $ae->encrypt_done();                 # returns $tag value
```

### decrypt\_add

Returns a binary string of plaintext (raw bytes).

```
 my $plaintext = $ae->decrypt_add($ciphertext); # can be called multiple times
```

### decrypt\_done

Without argument returns the computed tag as a binary string. With `$tag` argument returns `1` (success) or `0` (failure). This call finalizes the current message.

```
 my $tag = $ae->decrypt_done;           # returns $tag value
 #or
 my $result = $ae->decrypt_done($tag);  # returns 1 (success) or 0 (failure)
```

### set\_iv

```
 my $ae = Crypt::AuthEnc::XChaCha20Poly1305->new($key)->set_iv($nonce);
 # $nonce ... [binary string] extended nonce (192 bits / 24 bytes)
```

Call `"set_iv"` before the first `"adata_add"`, `"encrypt_add"`, or `"decrypt_add"` for a message.

### clone

Returns a copy of the AEAD object in its current state.

```
 my $ae_new = $ae->clone;
```

## SEE ALSO

- •

  Crypt::AuthEnc::ChaCha20Poly1305, Crypt::AuthEnc::GCM, Crypt::AuthEnc::CCM

- •

  \<https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha\>