Data::BytesLocker - Guarded storage for sensitive data
version 1.0.8.0
use Crypt::NaCl::Sodium qw(:utils); # lock by default $Data::BytesLocker::DEFAULT_LOCKED = 1; # some sensitive data read from external sources, eg. database my $password = ...; my $password_locker = Data::BytesLocker->new($password, wipe => 1); # $password now is overwritten with null bytes $password =~ /^\0+$/ or die; # as requested locker is locked $password_locker->is_locked or die; # dies with: "Unlock BytesLocker object before accessing the data" print "password: ", $password_locker->bytes, "\n"; # unlock the data $password_locker->unlock; # as requested locker is unlocked $password_locker->is_locked and die; # prints the password using overloaded stringification print "password: $password_locker\n"; # Crypt::NaCl::Sodium functions and methods return binary data locked in Data::BytesLocker objects my $random_password = random_bytes( 32 ); # we wanted locked by default $random_password->unlock; # helper function to convert into hexadecimal string print "random password: ", $random_password->to_hex, "\n"; # clone the data into new object my $copy = $password_locker->clone; # nonce increment my $next_nonce = $nonce->increment; # add number my $next_nonce = $nonce->add( $step ); # check if the data contains zero bits only $next_nonce->is_zero and print "back to square zero\n"; # always lock the data once done using it $password_locker->lock; $random_password->lock; # wipe out the memory and destroy the object undef $password_locker; undef $random_password; undef $copy;
Heartbleed was a serious vulnerability in OpenSSL. The ability to read past the end of a buffer is a serious bug, but what made it even worse is the fact that secret data could be disclosed by doing so.
In order to mitigate the impact of similar bugs, Data::BytesLocker provides heap allocation functions for storing sensitive data.
Data::BytesLocker
These are not general-purpose allocation functions. In particular, they are slower than regular scalars, and they require 3 or 4 extra pages of virtual memory (usually between 12-16kb extra memory will be used).
The stored data is placed at the end of a page boundary, immediately followed by a guard page. As a result, accessing memory past the end of the region will immediately terminate the application.
A canary is also placed right before the stored data. Modification of this canary are detected when trying to free the allocated region, and also cause the application to immediately terminate.
An additional guard page is placed before this canary. In a Heartbleed-like scenario, this guard page is likely to be read before the actual data, and this access will cause the application to terminate instead of leaking sensitive data.
The allocated region is filled with 0xd0 bytes in order to help catch bugs due to initialized data.
0xd0
On operating systems supporting MAP_NOCORE or MADV_DONTDUMP, the memory allocated this way will also not be part of core dumps and can help avoid the data being swapped to disk.
MAP_NOCORE
MADV_DONTDUMP
my $locker = Data::BytesLocker->new($data, wipe => 1 );
Returns object that stores the input $data in a protected memory location.
$data
If the optional parameter wipe is given and is true, then the input $data variable will be overwritten with null bytes.
wipe
Returned $locker object will contain the data that cannot be modified and if the object is locked it cannot be accessed as well.
$locker
Data::BytesLocker object when used in string context return the protected data. See "OVERLOADED OPERATIONS" for more details.
my $cloned = $locker->clone;
Returns new data object which will contain the copied data from $locker.
$locker->lock();
When called makes the data stored inaccessible. It cannot be read or written, but the data are preserved.
$locker->unlock();
When called makes the data stored accessible for read access only.
if ( $locker->is_locked ) { $locker->unlock; }
Returns true if the $locker object is locked, false otherwise.
my $data_length = $locker->length();
Returns the length of protected bytes.
my $hexencoded = $locker->to_hex();
Returns the protected data converted into a hexadecimal string.
NOTE: the $locker object must be unlocked.
Returns regular scalar.
my $bytes = $locker->bytes();
Returns the protected data as regular scalar.
if ( $locker->is_zero ) { print "data contains zero bits only\n"; }
Returns true if the $locker object contains zero bits only. Runs in constant-time for objects of the same length.
$locker->memcmp($bytes, $length ) or die "\$locker ne \$bytes for length: $length";
Compares strings in constant-time. Returns true if they match, false otherwise.
The argument $length is optional if length of $bytes is equal to the length of the data stored in $locker. Otherwise it is required and cannot be greater then the length of the shorter of compared variables.
$length
$bytes
$nonce->compare( $number, $length ) == -1 and print "\$nonce < \$number for length: $length";
A constant-time version of "memcmp", useful to compare nonces and counters in little-endian format, that plays well with "increment".
Returns -1 if $nonce is lower then $number, 0 if $nonce and $number are identical, or 1 if $nonce is greater then $number. Both $nonce and $number are assumed to be numbers encoded in little-endian format.
-1
$nonce
$number
0
1
The argument $length is optional if variables are of the same length. Otherwise it is required and cannot be greater then the length of the shorter of compared variables.
my $next_nonce = $nonce->increment();
Increments an arbitrary long unsigned number. Method runs in constant-time for a given length of locked data and considers it to be encoded in little-endian format.
This method is meant to be used to increment nonces and counters.
Returns the incremented object.
my $next_nonce = $nonce->add($number, $length);
Method computes ($nonce + $number) mod 2 ^ (8 * $length) in constant time for a given length and returns the result of that computation. Both $nonce and $number are assumed to be numbers encoded in little-endian format.
($nonce + $number) mod 2 ^ (8 * $length)
This method is meant to be used to increment nonces and counters using specified step.
Only operations listed below are supported.
print "Password: $locker\n";
if ( $locker eq $expected ) { print "matches\n"; } if ( $locker ne $expected ) { print "does not match\n"; }
The eq and ne operations are overloaded and allow to compare the $locker object with variable of equal length.
eq
ne
if ( $locker ) { print "locker has some non-zero length data\n"; } if ( ! $locker ) { print "locker has some zero length data\n"; }
The bool and ! operations are overloaded and allow to check if the $locker object contains the data at least one byte long.
bool
!
my $kv = "password:". $locker;
The concatenation operator . is overloaded and allows to create a new Data::BytesLocker object that is a result of joining the data together.
.
my $tripled_data = $locker x 3;
The repetition operator x is overloaded and allow to create a new Data::BytesLocker object that is a result of repeating the protected data specified number of times.
x
Crypt::NaCl::Sodium
Securing memory allocations
Alex J. G. Burzyński <ajgb@cpan.org>
This software is copyright (c) 2015 by Alex J. G. Burzyński <ajgb@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Crypt::NaCl::Sodium, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Crypt::NaCl::Sodium
CPAN shell
perl -MCPAN -e shell install Crypt::NaCl::Sodium
For more information on module installation, please visit the detailed CPAN module installation guide.