view release on metacpan or  search on metacpan

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

  $key->to_file("/some/path");
  print "hex: ", $key->to_hex->unlock, "\n";
  print "base64: ", $key->to_base64->unlock, "\n";

  my $key2 = mv_from_file("/other/path");

  if ($key1->memcmp($key2)) {
    die "randomly generated key matches loaded key: inconceivable!";
  }

  my $mv = mv_new("hello");

  my $extracted_data_mv = $mv->extract(1, 3); # "ell"
  print $extracted_data_mv->unlock, "\n";
  undef $extracted_data_mv;

  $mv->unlock;
  my $mv2 = $mv->clone; # unlocked clone is unlocked
  $mv2->xor_equals("\x{1f}\x{0a}\x{1e}\x{00}\x{0b}");
  print "$mv, $mv2!\n";
  my $colon_idx = $mv->index('ll'); # 2
  my $unlocked_mv = $mv->clone;
  $mv->lock;

=head1 DESCRIPTION

L<Crypt::Sodium::XS::MemVault> is the container for protected memory objects in
L<Crypt::Sodium::XS> which can be accessed from perl. It has constructors which
can read in the sensitive data without going through perl. It also provides
methods for manipulating the data while it remains only in protected memory.
These methods (except L</index>) are time-dependent only on the size of
protected data, not its content, so using them should not create any
sidechannels.

Memory protections are documented in L<Crypt::Sodium::XS::ProtMem>.

=head1 CONSTRUCTORS

=head2 new

  my $mv = Crypt::Sodium::XS::MemVault->new($bytes, $flags);

C<$bytes> is an arbitrary string of bytes.

C<$flags> is optional. It is the L<flags|Crypt::Sodium::XS::ProtMem/FLAGS> of
the newly-created MemVault object. If not provided, the default is
L<Crypt::Sodium::XS::ProtMem/protmem_flags_memvault_default>.

Returns a L<Crypt::Sodium::XS::MemVault>: the content of C<$bytes>.

=head2 new_from_hex

  my $mv = Crypt::Sodium::XS::MemVault->new_from_hex($hex_string, $flags);

C<$hex_string> is an arbitrary length string. Decoding of C<$hex_string> will
stop at the first non-hex character.

C<$flags> is optional. If not provided, the default is
L<Crypt::Sodium::XS::ProtMem/protmem_flags_memvault_default>.

Returns a L<Crypt::Sodium::XS::MemVault>: the decoded content of
C<$hex_string>.

=head2 new_from_base64

  my $mv
    = Crypt::Sodium::XS::MemVault->new_from_base64($base64, $variant, $flags);

C<$base64> is an arbitrary length string. Decoding of C<$base64> will stop at
the first non-base64 character.

C<$variant> is optional. If not provided, the default is
L<Crypt::Sodium::XS::Base64/BASE64_VARIANT_URLSAFE_NO_PADDING>. See
L<Crypt::Sodium::XS::Base64/CONSTANTS>.

C<$flags> is optional. It is the L<flags|Crypt::Sodium::XS::ProtMem/FLAGS> of
the newly-created MemVault object. If not provided, the default is
L<Crypt::Sodium::XS::ProtMem/protmem_flags_memvault_default>.

Returns a L<Crypt::Sodium::XS::MemVault>: the decoded content of C<$base64>.

=head2 new_from_file

  my $mv = Crypt::Sodium::XS::MemVault->new_from_file($path, $size, $flags);

C<$path> is a filesystem path.

C<$size> is optional. It is the B<maximum> number of bytes to read from C<$fd>.
If not provided or it numifies to 0, C<$fd> will be read until end-of-file.

C<$flags> is optional. It is the L<flags|Crypt::Sodium::XS::ProtMem/FLAGS> of
the newly-created MemVault object. If not provided, the default is
L<Crypt::Sodium::XS::ProtMem/protmem_flags_memvault_default>.

Returns a L<Crypt::Sodium::XS::MemVault>: the bytes read from the file located
at C<$path>, B<up to> C<$size> bytes or until end-of-file if C<$size> is 0.

Croaks on failure to open or read C<$path>.

=head2 new_from_tty

  my $mv = Crypt::Sodium::XS::MemVault->new_from_tty($path, $prompt, $flags);

C<$path> is optional. It is a filesystem path naming a TTY device. If not
provided, the default is the controlling tty for the process.

C<$prompt> is optional. It will be printed to the tty before reading input. If
not provided, the default is C<Password: >.

C<$flags> is optional. It is the L<flags|Crypt::Sodium::XS::ProtMem/FLAGS> of
the newly-created MemVault object. If not provided, the default is
L<Crypt::Sodium::XS::ProtMem/protmem_flags_memvault_default>.

Returns a L<Crypt::Sodium::XS::MemVault>: one line of input read from the TTY
device at C<$path>. The end-of-line character is not be included.

Echo will be disabled during input, making this appropriate for password input.

Croaks on failure.

=head1 FUNCTIONS

Nothing is exported by default. A C<:constructors> tag imports the
L</CONSTRUCTOR FUNCTIONS>. A C<:all> tag imports everything.

=head2 CONSTRUCTOR FUNCTIONS

=head2 mv_new

Shortcut to L</new>.

=head2 mv_from_base64

Shortcut to L</new_from_base64>.

=head2 mv_from_hex

Shortcut to L</new_from_hex>.

=head2 mv_from_fd