The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Crypt-ECDSA-0.068
/ 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.