NAME

       Crypt::OpenSSL::DSA - Digital Signature Algorithm using OpenSSL

SYNOPSIS

         use Crypt::OpenSSL::DSA;

         # generate keys and write out to PEM files
         my $dsa = Crypt::OpenSSL::DSA->generate_parameters( 512 );
         $dsa->generate_key;
         $dsa->write_pub_key( $filename );
         $dsa->write_priv_key( $filename );

         # using keys from PEM files
         my $dsa_priv = Crypt::OpenSSL::DSA->read_priv_key( $filename );
         my $sig      = $dsa_priv->sign($message);
         my $dsa_pub  = Crypt::OpenSSL::DSA->read_pub_key( $filename );
         my $valid    = $dsa_pub->verify($message, $sig);

         # using keys from PEM strings
         my $dsa_priv = Crypt::OpenSSL::DSA->read_priv_key_str( $key_string );
         my $sig      = $dsa_priv->sign($message);
         my $dsa_pub  = Crypt::OpenSSL::DSA->read_pub_key_str( $key_string );
         my $valid    = $dsa_pub->verify($message, $sig);

DESCRIPTION

       Crypt::OpenSSL::DSA implements the DSA (Digital Signature Algorithm) signature
       verification system.

       It is a thin XS wrapper to the DSA functions contained in the OpenSSL crypto library,
       located at http://www.openssl.org

CLASS METHODS

       $dsa = Crypt::OpenSSL::DSA->generate_parameters( $bits, $seed );
           Returns a new DSA object and generates the p, q and g parameters necessary to generate
           keys.

           bits is the length of the prime to be generated; the DSS allows a maximum of 1024
           bits.

       $dsa = Crypt::OpenSSL::DSA->read_params( $filename );
           Reads in a parameter PEM file and returns a new DSA object with the p, q and g
           parameters necessary to generate keys.

       $dsa = Crypt::OpenSSL::DSA->read_pub_key( $filename );
           Reads in a public key PEM file and returns a new DSA object that can be used to verify
           DSA signatures.

       $dsa = Crypt::OpenSSL::DSA->read_priv_key( $filename );
           Reads in a private key PEM file and returns a new DSA object that can be used to sign
           messages.

       $dsa = Crypt::OpenSSL::DSA->read_pub_key_str( $key_string );
           Reads in a public key PEM string and returns a new DSA object that can be used to
           verify DSA signatures.  The string should include the -----BEGIN...----- and
           -----END...----- lines.

       $dsa = Crypt::OpenSSL::DSA->read_priv_key_str( $key_string );
           Reads in a private key PEM string and returns a new DSA object that can be used to
           sign messages.  The string should include the -----BEGIN...----- and -----END...-----
           lines.

OBJECT METHODS

       $dsa->generate_key;
           Generates private and public keys, assuming that $dsa is the return value of
           generate_parameters.

       $sig = $dsa->sign( $message );
           Signs $message, returning the signature.  Note that $meesage cannot exceed 20
           characters in length.

           $dsa is the signer's private key.

       $sig_obj = $dsa->do_sign( $message );
           Similar to "sign", but returns a Crypt::OpenSSL::DSA::Signature object.

       $valid = $dsa->verify( $message, $sig );
           Verifies that the $sig signature for $message is valid.

           $dsa is the signer's public key.

           Note: it croaks if the underlying library call returns error (-1).

       $valid = $dsa->do_verify( $message, $sig_obj );
           Similar to "verify", but uses a Crypt::OpenSSL::DSA::Signature object.

           Note: it croaks if the underlying library call returns error (-1).

       $dsa->write_params( $filename );
           Writes the parameters into a PEM file.

       $dsa->write_pub_key( $filename );
           Writes the public key into a PEM file.

       $dsa->write_priv_key( $filename );
           Writes the private key into a PEM file.

       $p = $dsa->get_p, $dsa->set_p($p)
           Gets/sets the prime number in binary format.

       $q = $dsa->get_q, $dsa->set_q($q)
           Gets/sets the subprime number (q | p-1) in binary format.

       $g = $dsa->get_g, $dsa->set_g($g)
           Gets/sets the generator of subgroup in binary format.

       $pub_key = $dsa->get_pub_key, $dsa->set_pub_key($pub_key)
           Gets/sets the public key (y = g^x) in binary format.

       $priv_key = $dsa->get_priv_key, $dsa->set_priv_key($priv_key)
           Gets/sets the private key in binary format.

NOTES

       Crpyt::DSA is a more mature Perl DSA module, but can be difficult to install, because of
       the Math::Pari requirement.

       Comments, suggestions, and patches welcome.

AUTHOR

       T.J. Mather, <tjmather@maxmind.com>

COPYRIGHT

       Copyright (c) 2002 T.J. Mather.  Crypt::OpenSSL::DSA is free software; you may
       redistribute it and/or modify it under the same terms as Perl itself.

       Paid support is available from directly from the author of this package.  Please see
       <http://www.maxmind.com/app/opensourceservices> for more details.

SEE ALSO

       Crypt::OpenSSL::DSA::Signature

       Crypt::DSA, Crypt::OpenSSL::RSA

       Net::DNS::SEC