NAME

Crypt::Sodium::XS::OO::box - Asymmetric (public/secret key) authenticated encryption

SYNOPSIS

use Crypt::Sodium::XS;
use Crypt::Sodium::XS::Util "sodium_increment";

my $box = Crypt::Sodium::XS->box;

my ($pk, $sk) = $box->keypair;
my ($pk2, $sk2) = $box->keypair;
my $nonce = $box->nonce;

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

$nonce = sodium_increment($nonce);
($ct, my $tag) = $box->encrypt_detached("world", $nonce, $pk, $sk2);
$pt = $box->decrypt_detached($ct, $tag, $nonce, $pk2, $sk);
# $pt is now "world" (MemVault)

my $precalc = $box->beforenm($pk2, $sk);
my $precalc2 = $box->beforenm($pk, $sk2);
# $precalc and $precalc2 hold identical derived secret keys

$nonce = $box->nonce();
$ct = $precalc->encrypt("goodbye", $nonce);
$pt = $precalc2->decrypt($ct, $nonce);
# $pt is now "goodbye" (MemVault)

$ct = box_seal_encrypt("anonymous message", $pk2);
$pt = box_seal_decrypt($ct, $sk, $pk);

DESCRIPTION

Using public-key authenticated encryption, Alice can encrypt a confidential message specifically for Bob, using Bob's public key.

Based on Bob's public key, Alice can compute a shared secret key. Using Alice's public key and his secret key, Bob can compute the exact same shared secret key. That shared secret key can be used to verify that the encrypted message was not tampered with, before eventually decrypting it.

In order to send messages to Bob, Alice only needs Bob's public key. Bob should never ever share his secret key (not even with Alice).

For verification and decryption, Bob only needs Alice's public key, the nonce and the ciphertext. Alice should never ever share her secret key either, even with Bob.

Bob can reply to Alice using the same system, without having to generate a distinct key pair. The nonce doesn't have to be confidential, but it must be used with just one invocation of "encrypt" for a particular pair of public and secret keys.

One easy way to generate a nonce is to use "nonce", considering the size of the nonces the risk of any random collisions is negligible. For some applications, if you wish to use nonces to detect missing messages or to ignore replayed messages, it is also acceptable to use a simple incrementing counter as a nonce. A better alternative for that use case is the Crypt::Sodium::XS::OO::secretstream API.

When doing so you must ensure that the same nonce can never be re-used (for example you may have multiple threads or even hosts generating messages using the same key pairs).

As stated above, senders can decrypt their own messages, and compute a valid authentication tag for any messages encrypted with a given shared secret key. This is generally not an issue for online protocols. If this is not acceptable, check out "SEALED BOXES", as well as Crypt::Sodium::XS::OO::kx.

CONSTRUCTOR

new

my $box = Crypt::Sodium::XS::OO::box->new;
my $primitive = 'curve25519xsalsa20poly1305';
my $box = Crypt::Sodium::XS::OO::box->new(primitive => $primitive);
my $box = Crypt::Sodium::XS->box;

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

ATTRIBUTES

primitive

my $primitive = $box->primitive;
$box->primitive('curve25519xsalsa20poly1305');

Gets or sets the primitive used for all operations by this object. Note this can be default.

METHODS

primitives

my @primitives = Crypt::Sodium::XS::OO::box->primitives;
my @primitives = $box->primitives;

Returns a list of all supported primitive names, including default.

Can be called as a class method.

PRIMITIVE

my $primitive = $box->PRIMITIVE;

Returns the primitive used for all operations by this object. Note this will never be default but would instead be the primitive it represents.

beforenm

my $precalc = $box->beforenm($their_public_key, $my_secret_key, $flags);

$their_public_key is the public key used by the precalcuation object. It must be "PUBLICKEYBYTES" bytes.

