The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Bitcoin-Crypto-2.004
River stage one • 3 direct dependents • 5 total dependents
5 ++
/ Bitcoin::Crypto::Key::Private

NAME

Bitcoin::Crypto::Key::Private - Bitcoin private keys

SYNOPSIS

        use Bitcoin::Crypto::Key::Private;

        # get Bitcoin::Crypto::Key::Public instance from private key

        my $pub = $priv->get_public_key();

        # automatically sign standard transactions

        $priv->sign_transaction($tx, signing_index => $n);

        # create signature for custom message (hash256)

        my $sig = $priv->sign_message('Hello world');

        # signature is returned as byte string
        # use to_format to get the representation you need

        use Bitcoin::Crypto::Util qw(to_format);
        my $sig_hex =  to_format [hex => $sig];

        # signature verification

        $priv->verify_message('Hello world', $sig);

DESCRIPTION

This class allows you to create a private key instance.

You can use a private key to:

  • generate public keys

  • sign and verify messages

Please note that any keys generated are by default compressed.

see Bitcoin::Crypto::Network if you want to work with other networks than Bitcoin Mainnet.

METHODS

new

Constructor is reserved for internal and advanced use only. Use "from_serialized" or "from_wif" instead.

from_serialized

        $key_object = $class->from_serialized($serialized)

This creates a new key from string data. Argument $serialized is a formatable bytestring containing the private key entropy.

Returns a new key object instance.

to_serialized

        $serialized = $key_object->to_serialized()

This returns a private key as a sequence of bytes. The result is a bytestring which can be further formated with to_format utility.

from_bytes

Deprecated. Use $class->from_serialized($data) instead.

to_bytes

Deprecated. Use $key->to_serialized() instead.

from_hex

Deprecated. Use $class->from_serialized([hex => $data]) instead.

to_hex

Deprecated. Use to_format [hex => $key->to_serialized()] instead.

from_wif

        $key_object = $class->from_wif($str, $network = undef)

Creates a new private key from Wallet Import Format string.

Takes an additional optional argument, which is network name. It may be useful if you use many networks and some have the same WIF byte.

This method will change compression and network states of the created private key, as this data is included in WIF format.

Returns class instance.

to_wif

        $wif_string = $object->to_wif()

Does the opposite of from_wif on a target object

set_compressed

        $key_object = $object->set_compressed($val)

Change key's compression state to $val (1/0). This will change the WIF generated by to_wif() method and also enable creation of uncompressed public keys. If $val is omitted it is set to 1.

Returns current key instance.

set_network

        $key_object = $object->set_network($val)

Change key's network state to $val. It can be either network name present in Bitcoin::Crypto::Network package or an instance of this class.

Returns current key instance.

get_public_key

        $public_key_object = $object->get_public_key()

Returns instance of Bitcoin::Crypto::Key::Public generated from the private key.

sign_message

        $signature = $object->sign_message($message)

Signs a digest of $message (digesting it with double sha256) with a private key.

Returns a byte string containing signature.

Character encoding note: $message should be encoded in the proper encoding before passing it to this method. Passing Unicode string will cause the function to fail. You can encode like this (for UTF-8):

        use Encode qw(encode);
        $message = encode('UTF-8', $message);

Caution: libtomcrypt cryptographic package that is generating signatures does not currently offer a deterministic mechanism. For this reason the sign_message method will complain with a warning. You should install an optional Crypt::Perl package, which supports deterministic signatures, which will disable the warning. Non-deterministic signatures can lead to leaking private keys if the random number generator's entropy is insufficient.

sign_transaction

        $object->sign_transaction($tx, %params)

Signs the transaction $tx using this private key. This automatic signing only works for standard script types, if your script is non-standard then you will have to sign manually.

Note that the module will let you sign any transaction with any private key. You have to manually run "verify" in Bitcoin::Crypto::Transaction to ensure you used the right private key and the signature is correct for the corresponding locking script.

Returns nothing - the result of the function is the modification of transaction $tx.

%params can contain:

  • signing_index

    This non-negative integer is the index of the input being signed. Required.

  • redeem_script

    A Bitcoin::Crypto::Script instance or something which can be turned into a script, used for specifying a payout script when redeeming P2SH and P2WSH outputs.

  • multisig

    A representation of the multisig signing stage. It is an array reference with exactly two elements. The first element is the number (1-based, not the index!) of the currently signed multisig. The second element is the total number of signatures required for the multisig. For example, signing 2-out-of-3 multisig can look like this (taken from ex/tx/multisig_redeem.pl example):

            # sign using the private key belonging to the first pubkey
        btc_prv->from_wif('cScAuqNfiNR7mq61QGW3LtokKAwzBzs4rbCz4Uff1NA15ysEij2i')
                ->sign_transaction($tx, signing_index => 0, redeem_script => $redeem_script, multisig => [1, 2]);

        # sign using the private key belonging to the third pubkey
        btc_prv->from_wif('cQsSKWrBLXNY1oSZbLcJf4HF5vnKGgKko533LnkTmqRdS9Fx4SGH')
                ->sign_transaction($tx, signing_index => 0, redeem_script => $redeem_script, multisig => [2, 2]);

  • sighash

    The sighash which should be used for the signature. By default SIGHASH_ALL is used.

verify_message

        $signature_valid = $object->verify_message($message, $signature)

Verifies $signature against digest of $message (digesting it with double sha256) using private key.

Returns boolean.

Character encoding note: $message should be encoded in the proper encoding before passing it to this method. Passing Unicode string will cause the function to fail. You can encode like this (for UTF-8):

        use Encode qw(encode);
        $message = encode('UTF-8', $message);

EXCEPTIONS

This module throws an instance of Bitcoin::Crypto::Exception if it encounters an error. It can produce the following error types from the Bitcoin::Crypto::Exception namespace:

  • Sign - couldn't sign the message correctly

  • ScriptType - couldn't automatically sign the given script type

  • Verify - couldn't verify the message correctly

  • KeyCreate - key couldn't be created correctly

  • NetworkConfig - incomplete or corrupted network configuration

SEE ALSO

Bitcoin::Crypto::Key::Public
Bitcoin::Crypto::Network