/ 
Crypt-Sodium-XS-0.000018
River stage zero No dependents
/ Crypt::Sodium::XS::MemVault

NAME

Crypt::Sodium::XS::MemVault - Protected memory objects

SYNOPSIS

use Crypt::Sodium::XS::MemVault;

...

DESCRIPTION

CONSTRUCTORS

new

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

$flags is optional (default: "protmem_flags_memvault_default" in Crypt::Sodium::XS::ProtMem).

new_from_hex

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

$flags is optional (default: "protmem_flags_memvault_default" in Crypt::Sodium::XS::ProtMem).

new_from_base64

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

$variant is optional (default: "BASE64_VARIANT_URLSAFE_NO_PADDING" in Crypt::Sodium::XS::Base64). See "CONSTANTS" in Crypt::Sodium::XS::Base64.

$flags is optional (default: "protmem_flags_memvault_default" in Crypt::Sodium::XS::ProtMem).

new_from_file

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

$flags is optional (default: "protmem_flags_memvault_default" in Crypt::Sodium::XS::ProtMem).

new_from_fd

my $mv = Crypt::Sodium::XS::MemVault->new_from_fd(fileno($fh), $flags);

Note: this requires the file descriptor number, not a perl file handle.

$flags is optional (default: "protmem_flags_memvault_default" in Crypt::Sodium::XS::ProtMem).

METHODS

is_locked

my $is_locked = $mv->is_locked;

Returns a boolean indicating if the object is conceptually "locked."

clone

my $new_mv = $mv->clone;

Returns a new object $new_mv with identical contents to the original $mv.

concat

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

Returns a new object with the concatenated contents of $mv followed by $bytes or the contents of $other_mv.

compare

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

Fixed-time (for a given length) comparison of bytes as little-endian arbitrary-length integers. Returns 0 if the bytes are equal, -1 if $mv is less than $other_mv (or $bytes), or 1 if $mv is greater. Comparible to the cmp perl operator.

$length is optional iif $mv and $other_mv (or $bytes) are equal lengths. If provided, only $length bytes are compared.

flags

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

Return or set memory protection flags. See "MEMORY SAFETY" in Crypt::Sodium::XS::ProtMem.

from_base64

# shortcut for Crypt::Sodium::XS::MemVault->new_from_base64($mv, ..);
my $new_mv = $mv->from_base64($variant, $flags);

$variant is optional (default: "BASE64_VARIANT_URLSAFE_NO_PADDING" in Crypt::Sodium::XS::Base64). See "CONSTANTS" in Crypt::Sodium::XS::BASE64.

$flags is optional. If not provided, the new MemVault will use the same flags as the one from which it is created.

Stops parsing at the first non-base64 byte (valid characters depend on $variant). $new_mv will be empty if the data cannot be parsed as valid base64 (i.e., the output would not be a multiple of 8 bits).

from_hex

# shortcut for Crypt::Sodium::XS::MemVault->new_from_hex($mv, ..);
my $new_mv = $mv->from_hex($flags);

$flags is optional. If not provided, the new MemVault will use the same flags as the one from which it is created.

Stops parsing at the first non-hex ([0-9a-f] case insensitive) byte.

index

my $pos = $mv->index($substr, $offset);

WARNING: this method does NOT run in constant-time!

Searches for an occurence of $substr in protected memory. This is similar to perl's own index function. Returns the first match of $substr at or after $offset, or -1 if $substr is not found.

$offset is optional. If not provided, the search will begin at the start of the protected memory. Unlike perl's index function, $offset may not be negative, and the method will croak if offset is beyond the last byte of protected memory.

This method should only be used when protected memory starts with non-sensitive data, and is guaranteed to find $substr before any sensitive data.

is_zero

my $is_null = $mv->is_zero;

Returns a boolean indicating if the protected memory consists of all null bytes. Runs in constant time for a given length.

length

my $length = $mv->length;

Returns the byte length of the protected memory. Runtime does not depend on data.

lock

$mv->lock;

Conceptually "lock" the object. This prevents access to the protected memory from perl (e.g., the object cannot be stringified, and attempting to do so will croak).

memcmp

$mv->memcmp($bytes, $length);
$mv->memcmp($other_mv, $length);

Fixed-time (for a given length) comparison of bytes as little-endian arbitrary-length integers. Returns true if the bytes are equal, false otherwise.

$length is optional iif $mv and $other_mv (or $bytes) are equal lengths. If provided, only $length bytes are compared.

to_fd

$mv->to_fd(fileno($fh));
close($fh) or die "error: $!";

Returns number of bytes written. Croaks on failure.

to_file

$mv->to_file($path);

Returns number of bytes written. Croaks on failure.

to_base64

my $new_mv = $mv->to_base64($variant);

Returns a new Crypt::Sodium::XS::MemVault with the contents encoded in base64.

$variant is optional (default: "BASE64_VARIANT_URLSAFE_NO_PADDING" in Crypt::Sodium::XS::Base64). See "CONSTANTS" in Crypt::Sodium::XS::Base64.

to_hex

my $new_mv = $mv->to_hex;

Returns a new Crypt::Sodium::XS::MemVault with the contents encoded as a hexadecimal string.

unlock

$mv->unlock;

Conceptually "unlock" the object. This allows access to the protected memory from perl (e.g., the object can be stringified).

memzero

$mv->memzero;

Overwrites protected memory with null bytes.

You may not need to call this yourself; unless using both of the non-default flags "PROTMEM_FLAGS_MALLOC_PLAIN" in Crypt::Sodium::XS::ProtMem and "PROTMEM_FLAGS_MEMZERO_DISABLED" in Crypt::Sodium::XS::ProtMem (or "PROTMEM_ALL_DISABLED" in Crypt::Sodium::XS::ProtMem), the memory is zeroed when the object is destroyed.

xor

$mv->xor($bytes);
$mv->xor($other_mv);

Modifies protected memory using the exclusive-or operation with the provided argument. The argument must be the same number of bytes in length as the protected memory.

OVERLOADS

boolean

my $is_empty = !$mv;
my $is_not_empty = !!$mv;

eq

my $is_equal = $mv eq $bytes;
my $is_equal = $bytes eq $mv;
my $is_equal = $mv eq $other_mv;

ne

my $not_equal = $mv ne $bytes;
my $not_equal = $bytes ne $mv;
my $not_equal = $mv ne $other_mv;

stringification

my $var = "$mv";

Stringifying a MemVault will croak if it is conceptually "locked."

concatenation

my $new_mv = $mv . $string;
my $new_mv = $string . $mv;
my $new_mv = $mv . $other_mv;

.= is equivalent to "concat".

repetition

my $new_mv = $mv x 3;

exclusive or

my $new_mv = $mv ^ $bytes;
my $new_mv = $bytes ^ $mv;
my $new_mv = $mv ^ $other_mv;

^= is equivalent to "xor".

FEEDBACK

For reporting bugs, giving feedback, submitting patches, etc. please use the following:

  • IRC channel #sodium on irc.perl.org.

  • Email the author directly.

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.