NAME

Crypt::Sodium::XS::aead - Authenticated encryption with additional data

SYNOPSIS

use Crypt::Sodium::XS::aead ":xchacha20poly1305";
use Crypt::Sodium::XS::Util "sodium_increment";

my $key = aead_xchacha20poly1305_ietf_keygen();
my $nonce = aead_xchacha20poly1305_ietf_nonce();
my $msg = "hello";

# combined mode, mac and ciphertext combined

my $ciphtertext
  = aead_xchacha20poly1305_ietf_encrypt($msg, $nonce, $key);
my $plaintext
  = aead_xchacha20poly1305_ietf_decrypt($ciphertext, $nonce, $key);
# $plaintext eq $msg

$nonce = sodium_increment($nonce);
# NOTE: $adata is not confidential
my $adata = "additional cryptographically validated data";

$ciphtertext
  = aead_xchacha20poly1305_ietf_encrypt($msg, $nonce, $key, $adata);
$plaintext
  = aead_xchacha20poly1305_ietf_decrypt($ciphertext, $nonce, $key, $adata);
# $plaintext eq $msg and $adata is authentic

# detached mode, mac and ciphertext separate

$nonce = sodium_increment($nonce);

my ($ciphtertext, $mac)
  = aead_xchacha20poly1305_ietf_encrypt_detached($msg, $nonce, $key, $adata);
my $plaintext
  = aead_xchacha20poly1305_ietf_decrypt($ciphertext, $mac, $nonce, $key, $adata);
# $plaintext eq $msg and $adata is authentic

DESCRIPTION

Crypt::Sodium::XS::aead encrypts a message with a key and a nonce to keep it confidential.

Crypt::Sodium::XS::aead computes an authentication MAC. This MAC is used to make sure that the message, as well as optional, non-confidential (non-encrypted) data haven't been tampered with.

These functions accept an optional, arbitrary long "additional data" ($adata below) parameter. These data are not present in the ciphertext, but are mixed in the computation of the authentication MAC. A typical use for these data is to authenticate version numbers, timestamps or monotonically increasing counters in order to discard previous messages and prevent replay attacks. It can also be used to to authenticate protocol-specific metadata about the message, such as its length and encoding, or other arbitrary non-confidential headers.

FUNCTIONS

Nothing is exported by default. A :features tag imports the *_available feature test functions. A separate import tag is provided for functions and constants for each of the primitives listed in "PRIMITIVES". For example, :chacha20poly1305 imports aead_chacha20poly1305_decrypt. You should use at least one import tag. A :all tag imports everything.

NOTE: Crypt::Sodium::XS::aead, like libsodium, does not provide generic functions for AEAD. Only the primitive-specific functions are available, so there is no :default tag.

aead_aes256gcm_available

my $has_aes256gcm = aead_aes256gcm_available();

aead_aes256gcm_beforenm

my $precalc = aead_aes256gcm_beforenm($key);

NOTE: aes256gcm primitive only!

Returns a precalculation aead object. This is useful when performing many operations with the same key. See "PRECALCULATION INTERFACE".

aead_<primitive>_decrypt

my $plaintext = aead_xchacha20poly1305_ietf_decrypt(
                  $ciphertext, $nonce, $key, $adata, $flags);

Croaks on decryption failure.

$adata is optional. See notes in "DESCRIPTION".

$flags is optional. It is the flags used for the $plaintext Crypt::Sodium::XS::MemVault object. See "MEMORY SAFETY" in Crypt::Sodium::XS.

aead_<primitive>_decrypt_detached

my $plaintext = aead_chacha20poly1305_decrypt_detached(
                  $ciphertext, $mac, $nonce, $key, $adata, $flags);

Croaks on decryption failure.

$adata is optional. See notes in "DESCRIPTION".

$flags is optional. It is the flags used for the $plaintext Crypt::Sodium::XS::MemVault object. See "MEMORY SAFETY" in Crypt::Sodium::XS.

aead_<primitive>_encrypt

my $ciphertext
  = aead_chacha20poly1305_ietf_encrypt($plaintext, $nonce, $key, $adata);

$adata is optional. See notes in "DESCRIPTION".

aead_<primitive>_encrypt_detached

my ($ciphertext, $mac)
  = aead_aes256gcm_encrypt_detached($plaintext, $nonce, $key, $adata);

$adata is optional. See notes in "DESCRIPTION".

aead_<primitive>_keygen

my $key = aead_xchacha20poly1305_ietf_keygen();

aead_<primitive>_nonce

my $nonce = aead_xchacha20poly1305_ietf_nonce();

