1Crypt::OpenSSL::DSA(3)User Contributed Perl DocumentationCrypt::OpenSSL::DSA(3)
2
3
4

NAME

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

SYNOPSIS

9         use Crypt::OpenSSL::DSA;
10
11         # generate keys and write out to PEM files
12         my $dsa = Crypt::OpenSSL::DSA->generate_parameters( 512 );
13         $dsa->generate_key;
14         $dsa->write_pub_key( $filename );
15         $dsa->write_priv_key( $filename );
16
17         # using keys from PEM files
18         my $dsa_priv = Crypt::OpenSSL::DSA->read_priv_key( $filename );
19         my $sig      = $dsa_priv->sign($message);
20         my $dsa_pub  = Crypt::OpenSSL::DSA->read_pub_key( $filename );
21         my $valid    = $dsa_pub->verify($message, $sig);
22
23         # using keys from PEM strings
24         my $dsa_priv = Crypt::OpenSSL::DSA->read_priv_key_str( $key_string );
25         my $sig      = $dsa_priv->sign($message);
26         my $dsa_pub  = Crypt::OpenSSL::DSA->read_pub_key_str( $key_string );
27         my $valid    = $dsa_pub->verify($message, $sig);
28

DESCRIPTION

30       Crypt::OpenSSL::DSA implements the DSA (Digital Signature Algorithm)
31       signature verification system.
32
33       It is a thin XS wrapper to the DSA functions contained in the OpenSSL
34       crypto library, located at http://www.openssl.org
35

CLASS METHODS

37       $dsa = Crypt::OpenSSL::DSA->generate_parameters( $bits, $seed );
38           Returns a new DSA object and generates the p, q and g parameters
39           necessary to generate keys.
40
41           bits is the length of the prime to be generated; the DSS allows a
42           maximum of 1024 bits.
43
44       $dsa = Crypt::OpenSSL::DSA->read_params( $filename );
45           Reads in a parameter PEM file and returns a new DSA object with the
46           p, q and g parameters necessary to generate keys.
47
48       $dsa = Crypt::OpenSSL::DSA->read_pub_key( $filename );
49           Reads in a public key PEM file and returns a new DSA object that
50           can be used to verify DSA signatures.
51
52       $dsa = Crypt::OpenSSL::DSA->read_priv_key( $filename );
53           Reads in a private key PEM file and returns a new DSA object that
54           can be used to sign messages.
55
56       $dsa = Crypt::OpenSSL::DSA->read_pub_key_str( $key_string );
57           Reads in a public key PEM string and returns a new DSA object that
58           can be used to verify DSA signatures.  The string should include
59           the -----BEGIN...----- and -----END...----- lines.
60
61       $dsa = Crypt::OpenSSL::DSA->read_priv_key_str( $key_string );
62           Reads in a private key PEM string and returns a new DSA object that
63           can be used to sign messages.  The string should include the
64           -----BEGIN...----- and -----END...----- lines.
65

OBJECT METHODS

67       $dsa->generate_key;
68           Generates private and public keys, assuming that $dsa is the return
69           value of generate_parameters.
70
71       $sig_size = $dsa->get_sig_size( );
72           Returns the maximum size of an ASN.1 encoded DSA signature for key
73           dsa in bytes.
74
75            512-bit keys = 48
76           1024-bit keys = 48
77           2024-bit keys = 72
78           3072-bit keys = 72
79
80           ASN.1 dsa signatures consist of:
81
82           Sequence 1-byte (0x30) Length   1-byte Integer  1-byte (0x02)
83           Length   1-byte (0x14) = 20 r       20-bytes or 21-bytes Integer
84           1-byte (0x02) Length   1-byte (0x14) = 20 s       20-bytes or
85           21-bytes
86
87           30 2C 02 14
88           6C.70.50.7C.93.A8.B5.EC.1E.A1.5E.C5.73.AA.0F.EA.4D.BE.42.7A 02 14
89           4E.AD.E6.BB.72.54.92.30.2B.03.AB.53.5D.3D.6E.88.B8.AA.D6.30
90
91           Note that the above signature is 46 bytes long - the extra two
92           bytes are used only when r and/or s are larger than or equal to
93           2^159.  The extra bytes are used to distinguish positive from
94           negative values.
95
96           All that to say if you are using get_sig_size() to determine the
97           size of r + s depending on the size of the key you can subtract 8
98           bytes for the ASN.1 overhead.
99
100       $sig = $dsa->sign( $message );
101           Signs $message, returning the signature.  Note that $meesage cannot
102           exceed 20 characters in length.
103
104           $dsa is the signer's private key.
105
106       $sig_obj = $dsa->do_sign( $message );
107           Similar to "sign", but returns a Crypt::OpenSSL::DSA::Signature
108           object.
109
110       $valid = $dsa->verify( $message, $sig );
111           Verifies that the $sig signature for $message is valid.
112
113           $dsa is the signer's public key.
114
115           Note: it croaks if the underlying library call returns error (-1).
116
117       $valid = $dsa->do_verify( $message, $sig_obj );
118           Similar to "verify", but uses a Crypt::OpenSSL::DSA::Signature
119           object.
120
121           Note: it croaks if the underlying library call returns error (-1).
122
123       $dsa->write_params( $filename );
124           Writes the parameters into a PEM file.
125
126       $dsa->write_pub_key( $filename );
127           Writes the public key into a PEM file.
128
129       $dsa->write_priv_key( $filename );
130           Writes the private key into a PEM file.
131
132       $p = $dsa->get_p, $dsa->set_p($p)
133           Gets/sets the prime number in binary format.
134
135       $q = $dsa->get_q, $dsa->set_q($q)
136           Gets/sets the subprime number (q | p-1) in binary format.
137
138       $g = $dsa->get_g, $dsa->set_g($g)
139           Gets/sets the generator of subgroup in binary format.
140
141       $pub_key = $dsa->get_pub_key, $dsa->set_pub_key($pub_key)
142           Gets/sets the public key (y = g^x) in binary format.
143
144       $priv_key = $dsa->get_priv_key, $dsa->set_priv_key($priv_key)
145           Gets/sets the private key in binary format.
146

NOTES

148       Crpyt::DSA is a more mature Perl DSA module, but can be difficult to
149       install, because of the Math::Pari requirement.
150
151       Comments, suggestions, and patches welcome.
152

AUTHOR

154       T.J. Mather, <tjmather@maxmind.com>
155
157       Copyright (c) 2002 T.J. Mather.  Crypt::OpenSSL::DSA is free software;
158       you may redistribute it and/or modify it under the same terms as Perl
159       itself.
160
161       Paid support is available directly from the author of this package.
162       Please see <http://www.maxmind.com/app/opensourceservices> for more
163       details.
164

SEE ALSO

166       Crypt::OpenSSL::DSA::Signature
167
168       Crypt::DSA, Crypt::OpenSSL::RSA
169
170       Net::DNS::SEC
171
172
173
174perl v5.34.0                      2022-01-21            Crypt::OpenSSL::DSA(3)
Impressum