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

NAME

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

SYNOPSIS

use Crypt::Sodium::XS::OO::secretbox;
my $sbox = Crypt::Sodium::XS::OO::secretbox->new;
# or use the shortcut
# use Crypt::Sodium::XS;
# my $sbox = Crypt::Sodium::XS->secretbox;
use Crypt::Sodium::XS "sodium_increment";

my $sk = $sbox->keygen;
my $nonce = $sbox->nonce;

my $ct = $sbox->encrypt("hello", $nonce, $sk);
my $pt = $sbox->decrypt($ct, $nonce, $sk);
# $pt is now "hello" (MemVault)

$nonce = sodium_increment($nonce);
($ct, my $mac) = $sbox->encrypt_detached("world", $nonce, $sk);
$pt = $sbox->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 "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.

CONSTRUCTOR

new

my $sbox = Crypt::Sodium::XS::OO::secretbox->new;
my $sbox
  = Crypt::Sodium::XS::OO::secretbox->new(primitive => 'xsalsa20poly1305');
my $sbox = Crypt::Sodium::XS->secretbox;

Returns a new secretbox object for the given primitive. If not given, the default primitive is default.

METHODS

PRIMITIVE

my $default_primitive = $sbox->PRIMITIVE;

NONCEBYTES

my $nonce_length = $sbox->NONCEBYTES;

KEYBYTES

my $key_length = $sbox->KEYBYTES;

MACBYTES

my $mac_length = $sbox->MACBYTES;

primitives

my @primitives = $pwhash->primitives;

Returns a list of all supported primitive names (including 'default').

decrypt

my $plaintext = $sbox->decrypt($ciphertext, $nonce, $key);

Croaks on decryption failure.

decrypt_detached

my $plaintext = $sbox->decrypt_detached($ciphertext, $mac, $nonce, $key);

Croaks on decryption failure.

encrypt

my $ciphertext = $sbox->encrypt($message, $nonce, $key);

encrypt_detached

my ($ciphertext, $mac) = $sbox->encrypt($message, $nonce, $key);

keygen

my $key = $sbox->keygen;

nonce

my $nonce = $sbox->nonce;
my $nonce = $sbox->nonce($base);

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::secretbox
https://doc.libsodium.org/secret-key_cryptography/secretbox

FEEDBACK

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

  • IRC channel #sodium on irc.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.