NOTE: This function provides a random nonce of the correct size for the given primitive. chacha20poly1305 and aes256gcm should *not* be used with only random nonces, as they have a short nonce and collisions are a risk. For those primitives, you can still generate a random nonce with this function, but you should then use "sodium_increment" in Crypt::Sodium::XS to get a new nonce for each message.

PRECALCULATION INTERFACE

Only available for aes256gcm.

Applications that encrypt several messages using the same key can gain a little speed by expanding the AES key only once, via the precalculation interface.

A precalculated aead object is created by calling the "aead_beforenm" function. It is an opaque object which provides the following methods:

decrypt

my $plaintext = $precalc->decrypt($ciphertext, $nonce, $adata, $flags);

Croaks on decryption failure.

$adata is optional. See notes in "DESCRIPTION".

$flags is optional. It is the flags used for the $plaintext Crypt::Sodium::XS::MemVault object. See "MEMORY SAFETY" in Crypt::Sodium::XS.

decrypt_detached

my $plaintext = $precalc->decrypt($ciphertext, $mac, $nonce, $adata, $flags);

Croaks on decryption failure.

$adata is optional. See notes in "DESCRIPTION".

$flags is optional. It is the flags used for the $plaintext Crypt::Sodium::XS::MemVault object. See "MEMORY SAFETY" in Crypt::Sodium::XS.

encrypt

my $ciphertext = $precalc->encrypt($plaintext, $nonce, $adata);

$adata is optional. See notes in "DESCRIPTION".

encrypt_detached

my ($ciphertext, $mac) = $precalc->encrypt($plaintext, $nonce, $adata);

$adata is optional. See notes in "DESCRIPTION".

CONSTANTS

aead_<primitive>_ABYTES

my $additional_data_length = aead_chacha20poly1305_ABYTES();

This is not a restriction on the amount of additional data, it is the size of the ciphertext MAC.

aead_<primitive>_KEYBYTES

my $key_length = aead_chacha20poly1305_ietf_KEYBYTES();

aead_<primitive>_MESSAGEBYTES_MAX

my $message_max_length = aead_aes256gcm_MESSAGEBYTES_MAX();

aead_<primitive>_NPUBBYTES

my $nonce_length = aead_xchacha20poly1305_ietf_NPUBBYTES();

PRIMITIVES

All functions have aead_<primitive>-prefixed couterparts (e.g., aead_xchacha20poly1305_encrypt, aead_chacha20poly1305_ietf_ABYTES).

chacha20poly1305
chacha20poly1305_ietf
xchacha20poly1305_ietf
aes256gcm

Check "aead_aes256gcm_available" to see if this primitive can be used.

WARNING: Despite being the most popular AEAD construction due to its use in TLS, safely using AES-GCM in a different context is tricky.

No more than ~ 350 GB of input data should be encrypted with a given key. This is for ~ 16 KB messages -- Actual figures vary according to message sizes.

In addition, nonces are short and repeated nonces would totally destroy the security of this scheme. Nonces should thus come from atomic counters, which can be difficult to set up in a distributed environment.

Unless you absolutely need AES-GCM, use xchacha20poly1305_ietf (this is the default) instead. It doesn't have any of these limitations.

Or, if you don't need to authenticate additional data, just stick to Crypt::Sodium::XS::secretbox.
aegis128l

Check "aead_aegis_available" to see if this primitive can be used.
aegis256

Check "aead_aegis_available" to see if this primitive can be used.

FEEDBACK

For reporting bugs, giving feedback, submitting patches, etc. please use the following:

RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS
IRC channel #sodium on irc.perl.org.
Email the author directly.

AUTHOR

Brad Barden <perlmodules@5c30.org>

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Crypt::Sodium::XS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Crypt::Sodium::XS

CPAN shell

perl -MCPAN -e shell
install Crypt::Sodium::XS

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

aead_aes256gcm_available

aead_aes256gcm_beforenm

aead_<primitive>_decrypt

aead_<primitive>_decrypt_detached

aead_<primitive>_encrypt

aead_<primitive>_encrypt_detached

aead_<primitive>_keygen

aead_<primitive>_nonce

PRECALCULATION INTERFACE

CONSTANTS

aead_<primitive>_ABYTES

aead_<primitive>_KEYBYTES

aead_<primitive>_MESSAGEBYTES_MAX

aead_<primitive>_NPUBBYTES

PRIMITIVES

SEE ALSO

FEEDBACK

AUTHOR

COPYRIGHT & LICENSE

Module Install Instructions