Skip to content
Newer
Older
100644 247 lines (167 sloc) 6.92 KB
5165f23 @gisle First revision.
gisle authored
1 package Digest::SHA1;
2
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
3 use strict;
4 use vars qw($VERSION @ISA @EXPORT_OK);
5
184cc7c @gisle Release 2.12
gisle authored
6 $VERSION = '2.12';
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
7
5165f23 @gisle First revision.
gisle authored
8 require Exporter;
9 *import = \&Exporter::import;
93acdc0 @gisle From: Mike McCauley <mikem@open.com.au>
gisle authored
10 @EXPORT_OK = qw(sha1 sha1_hex sha1_base64 sha1_transform);
5165f23 @gisle First revision.
gisle authored
11
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
12 require DynaLoader;
13 @ISA=qw(DynaLoader);
14
d8d9c08 @gisle Release 2.07
gisle authored
15 eval {
16 require Digest::base;
17 push(@ISA, 'Digest::base');
18 };
19 if ($@) {
20 my $err = $@;
21 *add_bits = sub { die $err };
22 }
23
24 Digest::SHA1->bootstrap($VERSION);
5165f23 @gisle First revision.
gisle authored
25
26 1;
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
27 __END__
28
29 =head1 NAME
30
96a2ae6 @gisle Fix spelling (downcase)
gisle authored
31 Digest::SHA1 - Perl interface to the SHA-1 algorithm
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
32
33 =head1 SYNOPSIS
34
35 # Functional style
36 use Digest::SHA1 qw(sha1 sha1_hex sha1_base64);
37
38 $digest = sha1($data);
39 $digest = sha1_hex($data);
40 $digest = sha1_base64($data);
93acdc0 @gisle From: Mike McCauley <mikem@open.com.au>
gisle authored
41 $digest = sha1_transform($data);
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
42
43
44 # OO style
45 use Digest::SHA1;
46
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
47 $sha1 = Digest::SHA1->new;
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
48
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
49 $sha1->add($data);
50 $sha1->addfile(*FILE);
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
51
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
52 $sha1_copy = $sha1->clone;
53
54 $digest = $sha1->digest;
55 $digest = $sha1->hexdigest;
56 $digest = $sha1->b64digest;
57 $digest = $sha1->transform;
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
58
59 =head1 DESCRIPTION
60
61 The C<Digest::SHA1> module allows you to use the NIST SHA-1 message
62 digest algorithm from within Perl programs. The algorithm takes as
63 input a message of arbitrary length and produces as output a 160-bit
64 "fingerprint" or "message digest" of the input.
65
6e33028 @gisle Mention that SHA-1 might be weak [RT#11880]
gisle authored
66 In 2005, security flaws were identified in SHA-1, namely that a possible
67 mathematical weakness might exist, indicating that a stronger hash function
68 would be desirable. The L<Digest::SHA> module implements the stronger
69 algorithms in the SHA family.
70
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
71 The C<Digest::SHA1> module provide a procedural interface for simple
72 use, as well as an object oriented interface that can handle messages
73 of arbitrary length and which can read files directly.
74
75 =head1 FUNCTIONS
76
77 The following functions can be exported from the C<Digest::SHA1>
78 module. No functions are exported by default.
79
80 =over 4
81
82 =item sha1($data,...)
83
84 This function will concatenate all arguments, calculate the SHA-1
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
85 digest of this "message", and return it in binary form. The returned
86 string will be 20 bytes long.
87
88 The result of sha1("a", "b", "c") will be exactly the same as the
89 result of sha1("abc").
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
90
91 =item sha1_hex($data,...)
92
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
93 Same as sha1(), but will return the digest in hexadecimal form. The
94 length of the returned string will be 40 and it will only contain
95 characters from this set: '0'..'9' and 'a'..'f'.
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
96
97 =item sha1_base64($data,...)
98
99 Same as sha1(), but will return the digest as a base64 encoded string.
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
100 The length of the returned string will be 27 and it will only contain
101 characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and
102 '/'.
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
103
4729280 @gisle Document missing base64 padding.
gisle authored
104 Note that the base64 encoded string returned is not padded to be a
105 multiple of 4 bytes long. If you want interoperability with other
106 base64 encoded sha1 digests you might want to append the redundant
107 string "=" to the result.
108
93acdc0 @gisle From: Mike McCauley <mikem@open.com.au>
gisle authored
109 =item sha1_transform($data)
110
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
111 Implements the basic SHA1 transform on a 64 byte block. The $data
112 argument and the returned $digest are in binary form. This algorithm
113 is used in NIST FIPS 186-2
93acdc0 @gisle From: Mike McCauley <mikem@open.com.au>
gisle authored
114
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
115 =back
116
117 =head1 METHODS
118
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
119 The object oriented interface to C<Digest::SHA1> is described in this
120 section. After a C<Digest::SHA1> object has been created, you will add
121 data to it and finally ask for the digest in a suitable format. A
122 single object can be used to calculate multiple digests.
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
123
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
124 The following methods are provided:
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
125
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
126 =over 4
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
127
128 =item $sha1 = Digest::SHA1->new
129
130 The constructor returns a new C<Digest::SHA1> object which encapsulate
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
131 the state of the SHA-1 message-digest algorithm.
132
133 If called as an instance method (i.e. $sha1->new) it will just reset the
134 state the object to the state of a newly created object. No new
135 object is created in this case.
136
137 =item $sha1->reset
138
139 This is just an alias for $sha1->new.
140
141 =item $sha1->clone
142
143 This a copy of the $sha1 object. It is useful when you do not want to
144 destroy the digests state, but need an intermediate value of the
145 digest, e.g. when calculating digests iteratively on a continuous data
146 stream. Example:
147
148 my $sha1 = Digest::SHA1->new;
149 while (<>) {
150 $sha1->add($_);
151 print "Line $.: ", $sha1->clone->hexdigest, "\n";
152 }
153
154 =item $sha1->add($data,...)
155
156 The $data provided as argument are appended to the message we
157 calculate the digest for. The return value is the $sha1 object itself.
158
159 All these lines will have the same effect on the state of the $sha1
160 object:
161
162 $sha1->add("a"); $sha1->add("b"); $sha1->add("c");
163 $sha1->add("a")->add("b")->add("c");
164 $sha1->add("a", "b", "c");
165 $sha1->add("abc");
166
167 =item $sha1->addfile($io_handle)
168
169 The $io_handle will be read until EOF and its content appended to the
170 message we calculate the digest for. The return value is the $sha1
171 object itself.
172
173 The addfile() method will croak() if it fails reading data for some
174 reason. If it croaks it is unpredictable what the state of the $sha1
175 object will be in. The addfile() method might have been able to read
176 the file partially before it failed. It is probably wise to discard
177 or reset the $sha1 object if this occurs.
178
179 In most cases you want to make sure that the $io_handle is in
180 C<binmode> before you pass it as argument to the addfile() method.
181
7b05b09 @gisle s/md5/sha1/
gisle authored
182 =item $sha1->add_bits($data, $nbits)
d8d9c08 @gisle Release 2.07
gisle authored
183
7b05b09 @gisle s/md5/sha1/
gisle authored
184 =item $sha1->add_bits($bitstring)
d8d9c08 @gisle Release 2.07
gisle authored
185
186 This implementation of SHA-1 only supports byte oriented input so you
187 might only add bits as multiples of 8. If you need bit level support
188 please consider using the C<Digest::SHA> module instead. The
189 add_bits() method is provided here for compatibility with other digest
190 implementations. See L<Digest> for description of the arguments that
191 add_bits() take.
192
5e6baf8 @gisle Copy documentation from Digest::MD5.
gisle authored
193 =item $sha1->digest
194
195 Return the binary digest for the message. The returned string will be
196 20 bytes long.
197
198 Note that the C<digest> operation is effectively a destructive,
199 read-once operation. Once it has been performed, the C<Digest::SHA1>
200 object is automatically C<reset> and can be used to calculate another
201 digest value. Call $sha1->clone->digest if you want to calculate the
202 digest without reseting the digest state.
203
204 =item $sha1->hexdigest
205
206 Same as $sha1->digest, but will return the digest in hexadecimal
207 form. The length of the returned string will be 40 and it will only
208 contain characters from this set: '0'..'9' and 'a'..'f'.
209
210 =item $sha1->b64digest
211
212 Same as $sha1->digest, but will return the digest as a base64 encoded
213 string. The length of the returned string will be 27 and it will only
214 contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+'
215 and '/'.
216
217
218 The base64 encoded string returned is not padded to be a multiple of 4
219 bytes long. If you want interoperability with other base64 encoded
7b05b09 @gisle s/md5/sha1/
gisle authored
220 SHA-1 digests you might want to append the string "=" to the result.
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
221
222 =back
223
224 =head1 SEE ALSO
225
d8d9c08 @gisle Release 2.07
gisle authored
226 L<Digest>, L<Digest::HMAC_SHA1>, L<Digest::SHA>, L<Digest::MD5>
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
227
228 http://www.itl.nist.gov/fipspubs/fip180-1.htm
229
6e33028 @gisle Mention that SHA-1 might be weak [RT#11880]
gisle authored
230 http://en.wikipedia.org/wiki/SHA_hash_functions
231
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
232 =head1 COPYRIGHT
233
234 This library is free software; you can redistribute it and/or
235 modify it under the same terms as Perl itself.
236
0fb2a99 @gisle Release 2.11.
gisle authored
237 Copyright 1999-2004 Gisle Aas.
35779fa @gisle Broken out of Digest-MD5-2.12
gisle authored
238 Copyright 1997 Uwe Hollerbach.
239
240 =head1 AUTHORS
241
242 Peter C. Gutmann,
243 Uwe Hollerbach <uh@alumni.caltech.edu>,
244 Gisle Aas <gisle@aas.no>
245
246 =cut
Something went wrong with that request. Please try again.