NAME

Crypt::ECDSA -- Elliptical Cryptography Digital Signature Algorithm

DESCRIPTION

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

Implements the pending FIPS 186-3 ECDSA standard for digital signatures using
elliptical key crytography.  Like FIPS 186-3, this is preliminary-- not yet
ready for full use.  It does contain a working implementation of the elliptical
key crypto found in the current 186-2 standard.  The final details of the 186-3
standard are still being worked out.  Perhaps a preliminary version of signature
in the NEW 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 method

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

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.

TODO

The Koblitz curve point multiplication algorithm could be optimized a bit more.
Digital X.509 certificate handling might be implemented for OpenSSL compatibility.

AUTHOR

William Herrera (wherrera@skylightview.com)

COPYRIGHT

Copyright (C) 2007 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.