view release on metacpan or  search on metacpan

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

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

=head2 MESSAGEBYTES_MAX

  my $message_max_size = $sstream->MESSAGEBYTES_MAX;

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

=head2 TAG_MESSAGE

  my $message_tag = $sstream->TAG_MESSAGE;

Returns the tag value for a TAG_MESSAGE secretstream tag.

=head2 TAG_PUSH

  my $push_tag = $sstream->TAG_PUSH;

Returns the tag value for a TAG_PUSH secretstream tag.

=head2 TAG_REKEY

  my $rekey_tag = $sstream->TAG_REKEY;

Returns the tag value for a TAG_REKEY secretstream tag.

=head2 TAG_FINAL

  my $final_tag = $sstream->TAG_FINAL;

Returns the tag value for a TAG_FINAL secretstream tag.

=head1 STREAM INTERFACE

=head2 OVERVIEW

An encrypted stream starts with a short header, whose size is L</HEADERBYTES>
bytes. That header must be sent/stored before the sequence of encrypted
messages, as it is required to decrypt the stream. The header content doesn’t
have to be secret and decryption with a different header would fail.

A tag is attached to each message. That tag can be any of:

=over 4

=item 0, or L</TAG_MESSAGE>

The most common tag, that doesn’t add any information about the nature of the
message.

=item L</TAG_FINAL>

Indicates that the message marks the end of the stream, and erases the secret
key used to encrypt the previous sequence.

=item L</TAG_PUSH>

Indicates that the message marks the end of a set of messages, but not the end
of the stream. For example, a huge JSON string sent as multiple chunks can use
this tag to indicate to the application that the string is complete and that it
can be decoded. But the stream itself is not closed, and more data may follow.

=item L</TAG_REKEY>

“Forget” the key used to encrypt this message and the previous ones, and derive
a new secret key.

=back

A typical encrypted stream simply attaches 0 as a tag to all messages, except
the last one which is tagged as TAG_FINAL.

Note that tags are encrypted; encrypted streams do not reveal any information
about sequence boundaries (PUSH and REKEY tags).

For each message, additional data can be included in the computation of the
authentication tag. With this API, additional data is rarely required, and most
applications can just omit it.

=head2 ENCRYPTION

The L</init_encrypt> method takes a shared secret key returns a header and a
secretstream encryption object. This is an opaque object with the following
methods:

=over 4

=item encrypt

  my $ciphertext = $sstream_enc->encrypt($plaintext, $tag, $adata);

C<$plaintext> is the plaintext to encrypt. It may be a
L<Crypt::Sodium::XS::MemVault>.

C<$tag> is optional. It is the tag value attached to the message. If not
provided, it defaults to L</TAG_MESSAGE>. The most common use is a tag of
L</TAG_FINAL> to indicate the last message in a stream. See L</OVERVIEW>.

C<$adata> is optional. If provided, it must match the additional data that was
used when encrypting this message. It is rarely needed with the secretstream
interface.

Returns the encrypted ciphertext.

=back

=head2 DECRYPTION

The L</init_decrypt> method is the decryption counterpart for the receiving end
of a stream. It takes a header and a secret key; the key must match the one
used to create the encryption object, and the header must match the one that
was returned when it was created. It returns a secretstream decryption object.
This is an opaque object with the following methods:

=over 4

=item decrypt

  my $plaintext = $sstream_dec->decrypt($ciphertext, $adata);
  my ($plaintext, $tag) = $sstream_dec->decrypt($ciphertext, $adata);