view release on metacpan or  search on metacpan

lib/Crypt/NaCl/Sodium/aead.pod  view on Meta::CPAN

Same as above but uses C<IETF>-compatible extended nonce.

=head2 AES256-GCM

When supported by the CPU, C<AES256-GCM> is the fastest C<AEAD> cipher available
in this library.

If portability is a concern, use default L</"ChaCha20/Poly1305 MAC"> cipher.

=head3 aes256gcm_is_available

    if ( $crypto_aead->aes256gcm_is_available ) {
        print "Can use AES256-GCM!\n";
    }

Returns true if the current CPU supports C<AES256-GCM> implementation.

=head3 aes256gcm_keygen

    my $key = $crypto_aead->aes256gcm_keygen();

Helper method to generate a random key to be used by C<$crypto_aead>.

The length of the C<$key> equals L</AES256GCM_KEYBYTES>.

B<NOTE:> keep the key confidential.

Returns L<Data::BytesLocker> object.

B<NOTE:> if C<AES256-GCM> is not available this method croaks.

=head3 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 C<Crypt::NaCl::Sodium::aead::aes256gcmstate> object which encapsulates
the expanded key.

B<NOTE:> the returned object provides following methods to allow securing the
access to the expanded key:

B<NOTE:> if C<AES256-GCM> is not available this method croaks.

=head4 lock

    $precal_key->lock();

When called makes the state inaccessible. It cannot be read or written,
but the data are preserved.

=head4 unlock

    $precal_key->unlock();

When called makes the state accessible for read access only.

=head4 is_locked

    if ( $precal_key->is_locked ) {
        $precal_key->unlock;
    }

Returns true if the C<$precal_key> object is locked, false otherwise.

=head3 aes256gcm_nonce

    my $nonce = $crypto_aead->aes256gcm_nonce();

Helper method to generate a random nonce to be used by C<$crypto_aead>.

The length of the nonce equals L</AES256GCM_NPUBBYTES>.

If initial value has been passed as the argument, it will then padded with
C<null> bytes.

    my $counter = 121;
    my $nonce = $crypto_aead->aes256gcm_nonce($counter);
    $nonce =~ /^121\0+$/ or die;

B<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 L<Data::BytesLocker> object.

B<NOTE:> if C<AES256-GCM> is not available this method croaks.

=head3 aes256gcm_encrypt

    my $secret = $crypto_aead->aes256gcm_encrypt($msg, $additional_data, $nonce, $key);

Encrypts the plaintext message using given C<$nonce> and C<$key>. Even when empty the
C<$additional_data> will be used to compute the MAC of the secret message.

The length of the C<$secret> is at most equal to the length of C<$msg> +
L</AES256GCM_ABYTES>.

Returns L<Data::BytesLocker> object.

B<NOTE:> if C<AES256-GCM> is not available this method croaks.

=head4 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 L</aes256gcm_beforenm>).

=head3 aes256gcm_decrypt

    my $msg;
    eval {
        $msg = $crypto_aead->aes256gcm_decrypt($secret, $additional_data, $nonce, $key);
    };
    if ( $@ ) {
        warn "Message forged!";
    } else {