NAME
Bitcoin::Crypto::Secret - Storing secrets more safely
SYNOPSIS
use Bitcoin::Crypto::Secret;
my $secret = Bitcoin::Crypto::Secret->new('super secret password');
say $secret; # prints "[REDACTED]"
# format strings are ok
my $secret_with_format = Bitcoin::Crypto::Secret->new([hex => '...']);DESCRIPTION
This is a small class which improves the security of secrets stored in Perl memory. It is an inside-out object which always stringifies to [REDACTED], so that the secret will not get leaked accidentally, for example in dumps (like Data::Dumper). Bitcoin::Crypto uses this class to store secrets internally, regardless of whether you use it explicitly or not. Plainstring secrets will be turned into instances of Bitcoin::Crypto::Secret automatically.
Secrets returned from Bitcoin::Crypto functions are plain strings and not instances of Bitcoin::Crypto::Secret.
What is considered a secret?
Currently, following arguments to functions accept objects of Bitcoin::Crypto::Secret:
$mnemonicand$passwordin "from_mnemonic" in Bitcoin::Crypto::Key::ExtPrivate$serializedin "from_serialized" in Bitcoin::Crypto::Key::ExtPrivate$serializedin "from_serialized" in Bitcoin::Crypto::Key::Private$entropyin "mnemonic_from_entropy" in Bitcoin::Crypto::Util$mnemonicand$passwordin "mnemonic_to_seed" in Bitcoin::Crypto::Util
Crypt::SecretBuffer awareness and partial compatibility
This class is partially compatible with Crypt::SecretBuffer: the interface of "new" and "unmask_to" is the same. In addition, it stringifies to the same [REDACTED] string. You can think of Bitcoin::Crypto::Secret as "Crypt::SecretBuffer light", as it only tries to hide the secret from leaking by accident, and not keep it away from perl's heap entirely. There is no way to keep secrets away from perl's heap when using Bitcoin::Crypto, as the library manipulates the secrets with perl (non-XS) code.
That being said, if you want that little extra protection or other features of Crypt::SecretBuffer, Bitcoin::Crypto is aware of its existence and will accept its objects in any place where a secret is expected. It will not try to turn it into a Bitcoin::Crypto::Secret instance, but instead store it internally as-is.
INTERFACE
Methods
new
$secret = $class->new($data)Creates a new secret instance holding $data, which can be any defined value (unlike "new" in Crypt::SecretBuffer, which only accepts strings).
unmask_to
$ret = $secret->unmask_to($sub)Executes $sub with a sole argument being a value of the secret. Returns whatever $sub returned. Fully compatible with "unmask_to" in Crypt::SecretBuffer.
as_string
$str = $secret->as_string()Always returns [REDACTED]. This happens automatically on object stringification. Unlike Crypt::SecretBuffer, there is no way to disable this mark to make it stringify as the secret. If this is needed, this idiom can be used:
$data = $secret->unmask_to(sub { shift });