/ 
Crypt-Sodium-XS-0.000039
River stage zero No dependents
/ Crypt::Sodium::XS::secretbox

NAME

Crypt::Sodium::XS::secretbox - Secret key authenticated encryption

SYNOPSIS

use Crypt::Sodium::XS::secretbox ":default";
use Crypt::Sodium::XS::Util "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 $tag) = secretbox_encrypt_detached("world", $nonce, $sk);
$pt = secretbox_decrypt_detached($ct, $tag, $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

secretbox_<primitive>_decrypt

my $plaintext = secretbox_decrypt($ciphertext, $nonce, $key);

Croaks on decryption failure.

$ciphertext is the combined ciphertext to decrypt.

$nonce is the nonce used to encrypt the ciphertext. It must be "secretbox_NONCEBYTES" bytes.

$key is the secret key used to encrypt the ciphertext. It must be "secretbox_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$flags is optional. It is the flags used for the $plaintext Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::Protmem.

Returns a Crypt::Sodium::XS::MemVault: the decrypted plaintext.

NOTE: this is the libsodium function crypto_secretbox_open_easy. Its name is slightly different for consistency of this API.

secretbox_decrypt_detached

secretbox_<primitive>_decrypt_detached

my $plaintext = secretbox_decrypt_detached($ciphertext, $tag, $nonce, $key);

Croaks on decryption failure.

$ciphertext is the detached ciphertext to decrypt.

$tag is the ciphertext's authentication tag. It must be "secretbox_MACBYTES" bytes.

$nonce is the nonce used to encrypt the ciphertext. It must be "secretbox_NONCEBYTES" bytes.

$key is the secret key used to encrypt the ciphertext. It must be "secretbox_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$flags is optional. It is the flags used for the $plaintext Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::Protmem.

Returns a Crypt::Sodium::XS::MemVault: the decrypted plaintext.

NOTE: this is the libsodium function crypto_secretbox_open_detached. Its name is slightly different for consistency of this API.

secretbox_encrypt

secretbox_<primitive>_encrypt

my $ciphertext = secretbox_encrypt($message, $nonce, $key);

$message is the message to encrypt. It may be a Crypt::Sodium::XS::MemVault.

$nonce is the nonce used to encrypt the ciphertext. It must be "secretbox_NONCEBYTES" bytes.

$key is the secret key used to encrypt the ciphertext. It must be "secretbox_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

Returns the encrypted ciphertext.

NOTE: this is the libsodium function crypto_secretbox_easy. Its name is slightly different for consistency of this API.

secretbox_encrypt_detached

secretbox_<primitive>_encrypt_detached

my ($ciphertext, $tag) = secretbox_encrypt($message, $nonce, $key);

$message is the message to encrypt. It may be a Crypt::Sodium::XS::MemVault.

$nonce is the nonce used to encrypt the ciphertext. It must be "secretbox_NONCEBYTES" bytes.

$key is the secret key used to encrypt the ciphertext. It must be "secretbox_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

Returns the encrypted ciphertext and its authentication tag.

NOTE: this is the libsodium function crypto_secretbox_detached. Its name is slightly different for consistency of this API.

secretbox_keygen

secretbox_<primitive>_keygen

my $key = secretbox_keygen($flags);

$flags is optional. It is the flags used for the $key Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::Protmem.

Returns a Crypt::Sodium::XS::MemVault: a secret key of "secretbox_KEYBYTES" bytes.

secretbox_nonce

secretbox_<primitive>_nonce

my $nonce = secretbox_nonce();
my $nonce = secretbox_nonce($base);

$base is optional. It must be less than or equal to "secretbox_NONCEBYTES" bytes. If not provided, the nonce will be random.

Returns a nonce of "secretbox_NONCEBYTES" bytes.

CONSTANTS

secretbox_PRIMITIVE

my $default_primitive = secretbox_PRIMITIVE();

Returns the name of the default primitive.

secretbox_NONCEBYTES

secretbox_<primitive>_NONCEBYTES

my $nonce_size = secretbox_NONCEBYTES();

Returns the size, in bytes, of a nonce.

secretbox_KEYBYTES

secretbox_<primitive>_KEYBYTES

my $key_size = secretbox_KEYBYTES();

Returns the size, in bytes, of a secret key.

secretbox_MACBYTES

secretbox_<primitive>_MACBYTES

my $tag_size = secretbox_MACBYTES();

Returns the size, in bytes, of an authentication tag.

PRIMITIVES

All constants (except _PRIMITIVE) and functions have secretbox_<primitive>-prefixed counterparts (e.g., secretbox_xchachapoly1305_verify).

  • xchacha20poly1305

  • xsalsa20poly1305 (default)

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:

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.