/ 
Crypt-ECDSA-0.065
/ Crypt::ECDSA

NAME

Crypt::ECDSA -- Elliptical Cryptography Digital Signature Algorithm

DESCRIPTION

An implementation of the elliptic curve digital signature algorithm in Perl,
using the Math::BigInt::GMP library and a little C for speed.

Implements the pending FIPS 186-3 ECDSA standard for digital signatures using
elliptical key crytography.  Routines include a working implementation of 
elliptical key cryptography.  Perhaps a preliminary version of signature
in the newer standard might be the following, which uses SHA-256 instead of the
current SHA-1 digest:

my $ecdsa = Crypt::ECDSA->new(
  standard => 'ECP-256',
  algorithm => Digest::SHA->new(256);
);
my $msg = "This is a test message for perl ecdsa."
my ( $r, $s ) = ecdsa->signature( message => $msg );

print "Signature (r, s) is: \nr = $r\ns = $s\n";

SYNOPSIS

my $ecdsa = Crypt::ECDSA->new( standard => 'ECP-256' );

my $msg = "This is a test message for perl ecdsa."

my ( $r, $s ) = $ecdsa->signature( message => $msg );

my $verify_ok = $ecdsa->verify( r => $r, 's' => $s, message => $msg );

my $ecdsa_from_PEM = Crypt::ECDSA->new( PEM => $pem_filename );

METHODS

new
Create an ECDSA object.

Arguments include:

standard => curve type, one of 'ECP-192', 'ECP-224', 'ECP-256', 'ECP-384',
  'ECP-521', 'EC2N-163', 'EC2N-233', 'EC2N-283', 'EC2N-409', 'EC2N-571',

algorithm => $algo,  where $algo is a Digest::SHA interface compatible object,
  which defaults to Digest::SHA(1) which does SHA-1 digests for ECDSA.

.. and other arguments, used as per Crypt::ECDSA::Key.
key
my $key = $ecdsa->key;

Get the key object in use by this ecdsa object
errstr
print $ecdsa->errstr;

Get the last internal error message
keygen
if( $want_new_key ) {  $
  my( $secret, $base_point ) = ecdsa->keygen();

Make a new private/ public key pair
make_text_digest
  my $msg = "This is a test message fpr perl ecdsa."

  my  $digest = ecdsa->make_text_digest( $msg );

Make a text digest via the algorithm passed to new ( default is SHA-1 )
signature
  my ( $r, $s ) = $ecdsa->signature( message => $msg );
  
  my( $r, $s ) = $ecdsa->signature( hash => $digest );
  
  $ecdsa->signature( message_file => $filename, sig_file => $outfilename );

Sign a message as message => message or a digest as hash => $digest

Optionally, the message_file is a file to be hashed and signed, and the 
sig_file is a file to which a DER encoded (r,s) signature pair is written.
sign
Sign is a synonym for signature
verify_public_key
Verify a public key point, as in the Crypt::ECDSA::Key methods
verify
  my $msg = "This is a test message fpr perl ecdsa."
  my $digest = ecdsa->make_text_digest( $msg );
  my $verify_ok = $ecdsa->verify( r => $r, 's' => $s, message => $msg );
  my $verify_ok = $ecdsa->verify( r => $r, 's' => $s, hash => $digest );

  $ok = $ecdsa->verify( message => $msg, r => $r, 's' => $s );   
  $ok = $ecdsa->verify( r => $r, s => $s, hash => $digest );
  $ok = $ecdsa->verify( message_file => $filename, sig_file => $sigfilename );

Verify a message as message => message or a digest as hash => $digest

Optionally, the message_file is a file to be hashed and verified against the 
sig_file, which is a file to which a DER encoded (r,s) signature pair has
been written.

Verify as message given  r, s, and either message or its digest

Package Non-object (Static) Functions

ecdsa_sign_hash

ecdsa_sign_hash( r, s, hash, gx, gy, q, d, mod, a, is_binary, max_tries );

Direct call to the XS routine, with numbers as Math::BigInt::GMP values fields. Places the r and s values of the signature in r and s.

ecdsa_verify_hash

ecdsa_verify_hash( r, s, hash, gx, gy, qx, qy, q, mod, a, is_binary );

Direct call to the XS routine. Returns 1 if hash verifies, 0 if not.

sidechannel_protection
sidechannel_protection(1);  # slightly safer from hardware snooping

$side_channels_normalized = sidechannel_protection();  # 1

sidechannel_protection(0);  # slightly faster with prime field multiplies

Off by default.

Set or get an option to normalize doubling/adding calculation methods during ECC multiplication to make side-channel snooping more difficult. This is a security feature which seems to incur a 0 to 10% performance hit, less with binary curves than prime field curves. If the ECC computation is to be run on a PC or larger general purpose computing device, side-channel vulnerability protection is probably unnecessary since most persons with access to the inner physical side channels of such a device would also be able to access protected data more simply. With dedicated small devices such protection may be of value. It may be useful to check the specifics of your CPU and/or device to see if side channels would be an issue.

Class Internal Functions

add_F2m_point
add_Fp_point
double_F2m_point
double_Fp_point
gmp_is_probably_prime
gmp_random_bits
invert_F2m
is_F2m_point_on_curve
is_Fp_point_on_curve
is_valid_point
multiply_F2m
multiply_F2m_point
multiply_Fp_point

NOTES

See FIPS 186-3, draft standard
Note the use of SHA-1 hashing is becoming deprecated, but is still the default.
SHA-256 hashing may be used instead of SHA-1 when practicable.
See also http://en.wikipedia.org/wiki/Elliptic_Curve_DSA, quoted below:
Signature generation algorithm

Suppose Alice wants to send a signed message to Bob.
Initially, the curve parameters (q,FR,a,b,G,n,h) must be agreed upon.
Also, Alice must have a key pair suitable for elliptic curve cryptography,
consisting of a private key dA (a randomly selected integer in the
interval [1,n - 1]) and a public key QA (where QA = dAG).

For Alice to sign a message m, she follows these steps:

 1. Calculate e = HASH(m), where HASH is a cryptographic hash function, such as SHA-1.
 2. Select a random integer k from [1,n - 1].
 3. Calculate r = x1(mod n), where (x1,y1) = kG. If r = 0, go back to step 2.
 4. Calculate s = k**(-1)*(e + dAr)(mod n). If s = 0, go back to step 2.
 5. The signature is the pair (r,s).

Signature verification algorithm

For Bob to authenticate Alice's signature, he must have a copy of her
public key QA. He follows these steps:

 1. Verify that r and s are integers in [1,n - 1]. If not, the signature is invalid.
 2. Calculate e = HASH(m), where HASH is the same function used in the signature generation.
 3. Calculate w = s**(-1)(mod n).
 4. Calculate u1 = ew(mod n) and u2 = rw(mod n).
 5. Calculate (x1,y1) = u1G + u2QA.
 6. The signature is valid if x1 = r(mod n), invalid otherwise.

AUTHOR

William Herrera (wherrera@skylightview.com)

COPYRIGHT

Copyright (C) 2007, 2008 William Hererra.  All Rights Reserved.

This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.