"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style:
standard) with prefixed line numbers and
code folding option.
Alternatively you can here
view or
download the uninterpreted source code file.
For more information about "SHA1.pm" see the
Fossies "Dox" file reference documentation.
1 package Digest::SHA1;
2
3 use strict;
4 use vars qw($VERSION @ISA @EXPORT_OK);
5
6 $VERSION = '2.13';
7
8 require Exporter;
9 *import = \&Exporter::import;
10 @EXPORT_OK = qw(sha1 sha1_hex sha1_base64 sha1_transform);
11
12 require DynaLoader;
13 @ISA=qw(DynaLoader);
14
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);
25
26 1;
27 __END__
28
29 =head1 NAME
30
31 Digest::SHA1 - Perl interface to the SHA-1 algorithm
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);
41 $digest = sha1_transform($data);
42
43
44 # OO style
45 use Digest::SHA1;
46
47 $sha1 = Digest::SHA1->new;
48
49 $sha1->add($data);
50 $sha1->addfile(*FILE);
51
52 $sha1_copy = $sha1->clone;
53
54 $digest = $sha1->digest;
55 $digest = $sha1->hexdigest;
56 $digest = $sha1->b64digest;
57 $digest = $sha1->transform;
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
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
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
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").
90
91 =item sha1_hex($data,...)
92
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'.
96
97 =item sha1_base64($data,...)
98
99 Same as sha1(), but will return the digest as a base64 encoded string.
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 '/'.
103
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
109 =item sha1_transform($data)
110
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
114
115 =back
116
117 =head1 METHODS
118
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.
123
124 The following methods are provided:
125
126 =over 4
127
128 =item $sha1 = Digest::SHA1->new
129
130 The constructor returns a new C<Digest::SHA1> object which encapsulate
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
182 =item $sha1->add_bits($data, $nbits)
183
184 =item $sha1->add_bits($bitstring)
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
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
220 SHA-1 digests you might want to append the string "=" to the result.
221
222 =back
223
224 =head1 SEE ALSO
225
226 L<Digest>, L<Digest::HMAC_SHA1>, L<Digest::SHA>, L<Digest::MD5>
227
228 http://www.itl.nist.gov/fipspubs/fip180-1.htm
229
230 http://en.wikipedia.org/wiki/SHA_hash_functions
231
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
237 Copyright 1999-2004 Gisle Aas.
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