NAME
Crypt::NaCl::Sodium::aead - Authenticated Encryption with Additional Data (ChaCha20/Poly1305 MAC, AES256-GCM)
VERSION
version 1.0.7.0
SYNOPSIS
use Crypt::NaCl::Sodium qw( :utils );
my $crypto_aead = Crypt::NaCl::Sodium->aead();
my ($key, $nonce, $additional_data, $decrypted_msg, $msg, $secret);
## Alice
########
# Alice generates secret key
$key = $crypto_aead->keygen();
# ... and shares it with Bob
send_to( Bob => { key => $key } );
# now Alice and Bob can start communicating
# then generates random nonce
$nonce = $crypto_aead->nonce();
send_to( Bob => { nonce => $nonce } );
# Alice's message to Bob
$msg = "Hi Bob!";
# unencrypted metadata
$additional_data = "greeting";
# Bob will need it to decrypt and verify secret message
send_to( Bob => { additional_data => $additional_data } );
# the secret will include the additional data
$secret = $crypto_aead->encrypt( $msg, $additional_data, $nonce, $key );
# message is ready for Bob
send_to( Bob => { secret => $secret } );
## Bob
########
# Bob receives the secret key from Alice
$key = receive_for( Bob => 'key' );
# and random nonce
$nonce = receive_for( Bob => 'nonce' );
# Bob is now ready to receive first message from Alice
# first the additional data
$additional_data = receive_for( Bob => 'additional_data' );
# then the secret itself
$secret = receive_for( Bob => 'secret' );
# he has now all information required to decrypt message
$decrypted_msg = $crypto_aead->decrypt( $secret, $additional_data, $nonce, $key );
# time to reply
$msg = "Hello Alice!";
# generates new nonce
$nonce = $crypto_aead->nonce();
# Bob replies with no additional data
$additional_data = "";
# let's encrypt now
$secret = $crypto_aead->encrypt( $msg, $additional_data, $nonce, $key );
# Alice needs all pieces to verify and decrypt Bob's message
send_to( Alice => { nonce => $nonce } );
send_to( Alice => { additional_data => $additional_data } );
send_to( Alice => { secret => $secret } );
## Alice
########
# Bob's data sent to Alice
$nonce = receive_for( Alice => 'nonce' );
$additional_data = receive_for( Alice => 'additional_data' );
$secret = receive_for( Alice => 'secret' );
# we have now all information required to decrypt message
$decrypted_msg = $crypto_aead->decrypt( $secret, $additional_data, $nonce, $key );
# NOTE: send_to() and receive_for() and user functions providing transport of
# messagesDESCRIPTION
Authenticated Encryption with Additional Data combines the secret-key encryption with a mechanism to include an optional, non-confidential (not-encrypted) data which can provide some protocol-specific metadata.
The additional data is included when computing the MAC of the secret and the decryption will never be performed, even partially, before verification.
The generated key must be distributed in secret.
Nonce (number used once) does not have to be protected, but it is crucial that the same nonce has not been ever reused with the same key. The recommended way is to generate the initial nonce with first message and then increment it for each subsequent message using the same key - see "increment" in Crypt::NaCl::Sodium.
The default algorithm is ChaCha20 with Poly1305 MAC.
If Intel SSSE3 extensions, aesni and pcmul instructions are available the hardware-accelerated AES256-GCM cipher can also be used.
METHODS
ChaCha20/Poly1305 MAC
The nonce is 64 bits long,
Methods that use IETF-compatible extended nonce (96-bit) and a 32-bit counter are also available as "ietf_nonce", "ietf_encrypt" and "ietf_decrypt".
keygen
my $key = $crypto_aead->keygen();Helper method to generate a random key to be used by $crypto_aead.
The length of the $key equals "KEYBYTES".
NOTE: keep the key confidential.
Returns Data::BytesLocker object.
nonce
my $nonce = $crypto_aead->nonce();Helper method to generate a random nonce to be used by $crypto_aead.
The length of the nonce equals "NPUBBYTES".
If initial value has been passed as the argument, it will then padded with null bytes.
my $counter = 121;
my $nonce = $crypto_aead->nonce($counter);
$nonce =~ /^121\0+$/ or die;NOTE: nonce does not have to be random nor confidential, but it must never be reused with the same key.
If random nonce is being used it needs to be provided to the other party to allow decryption.
If counter is being used store it alongside the key to avoid accidental reuse on the next session. In connection-oriented protocols counter-based nonce could help rejecting duplicate messages.
Returns Data::BytesLocker object.
ietf_nonce
my $nonce_ietf = $crypto_aead->ietf_nonce();Same as above but generates IETF-compatible extended nonce.
The length of the nonce equals "IETF_NPUBBYTES".
encrypt
my $secret = $crypto_aead->encrypt($msg, $additional_data, $nonce, $key);Encrypts the plaintext message using given $nonce and $key. Even when empty the $additional_data will be used to compute the MAC of the secret message.
The length of the $secret is at most equal to the length of $msg + "ABYTES".
Returns Data::BytesLocker object.
ietf_encrypt
my $secret = $crypto_aead->ietf_encrypt($msg, $additional_data, $nonce_ietf, $key);Same as above but uses IETF-compatible extended nonce.
decrypt
my $msg;
eval {
$msg = $crypto_aead->decrypt($secret, $additional_data, $nonce, $key);
};
if ( $@ ) {
warn "Message forged!";
} else {
print "Decrypted message: $msg\n";
}Verify and decrypt the secret message with $additional_data using given $nonce and $key.
Function croaks if the verification fails. Otherwise returns the decrypted message.
The length of the $msg is at most equal to the length of $secret - "ABYTES".
Returns Data::BytesLocker object.
ietf_decrypt
my $msg;
eval {
$msg = $crypto_aead->ietf_decrypt($secret, $additional_data, $nonce_ietf, $key);
};
if ( $@ ) {
warn "Message forged!";
} else {
print "Decrypted message: $msg\n";
}Same as above but uses IETF-compatible extended nonce.
AES256-GCM
When supported by the CPU, AES256-GCM is the fastest AEAD cipher available in this library.
If portability is a concern, use default "ChaCha20/Poly1305 MAC" cipher.
aes256gcm_is_available
if ( $crypto_aead->aes256gcm_is_available ) {
print "Can use AES256-GCM!\n";
}Returns true if the current CPU supports AES256-GCM implementation.
aes256gcm_keygen
my $key = $crypto_aead->aes256gcm_keygen();Helper method to generate a random key to be used by $crypto_aead.
The length of the $key equals "AES256GCM_KEYBYTES".
NOTE: keep the key confidential.
Returns Data::BytesLocker object.
NOTE: if AES256-GCM is not available this method croaks.
aes256gcm_beforenm
my $precal_key = $crypto_aead->aes256gcm_beforenm( $key );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.
Returns Crypt::NaCl::Sodium::aead::aes256gcmstate object which encapsulates the expanded key.
NOTE: the returned object provides following methods to allow securing the access to the expanded key:
NOTE: if AES256-GCM is not available this method croaks.
lock
$precal_key->lock();When called makes the state inaccessible. It cannot be read or written, but the data are preserved.
unlock
$precal_key->unlock();When called makes the state accessible for read access only.
is_locked
if ( $precal_key->is_locked ) {
$precal_key->unlock;
}Returns true if the $precal_key object is locked, false otherwise.
aes256gcm_nonce
my $nonce = $crypto_aead->aes256gcm_nonce();Helper method to generate a random nonce to be used by $crypto_aead.
The length of the nonce equals "AES256GCM_NPUBBYTES".
If initial value has been passed as the argument, it will then padded with null bytes.
my $counter = 121;
my $nonce = $crypto_aead->aes256gcm_nonce($counter);
$nonce =~ /^121\0+$/ or die;NOTE: nonce does not have to be random nor confidential, but it must never be reused with the same key.
If random nonce is being used it needs to be provided to the other party to allow decryption.
If counter is being used store it alongside the key to avoid accidental reuse on the next session. In connection-oriented protocols counter-based nonce could help rejecting duplicate messages.
Returns Data::BytesLocker object.
NOTE: if AES256-GCM is not available this method croaks.
aes256gcm_encrypt
my $secret = $crypto_aead->aes256gcm_encrypt($msg, $additional_data, $nonce, $key);Encrypts the plaintext message using given $nonce and $key. Even when empty the $additional_data will be used to compute the MAC of the secret message.
The length of the $secret is at most equal to the length of $msg + "AES256GCM_ABYTES".
Returns Data::BytesLocker object.
NOTE: if AES256-GCM is not available this method croaks.
aes256gcm_encrypt_afternm
my $secret = $crypto_aead->aes256gcm_encrypt_afternm($msg, $additional_data, $nonce,
$precal_key);Same as above but uses precalculated key (as returned by "aes256gcm_beforenm").
aes256gcm_decrypt
my $msg;
eval {
$msg = $crypto_aead->aes256gcm_decrypt($secret, $additional_data, $nonce, $key);
};
if ( $@ ) {
warn "Message forged!";
} else {
print "Decrypted message: $msg\n";
}Verify and decrypt the secret message with $additional_data using given $nonce and $key.
Function croaks if the verification fails. Otherwise returns the decrypted message.
The length of the $msg is at most equal to the length of $secret - "AES256GCM_ABYTES".
Returns Data::BytesLocker object.
NOTE: if AES256-GCM is not available this method croaks.
aes256gcm_decrypt_afternm
my $msg;
eval {
$msg = $crypto_aead->aes256gcm_decrypt_afternm($secret, $additional_data, $nonce,
$precal_key);
};
if ( $@ ) {
warn "Message forged!";
} else {
print "Decrypted message: $msg\n";
}Same as above but uses precalculated key (as returned by "aes256gcm_beforenm").
CONSTANTS
NPUBBYTES
my $nonce_length = $crypto_aead->NPUBBYTES;Returns the length of nonce used by "ChaCha20/Poly1305 MAC" methods.
IETF_NPUBBYTES
my $nonce_length = $crypto_aead->IETF_NPUBBYTES;Returns the length of nonce used by IETF-compatible "ChaCha20/Poly1305 MAC" methods.
AES256GCM_NPUBBYTES
my $nonce_length = $crypto_aead->AES256GCM_NPUBBYTES;Returns the length of nonce used by "AES256-GCM" methods.
NOTE: if AES256-GCM is not available this method croaks.
KEYBYTES
my $key_length = $crypto_aead->KEYBYTES;Returns the length of key used by "ChaCha20/Poly1305 MAC" methods.
AES256GCM_KEYBYTES
my $key_length = $crypto_aead->AES256GCM_KEYBYTES;Returns the length of key used by "AES256-GCM" methods.
NOTE: if AES256-GCM is not available this method croaks.
ABYTES
my $additional_bytes = $crypto_aead->ABYTES;Returns the maximum of number of additional bytes added to encrypted messages used by "ChaCha20/Poly1305 MAC" methods.
AES256GCM_ABYTES
my $additional_bytes = $crypto_aead->AES256GCM_ABYTES;Returns the maximum of number of additional bytes added to encrypted messages used by "AES256-GCM" methods.
NOTE: if AES256-GCM is not available this method croaks.
ALGORITHM DETAILS
crypto_aead for encryption by default uses ChaCha20 stream cipher and Poly1305 MAC for authentication.
Google has selected those algorithms as a replacement for RC4 in OpenSSL, and shortly afterwards it has been added to OpenSSH.
The AES256-GCM algorithm has been recommended by NIST and is a part of the TLS 1.2 ciphers.
SEE ALSO
Data::BytesLocker - guarded data storage
AUTHOR
Alex J. G. Burzyński <ajgb@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Alex J. G. Burzyński <ajgb@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.