NAME
Crypt::Sodium::XS::secretbox - Secret key authenticated encryption
SYNOPSIS
use Crypt::Sodium::XS::secretbox ":default";
use Crypt::Sodium::XS "sodium_increment";
my $sk = secretbox_keygen();
my $nonce = secretbox_nonce();
my $ct = secretbox_encrypt("hello", $nonce, $sk);
my $pt = secretbox_decrypt($ct, $nonce, $sk);
# $pt is now "hello" (MemVault)
$nonce = sodium_increment($nonce);
($ct, my $mac) = secretbox_encrypt_detached("world", $nonce, $sk);
$pt = secretbox_decrypt_detached($ct, $mac, $nonce, $sk);
# $pt is now "world" (MemVault)DESCRIPTION
Encrypts a message with a key and a nonce to keep it confidential.
Computes an authentication tag. This tag is used to make sure that the message hasn't been tampered with before decrypting it.
A single key is used both to encrypt/authenticate and verify/decrypt messages. For this reason, it is critical to keep the key confidential.
The nonce doesn't have to be confidential, but it should never ever be reused with the same key. The easiest way to generate a nonce is to use "secretbox_nonce".
Messages encrypted are assumed to be independent. If multiple messages are sent using this API and random nonces, there will be no way to detect if a message has been received twice, or if messages have been reordered. If this is a requirement, see Crypt::Sodium::XS::secretstream.
FUNCTIONS
Nothing is exported by default. A :default tag imports the functions and constants as documented below. A separate import tag is provided for each of the primitives listed in "PRIMITIVES". For example, :xchacha20poly1305 imports secretbox_xchacha20poly1305_decrypt. You should use at least one import tag.
secretbox_decrypt
my $plaintext = secretbox_decrypt($ciphertext, $nonce, $key);Croaks on decryption failure.
NOTE: this is the libsodium function crypto_secretbox_open_easy. Its name is slightly different for consistency of this API.
secretbox_decrypt_detached
my $plaintext = secretbox_decrypt_detached($ciphertext, $mac, $nonce, $key);Croaks on decryption failure.
NOTE: this is the libsodium function crypto_secretbox_open_detached. Its name is slightly different for consistency of this API.
secretbox_encrypt
my $ciphertext = secretbox_encrypt($message, $nonce, $key);NOTE: this is the libsodium function crypto_secretbox_easy. Its name is slightly different for consistency of this API.
secretbox_encrypt_detached
my ($ciphertext, $mac) = secretbox_encrypt($message, $nonce, $key);NOTE: this is the libsodium function crypto_secretbox_detached. Its name is slightly different for consistency of this API.
secretbox_keygen
my $key = secretbox_keygen();secretbox_nonce
my $nonce = secretbox_nonce();
my $nonce = secretbox_nonce($base);CONSTANTS
secretbox_PRIMITIVE
my $default_primitive = secretbox_PRIMITIVE();secretbox_NONCEBYTES
my $nonce_length = secretbox_NONCEBYTES();secretbox_KEYBYTES
my $key_length = secretbox_KEYBYTES();secretbox_MACBYTES
my $mac_length = secretbox_MACBYTES();PRIMITIVES
All constants (except _PRIMITIVE) and functions have secretbox_<primitive>-prefixed counterparts (e.g., secretbox_xchachapoly1305_verify).
xchacha20poly1305
xsalsa20poly1305
SEE ALSO
- Crypt::Sodium::XS
- Crypt::Sodium::XS::OO::secretbox
- https://doc.libsodium.org/secret-key_cryptography/secretbox
FEEDBACK
For reporting bugs, giving feedback, submitting patches, etc. please use the following:
IRC channel
#sodiumonirc.perl.org.Email the author directly.
For any security sensitive reports, please email the author directly or contact privately via IRC.
AUTHOR
Brad Barden <perlmodules@5c30.org>
COPYRIGHT & LICENSE
Copyright (c) 2022 Brad Barden. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.