NAME

Crypt::Sodium::XS::OO::stream - Stream ciphers

SYNOPSIS

use Crypt::Sodium::XS::OO::stream;
my $stream = Crypt::Sodium::XS::OO::stream->new;
# or use the shortcut
# use Crypt::Sodium::XS;
# my $stream = Crypt::Sodium::XS->stream;

DESCRIPTION

These functions are stream ciphers. They do not provide authenticated encryption. They can be used to generate pseudo-random data from a key, or as building blocks for implementing custom constructions, but they are not alternatives to Crypt::Sodium::XS::OO::secretbox.

CONSTRUCTOR

new

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

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

ATTRIBUTES

primitive

my $primitive = $stream->primitive;
$stream->primitive('xchacha20');

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::stream->primitives;
my @primitives = $stream->primitives;

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

Can be called as a class method.

PRIMITIVE

my $primitive = $stream->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.

keygen

my $key = $stream->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 "KEYBYTES" bytes.

nonce

my $nonce = $stream->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.

stream

my $stream_data = $stream->stream($out_size, $nonce, $key);

$out_size is the desired size, in bytes, of stream data output.

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

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

Returns $out_size bytes of stream data.

xor

my $outdata = $stream->xor($indata, $nonce, $key, $flags);

$indata is the data to xor. It may be a Crypt::Sodium::XS::MemVault.

$nonce is the nonce used to xor the data. It must be "NONCEBYTES" bytes.

$key is the secret key used to xor the data. It must be "KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$flags is optional. If provided, the returned data will be a Crypt::Sodium::XS::MemVault, created with the given flags.

Returns the xor result. May be a Crypt::Sodium::XS::MemVault; see $flags above.

When using this method to decrypt data, $flags should be passed (even if 0 or undef) to ensure the decrypted data is protected with a Crypt::Sodium::XS::MemVault.

xor_ic

my $outdata
  = $stream->xor_ic($indata, $nonce, $internal_counter, $key, $flags);

Note: xor_ic is not supported with the salsa2012 primitive.

$indata is the data to xor. It may be a Crypt::Sodium::XS::MemVault.

$nonce is the nonce used to xor the data. It must be "NONCEBYTES" bytes.

$internal_counter is the initial value of the block counter.

$key is the secret key used to xor the data. It must be "KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$flags is optional. If provided, the returned data will be a Crypt::Sodium::XS::MemVault, created with the given flags.

Returns the xor result. May be a Crypt::Sodium::XS::MemVault; see $flags above.

"xor_ic" is similar to "xor" but adds the ability to set the initial value of the block counter ($internal_counter) to a non-zero value. This permits direct access to any block without having to compute the previous ones.

When using this method to decrypt data, $flags should be passed (even if 0 or undef) to ensure the decrypted data is protected with a Crypt::Sodium::XS::MemVault.

KEYBYTES

my $key_size = $stream->KEYBYTES;

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

MESSAGEBYTES_MAX

my $plaintext_max_size = $stream->MESSAGEBYTES_MAX;

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

NONCEBYTES

my $nonce_size = $stream->NONCEBYTES;

Returns the size, in bytes, of a nonce.

SEE ALSO

Crypt::Sodium::XS

Crypt::Sodium::XS::stream

"PRIMITIVES" in Crypt::Sodium::XS::stream

https://doc.libsodium.org/advanced/stream_ciphers

https://doc.libsodium.org/advanced/stream_ciphers/chacha20

https://doc.libsodium.org/advanced/stream_ciphers/xchacha20

https://doc.libsodium.org/advanced/stream_ciphers/salsa20

https://doc.libsodium.org/advanced/stream_ciphers/xsalsa20

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.

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.

cpanm Crypt::Sodium::XS

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