view release on metacpan or  search on metacpan

lib/Crypt/Sodium/XS/secretstream.pm  view on Meta::CPAN

  if ($tag == $sstream->TAG_MESSAGE) {
    # default, most common tag
  }
  elsif ($tag == $sstream->TAG_PUSH) {
    # in-band mark for application to delimit related messages
  }
  elsif ($tag == $sstream->TAG_REKEY) {
    # re-keying after this message was triggered by sender
  }
  elsif ($tag == $sstream->TAG_FINAL) {
    # last message
  }

=head1 DESCRIPTION

L<Crypt::Sodium::XS::secretstream> encrypts a sequence of messages, or a single
message split into an arbitrary number of chunks, using a secret key, with the
following properties:

=over 4

=item *

Messages cannot be truncated, removed, reordered, duplicated or modified
without this being detected by the decryption functions.

=item *

The same sequence encrypted twice will produce different ciphertexts.

=item *

An authentication tag is added to each encrypted message: stream corruption
will be detected early, without having to read the stream until the end.

=item *

Each message can include additional data (ex: timestamp, protocol version) in
the computation of the authentication tag.

=item *

Messages can have different sizes.

=item *

There are no practical limits to the total length of the stream, or to the
total number of individual messages.

=item *

Ratcheting: at any point in the stream, it is possible to "forget" the key used
to encrypt the previous messages, and switch to a new key.

=back

L<Crypt::Sodium::XS::secretstream> can be used to securely send an ordered
sequence of messages to a peer. Since the length of the stream is not limited,
it can also be used to encrypt files regardless of their size.

It transparently generates nonces and automatically handles key rotation.

=head1 CONSTRUCTOR

The constructor is called with the C<Crypt::Sodium::XS-E<gt>secretstream>
method.

  my $sstream = Crypt::Sodium::XS->secretstream;
  my $sstream
    = Crypt::Sodium::XS->secretstream(primitive => 'xchacha20poly1305');

Returns a new secretstream object. The primitive attribute is required.

Implementation detail: the returned object is blessed into
C<Crypt::Sodium::XS::OO::secretstream>.

=head1 ATTRIBUTES

=head2 primitive

  my $primitive = $sstream->primitive;
  $sstream->primitive('xchacha20poly1305');

Gets or sets the primitive used for all operations by this object. Must be one
of the primitives listed in L</PRIMITIVES>. For this module there is no
C<default> primitive, and this attribute is always identical to L</PRIMITIVE>.

=head1 METHODS

=head2 primitives

  my @primitives = $sstream->primitives;
  my @primitives = Crypt::Sodium::XS::secretstream->primitives;

Returns a list of all supported primitive names.

Can be called as a class method.

=head2 PRIMITIVE

  my $primitive = $sstream->PRIMITIVE;

Returns the primitive used for all operations by this object. For this module,
always identical to the L</primitive> attribute.

=head2 init_decrypt

  my $sstream_dec = $sstream->init_decrypt($header, $key, $flags);

C<$header> is an opaque header of L</HEADERBYTES> bytes generated by a previous
call to L</init_encrypt>.

C<$key> is a shared secret key. It must be L</KEYBYTES> bytes. It may be a
L</Crypt::Sodium::XS::MemVault>.

C<$flags> is optional. It is the flags used for the secretstream decryption
protected memory object. See L<Crypt::Sodium::XS::ProtMem>.

Returns an opaque protected memory object: a secretstream decryption object.

See L</STREAM INTERFACE>.