view release on metacpan or  search on metacpan

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

=head2 mv_from_hex

Shortcut to L</new_from_hex>.

=head2 mv_from_fd

Shortcut to L</new_from_fd>.

=head2 mv_from_file

Shortcut to L</new_from_file>.

=head2 mv_from_tty

Shortcut to L</new_from_tty>.

=head2 mv_from_ttyno

Shortcut to L</new_from_ttyno>.

=head1 METHODS

=head2 bitwise_and

=head2 bitwise_and_equals

=head2 bitwise_or

=head2 bitwise_or_equals

=head2 bitwise_xor

=head2 bitwise_xor_equals

  $mv2 = $mv->bitwise_and($bytes);
  $mv2 = $mv->bitwise_or($other_mv);

  $mv->bitwise_xor_equals($bytes);
  $mv->bitwise_and_equals($other_mv);

Modifies protected memory using the associated bitwise operation with the
provided argument. The argument must be the same size, in bytes, as the
protected memory.

The C<*_equals> functions modify in-place. Other functions return a new
L<Crypt::Sodium::XS::MemVault>.

=head2 clone

  my $new_mv = $mv->clone;

Returns a new object C<$new_mv> with identical flags and contents to the
original C<$mv>.

=head2 compare

B<!!WARNING!!>: The results of this comparison method can be used to leak
information about the protected memory. If one can make arbitrary comparisons
and has any visibility to the result, the protected data can be determined in
(nbits - trailing_zero_bits) iterations! For a 256-bit key, that means it takes
no more than 256 tries to extract the key. This method is fixed-time, but the
only safe use of the result is whether it equals 0 or not, and L</memcmp> is a
better way to determine equality.

  $mv->compare($bytes, $size);
  $mv->compare($other_mv, $size);

Returns C<0> if the bytes are equal, C<-1> if C<$mv> is less than C<$other_mv>
(or C<$bytes>), or C<1> if C<$mv> is greater. This method runs in fixed-time
(for a given size), and compares bytes as little-endian arbitrary-length
integers. Comparible to the C<cmp> perl operator.

C<$size> is optional iif C<$mv> and C<$other_mv> (or C<$bytes>) are equal
sizes. If provided, only C<$size> bytes are compared. B<Note>: Croaks if a
comparison is of unequal sizes and C<$size> was not provided, or if C<$size> is
larger than either of the operands.

Croaks if C<$mv> or C<$other_mv> is conceptually "locked". See L</lock> and
L</unlock>.

B<Note>: This method is similar to L<memcmp(3)>; that is, it returns -1, 0, or
1 for the comparison results. For simple true/false equality comparisons, see
L</memcmp>. The naming is chosen here to be consistent with libsodium.

=head2 concat

  my $new_mv = $mv->concat($bytes);
  my $new_mv = $mv->concat($other_mv);

Returns a new L<Crypt::Sodium::Memvault> with the concatenated contents of
C<$mv> followed by C<$bytes> or the contents of C<$other_mv>. The new object's
flags will be the combined restrictions of C<$mv> and C<$new_mv>.

=head2 concat_inplace

  $mv->concat_inplace($appended_bytes);
  $mv->concat_inplace($another_mv);

Appends C<$appended_bytes> or the contents of C<$another_mv> to the end of
<$mv>. Returns C<$mv>.

=head2 flags

  my $flags = $mv->flags;
  $mv->flags($new_flags);

Return or set memory protection flags. See L<Crypt::Sodium::XS::ProtMem>.

=head2 from_base64

Shortcut for L<Crypt::Sodium::XS::MemVault/new_from_base64>.

=head2 from_hex

Shortcut for L<Crypt::Sodium::XS::MemVault/new_from_hex>.

=head2 index

B<!!WARNING!!>: This method does not run in constant-time and may leak
information about the protected memory.