$my_secret_key is the secret key used by the precalculation object. It must be "KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$flags is optional. It is the flags used for the precalculation protected memory object. See Crypt::Sodium::XS::ProtMem.

Returns an opaque protected memory object: a precalculation box object. This is useful if you send or receive many messages using the same public key. See "PRECALCULATION INTERFACE".

decrypt

my $plaintext = $box->decrypt(
  $ciphertext,
  $nonce,
  $their_public_key,
  $my_secret_key,
  $flags
);

Croaks on decryption failure.

$ciphertext is the ciphertext to decrypt.

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

$their_public_key is the public key used to authenticate the ciphertext. It must be "PUBLICKEYBYTES" bytes.

$my_secret_key is the secret key used to decrypt the ciphertext. It must be "SECRETKEYBYTES" 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_box_open_easy. Its name is slightly different for consistency of this API.

decrypt_detached

my $plaintext = $box->decrypt_detached(
  $ciphertext,
  $tag,
  $nonce,
  $their_public_key,
  $my_secret_key,
  $flags
);

Croaks on decryption failure.

$ciphertext is the ciphertext to decrypt.

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

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

$their_public_key is the public key used to authenticate the ciphertext. It must be "PUBLICKEYBYTES" bytes.

$my_secret_key is the secret key used to decrypt the ciphertext. It must be "SECRETKEYBYTES" 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_box_open_detached. Its name is slightly different for consistency of this API.

encrypt

