/ 
Crypt-secp256k1-0.0_02
River stage zero No dependents
/ Crypt::secp256k1

NAME

Crypt::secp256k1 - Perl interface to libsecp256k1

SYNOPSIS

use Crypt::secp256k1;
my $ctx = Crypt::secp256k1->new(SECP256K1_CONTEXT_SIGN);
$ctx->randomize($random_32byte_string);
my $bad_secret = pack "C32", map { int rand 256 } 1..32;
my $public = $ctx->pubkey_create($bad_secret);

DESCRIPTION

Handle keys, sign hashes and verify signatures using the secp256k1 protocol by extending Bitcoin Core's libsecp256k1 to perl.

BUGS

... that I know of.

  • Scalars' lengths are not checked when mapping to C.

  • Very little testing has been done.

  • Makefile.PL makes no attempt to find the library or header files.

EXPORT

None by default. All exportable constants may be imported by using this module with :all.

Exportable constants

SECP256K1_CONTEXT_NONE
SECP256K1_CONTEXT_SIGN
SECP256K1_CONTEXT_VERIFY
SECP256K1_EC_COMPRESSED
SECP256K1_EC_UNCOMPRESSED

PERL/C API

Apart from making the method call/return signature more perl-like, the API exactly follows the C API defined in secp256k1.h. See that file for more detail on each method's usage.

The changes made to fit into a perl-like model are:

  • Methods which can fail will croak() if they do so.

  • Methods which output a key/signature/etc. will return a simple scalar.

  • Methods which require a key/signature/etc. require a simple scalar holding as many bytes as the specification requires.

  • Methods which modified their arguments in-place now return a new simple scalar and leave the original alone.

  • randomize() returns the context object so that it can be chained in the constructor:

    my $context = Crypt::secp256k1->new($flags)->randomize($seed);

CONSTRUCTION & CONTEXT METHODS

All operations require a context object to work on. Contexts are created like a normal perl object and can be cloned. The model nevertheless closely follows the C model.

Crypt::secp256k1->new([flags]) => $context

Create a new context for secp256k1 operations. flags can be any combination of the SECP256K1_CONTEXT_* constants. Some operations require that a SIGN or VERIFY context (or both) be used.

$context->clone() => $context

Clone the context into a new context object.

$context->randomize(seed) => $context

Updates the context randomization to protect against side-channel leakage.

This returns the context object it was called on so that it may be called in-line in the constructor.

$context->set_error_callback($callback)

Set a callback function to be called when an internal consistency check fails. The default is crashing.

$context->set_illegal_callback($callback)

Set a callback function to be called when an illegal argument is passed to an API call. It will only trigger for violations that are mentioned explicitly in the header.

PRIVATE KEY METHODS

Yes there are 3 privkey_* methods and 1 seckey_* method. No I haven't decided what to do about it.

There is no method for creating a secret key. Any means of creating 32 random bytes and stuffing them in a scalar will do. Beware encoding/unicode issues.

For example to simply create a key from an unsafe random source, use:

my $secret = pack "C32", map { int rand 256 } 1..32;

Which packs a list of 32 random integers (between 0 and 255) into a 32-byte simple scalar.

$context->privkey_negate($seckey) => $seckey

Negates a private key in place.

$context->privkey_tweak_add($seckey, $tweak) => $seckey

Tweak a private key by adding tweak to it.

$context->privkey_tweak_mul($seckey, $tweak) => $seckey

Tweak a private key by multiplying it by a tweak.

$context->seckey_verify($seckey) => $boolean

Verify an ECDSA secret key.

PUBLIC KEY METHODS

$context->pubkey_combine(@pubkeys) => $pubkey

Add a number of public keys together.

$context->pubkey_create($seckey) => $pubkey

Compute the public key for a secret key.

$context->pubkey_negate($pubkey) => $pubkey

Negates a public key in place.

$context->pubkey_parse($variable_pubkey) => $pubkey

Parse a variable-length public key into the pubkey object.

$context->pubkey_serialize($pubkey, $flags) => $serialized_pubkey

Serialize a pubkey object into a serialized byte sequence.

$context->pubkey_tweak_add($pubkey, $tweak) => $pubkey

Tweak a public key by adding tweak times the generator to it.

$context->pubkey_tweak_mul($pubkey, $tweak) => $pubkey

Tweak a public key by multiplying it by a tweak value.

SIGNATURE & VERIFICATION METHODS

$context->sign($seckey, $hash, [$nonce_callback]) => $signature

Create an ECDSA signature.

$context->signature_normalize($abnormal_signature) => $signature

Convert a signature to a normalized lower-S form.

$context->signature_parse_compact($compact_signature) => $signature

Parse an ECDSA signature in compact (64 bytes) format.

$context->signature_parse_der($der_signature) => $signature

Parse a DER ECDSA signature.

$context->signature_serialize_compact($compact_signature) => $serialized_signature

Serialize an ECDSA signature in compact (64 byte) format.

$context->signature_serialize_der($der_signature) => $serialized_signature

Serialize an ECDSA signature in DER format.

$context->verify($signature, $hash, $pubkey) => $boolean

Verify an ECDSA signature.

SEE ALSO

https://github.com/bitcoin-core/secp256k1

AUTHOR

Matthew King, <chohag@jtan.com>

COPYRIGHT AND LICENSE

Copyright (C) 2017 by Matthew King

This library is free software; you can redistribute it and/or modify it under the terms of the WTFPL version 2 or, at your option, any version of any license you may have available.