1package Digest::SHA1; 2 3use strict; 4use vars qw($VERSION @ISA @EXPORT_OK); 5 6$VERSION = '2.13'; 7 8require Exporter; 9*import = \&Exporter::import; 10@EXPORT_OK = qw(sha1 sha1_hex sha1_base64 sha1_transform); 11 12require DynaLoader; 13@ISA=qw(DynaLoader); 14 15eval { 16 require Digest::base; 17 push(@ISA, 'Digest::base'); 18}; 19if ($@) { 20 my $err = $@; 21 *add_bits = sub { die $err }; 22} 23 24Digest::SHA1->bootstrap($VERSION); 25 261; 27__END__ 28 29=head1 NAME 30 31Digest::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 61The C<Digest::SHA1> module allows you to use the NIST SHA-1 message 62digest algorithm from within Perl programs. The algorithm takes as 63input a message of arbitrary length and produces as output a 160-bit 64"fingerprint" or "message digest" of the input. 65 66In 2005, security flaws were identified in SHA-1, namely that a possible 67mathematical weakness might exist, indicating that a stronger hash function 68would be desirable. The L<Digest::SHA> module implements the stronger 69algorithms in the SHA family. 70 71The C<Digest::SHA1> module provide a procedural interface for simple 72use, as well as an object oriented interface that can handle messages 73of arbitrary length and which can read files directly. 74 75=head1 FUNCTIONS 76 77The following functions can be exported from the C<Digest::SHA1> 78module. No functions are exported by default. 79 80=over 4 81 82=item sha1($data,...) 83 84This function will concatenate all arguments, calculate the SHA-1 85digest of this "message", and return it in binary form. The returned 86string will be 20 bytes long. 87 88The result of sha1("a", "b", "c") will be exactly the same as the 89result of sha1("abc"). 90 91=item sha1_hex($data,...) 92 93Same as sha1(), but will return the digest in hexadecimal form. The 94length of the returned string will be 40 and it will only contain 95characters from this set: '0'..'9' and 'a'..'f'. 96 97=item sha1_base64($data,...) 98 99Same as sha1(), but will return the digest as a base64 encoded string. 100The length of the returned string will be 27 and it will only contain 101characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and 102'/'. 103 104Note that the base64 encoded string returned is not padded to be a 105multiple of 4 bytes long. If you want interoperability with other 106base64 encoded sha1 digests you might want to append the redundant 107string "=" to the result. 108 109=item sha1_transform($data) 110 111Implements the basic SHA1 transform on a 64 byte block. The $data 112argument and the returned $digest are in binary form. This algorithm 113is used in NIST FIPS 186-2 114 115=back 116 117=head1 METHODS 118 119The object oriented interface to C<Digest::SHA1> is described in this 120section. After a C<Digest::SHA1> object has been created, you will add 121data to it and finally ask for the digest in a suitable format. A 122single object can be used to calculate multiple digests. 123 124The following methods are provided: 125 126=over 4 127 128=item $sha1 = Digest::SHA1->new 129 130The constructor returns a new C<Digest::SHA1> object which encapsulate 131the state of the SHA-1 message-digest algorithm. 132 133If called as an instance method (i.e. $sha1->new) it will just reset the 134state the object to the state of a newly created object. No new 135object is created in this case. 136 137=item $sha1->reset 138 139This is just an alias for $sha1->new. 140 141=item $sha1->clone 142 143This a copy of the $sha1 object. It is useful when you do not want to 144destroy the digests state, but need an intermediate value of the 145digest, e.g. when calculating digests iteratively on a continuous data 146stream. 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 156The $data provided as argument are appended to the message we 157calculate the digest for. The return value is the $sha1 object itself. 158 159All these lines will have the same effect on the state of the $sha1 160object: 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 169The $io_handle will be read until EOF and its content appended to the 170message we calculate the digest for. The return value is the $sha1 171object itself. 172 173The addfile() method will croak() if it fails reading data for some 174reason. If it croaks it is unpredictable what the state of the $sha1 175object will be in. The addfile() method might have been able to read 176the file partially before it failed. It is probably wise to discard 177or reset the $sha1 object if this occurs. 178 179In most cases you want to make sure that the $io_handle is in 180C<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 186This implementation of SHA-1 only supports byte oriented input so you 187might only add bits as multiples of 8. If you need bit level support 188please consider using the C<Digest::SHA> module instead. The 189add_bits() method is provided here for compatibility with other digest 190implementations. See L<Digest> for description of the arguments that 191add_bits() take. 192 193=item $sha1->digest 194 195Return the binary digest for the message. The returned string will be 19620 bytes long. 197 198Note that the C<digest> operation is effectively a destructive, 199read-once operation. Once it has been performed, the C<Digest::SHA1> 200object is automatically C<reset> and can be used to calculate another 201digest value. Call $sha1->clone->digest if you want to calculate the 202digest without reseting the digest state. 203 204=item $sha1->hexdigest 205 206Same as $sha1->digest, but will return the digest in hexadecimal 207form. The length of the returned string will be 40 and it will only 208contain characters from this set: '0'..'9' and 'a'..'f'. 209 210=item $sha1->b64digest 211 212Same as $sha1->digest, but will return the digest as a base64 encoded 213string. The length of the returned string will be 27 and it will only 214contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' 215and '/'. 216 217 218The base64 encoded string returned is not padded to be a multiple of 4 219bytes long. If you want interoperability with other base64 encoded 220SHA-1 digests you might want to append the string "=" to the result. 221 222=back 223 224=head1 SEE ALSO 225 226L<Digest>, L<Digest::HMAC_SHA1>, L<Digest::SHA>, L<Digest::MD5> 227 228http://www.itl.nist.gov/fipspubs/fip180-1.htm 229 230http://en.wikipedia.org/wiki/SHA_hash_functions 231 232=head1 COPYRIGHT 233 234This library is free software; you can redistribute it and/or 235modify 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 242Peter C. Gutmann, 243Uwe Hollerbach <uh@alumni.caltech.edu>, 244Gisle Aas <gisle@aas.no> 245 246=cut 247