my $ciphertext
  = $box->encrypt($message, $nonce, $their_public_key, $my_secret_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 "NONCEBYTES" bytes.

$their_public_key is the public key used to encrypt the ciphertext. It must be "PUBLICKEYBYTES" bytes.

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

Returns the encrypted ciphertext.

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

encrypt_detached

my ($ciphertext, $tag) = $box->encrypt_detached(
  $message,
  $nonce,
  $their_public_key,
  $my_secret_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 "NONCEBYTES" bytes.

$their_public_key is the public key used to encrypt the ciphertext. It must be "PUBLICKEYBYTES" bytes.

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

Returns the encrypted ciphertext and its authentication tag.

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

keypair

my ($public_key, $secret_key) = $box->keypair($seed, $flags);

$seed is optional. It must be "SEEDBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault. Using the same seed will generate the same key pair, so it must be kept confidential. If omitted, a key pair is randomly generated.

$flags is optional. It is the flags used for the $secret_key Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.

Returns a public key of "PUBLICKEYBYTES" bytes and a Crypt::Sodium::XS::MemVault: the secret key of "SECRETKEYBYTES" bytes.

nonce

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

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

Returns a nonce of "NONCEBYTES" bytes.

BEFORENMBYTES

my $shared_key_size = $box->BEFORENMBYTES;

Returns the size, in bytes, of the pre-calculated state created by "beforenm". Not normally needed.

MACBYTES

my $tag_size = $box->MACBYTES;

Returns the size, in bytes, of a message authentication tag.

The size of a combined (not detached) ciphertext is message size + "MACBYTES".

MESSAGEBYTES_MAX

my $message_max_size = $box->MESSAGEBYTES_MAX;

Returns the size, in bytes, of the maximum size of any message to be encrypted.

NONCEBYTES

my $nonce_size = $box->NONCEBYTES;

Returns the size, in bytes, of a nonce.

PUBLICKEYBYTES

my $public_key_size = $box->PUBLICKEYBYTES;

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

SEALBYTES

my $seal_size = $box->SEALBYTES;

Returns the size, in bytes, of the "seal" attached to a sealed box. The size of a sealed box is the message size + "SEALBYTES".

SECRETKEYBYTES

my $secret_key_size = $box->SECRETKEYBYTES;

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

SEEDBYTES

my $keypair_seed_size = $box->SEEDBYTES;

Returns the size, in bytes, of a seed used by "keypair".

SEALED BOXES

Sealed boxes are designed to anonymously send messages to a recipient given their public key.

Only the recipient can decrypt these messages using their private key. While the recipient can verify the integrity of the message, they cannot verify the identity of the sender.

A message is encrypted using an ephemeral key pair, with the secret key being erased right after the encryption process.

Without knowing the secret key used for a given message, the sender cannot decrypt the message later. Furthermore, without additional data, a message cannot be correlated with the identity of its sender.

seal_decrypt

my $plaintext
  = $box->seal_decrypt($ciphertext, $my_public_key, $my_secret_key, $flags);

Croaks on decryption failure.

$ciphertext is the ciphertext to decrypt.

$my_public_key is the public key to which the message was encrypted. It must be "PUBLICKEYBYTES" bytes.

$my_secret_key is the secret key from which the public key is derived. It must be "SECRETKEYBYTES" 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.

This method doesn’t require passing the public key of the sender as the ciphertext already includes this information. It requires passing $my_public_key as the anonymous sender and recipient public keys are used to generate a nonce.

Note: this is the libsodium function crypto_box_seal_open. Its name is slightly different for consistency of this API.

seal_encrypt

my $ciphertext = $box->seal_encrypt($message, $their_public_key);

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

$their_public_key is the public key to which the message is encrypted. It must be "PUBLICKEYBYTES" bytes.

Returns the combined ciphertext.

The function creates a new key pair for each message and attaches the public key to the ciphertext. The secret key is overwritten and is not accessible after this function returns.

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

PRECALCULATION INTERFACE

Applications that send several messages to the same recipient or receive several messages from the same sender can improve performance by calculating the shared key only once, via the precalculation interface.

A precalculated box object is created by calling the "beforenm" method. It is an opaque object which provides the following methods:

decrypt

my $plaintext = $precalc->decrypt($ciphertext, $nonce, $flags);

Croaks on decryption failure.

$ciphertext is the ciphertext to decrypt.

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

$their_public_key is the public key derived from the secret key used to encrypt the ciphertext. It must be "PUBLICKEYBYTES" bytes.

$my_secret_key is the secret key from which was derived the public key used to encrypt the ciphertext. It must be "SECRETKEYBYTES" 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.

decrypt_detached

my $plaintext = $precalc->decrypt_detached($ciphertext, $tag, $nonce, $flags);

Croaks on decryption failure.

$ciphertext is the ciphertext to decrypt.

$tag is the ciphertext's authentication tag.

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

$their_public_key is the public key derived from the secret key used to encrypt the ciphertext. It must be "PUBLICKEYBYTES" bytes.

$my_secret_key is the secret key from which was derived the public key used to encrypt the ciphertext. It must be "SECRETKEYBYTES" 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.

encrypt

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

$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 "NONCEBYTES" bytes.

Returns the encrypted ciphertext.

encrypt_detached

my ($ciphertext, $tag) = $precalc->encrypt($message, $nonce);

$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 "NONCEBYTES" bytes.

Returns the encrypted ciphertext and its authentication tag.

FEEDBACK

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

RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS
IRC channel #sodium on irc.perl.org.
Email the author directly.

AUTHOR

Brad Barden <perlmodules@5c30.org>

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Crypt::Sodium::XS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Crypt::Sodium::XS

CPAN shell

perl -MCPAN -e shell
install Crypt::Sodium::XS

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

new

ATTRIBUTES

primitive

METHODS

primitives

PRIMITIVE

beforenm

decrypt

decrypt_detached

encrypt

encrypt_detached

keypair

nonce

BEFORENMBYTES

MACBYTES

MESSAGEBYTES_MAX

NONCEBYTES

PUBLICKEYBYTES

SEALBYTES

SECRETKEYBYTES

SEEDBYTES

SEALED BOXES

seal_decrypt

seal_encrypt

PRECALCULATION INTERFACE

SEE ALSO

FEEDBACK

AUTHOR

COPYRIGHT & LICENSE

Module Install Instructions