|
Packit Service |
b886ba |
package Digest::SHA1;
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
use strict;
|
|
Packit Service |
b886ba |
use vars qw($VERSION @ISA @EXPORT_OK);
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
$VERSION = '2.13';
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
require Exporter;
|
|
Packit Service |
b886ba |
*import = \&Exporter::import;
|
|
Packit Service |
b886ba |
@EXPORT_OK = qw(sha1 sha1_hex sha1_base64 sha1_transform);
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
require DynaLoader;
|
|
Packit Service |
b886ba |
@ISA=qw(DynaLoader);
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
eval {
|
|
Packit Service |
b886ba |
require Digest::base;
|
|
Packit Service |
b886ba |
push(@ISA, 'Digest::base');
|
|
Packit Service |
b886ba |
};
|
|
Packit Service |
b886ba |
if ($@) {
|
|
Packit Service |
b886ba |
my $err = $@;
|
|
Packit Service |
b886ba |
*add_bits = sub { die $err };
|
|
Packit Service |
b886ba |
}
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Digest::SHA1->bootstrap($VERSION);
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
1;
|
|
Packit Service |
b886ba |
__END__
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=head1 NAME
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Digest::SHA1 - Perl interface to the SHA-1 algorithm
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=head1 SYNOPSIS
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
# Functional style
|
|
Packit Service |
b886ba |
use Digest::SHA1 qw(sha1 sha1_hex sha1_base64);
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
$digest = sha1($data);
|
|
Packit Service |
b886ba |
$digest = sha1_hex($data);
|
|
Packit Service |
b886ba |
$digest = sha1_base64($data);
|
|
Packit Service |
b886ba |
$digest = sha1_transform($data);
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
# OO style
|
|
Packit Service |
b886ba |
use Digest::SHA1;
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
$sha1 = Digest::SHA1->new;
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
$sha1->add($data);
|
|
Packit Service |
b886ba |
$sha1->addfile(*FILE);
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
$sha1_copy = $sha1->clone;
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
$digest = $sha1->digest;
|
|
Packit Service |
b886ba |
$digest = $sha1->hexdigest;
|
|
Packit Service |
b886ba |
$digest = $sha1->b64digest;
|
|
Packit Service |
b886ba |
$digest = $sha1->transform;
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=head1 DESCRIPTION
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The C<Digest::SHA1> module allows you to use the NIST SHA-1 message
|
|
Packit Service |
b886ba |
digest algorithm from within Perl programs. The algorithm takes as
|
|
Packit Service |
b886ba |
input a message of arbitrary length and produces as output a 160-bit
|
|
Packit Service |
b886ba |
"fingerprint" or "message digest" of the input.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
In 2005, security flaws were identified in SHA-1, namely that a possible
|
|
Packit Service |
b886ba |
mathematical weakness might exist, indicating that a stronger hash function
|
|
Packit Service |
b886ba |
would be desirable. The L<Digest::SHA> module implements the stronger
|
|
Packit Service |
b886ba |
algorithms in the SHA family.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The C<Digest::SHA1> module provide a procedural interface for simple
|
|
Packit Service |
b886ba |
use, as well as an object oriented interface that can handle messages
|
|
Packit Service |
b886ba |
of arbitrary length and which can read files directly.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=head1 FUNCTIONS
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The following functions can be exported from the C<Digest::SHA1>
|
|
Packit Service |
b886ba |
module. No functions are exported by default.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=over 4
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item sha1($data,...)
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
This function will concatenate all arguments, calculate the SHA-1
|
|
Packit Service |
b886ba |
digest of this "message", and return it in binary form. The returned
|
|
Packit Service |
b886ba |
string will be 20 bytes long.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The result of sha1("a", "b", "c") will be exactly the same as the
|
|
Packit Service |
b886ba |
result of sha1("abc").
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item sha1_hex($data,...)
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Same as sha1(), but will return the digest in hexadecimal form. The
|
|
Packit Service |
b886ba |
length of the returned string will be 40 and it will only contain
|
|
Packit Service |
b886ba |
characters from this set: '0'..'9' and 'a'..'f'.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item sha1_base64($data,...)
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Same as sha1(), but will return the digest as a base64 encoded string.
|
|
Packit Service |
b886ba |
The length of the returned string will be 27 and it will only contain
|
|
Packit Service |
b886ba |
characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and
|
|
Packit Service |
b886ba |
'/'.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Note that the base64 encoded string returned is not padded to be a
|
|
Packit Service |
b886ba |
multiple of 4 bytes long. If you want interoperability with other
|
|
Packit Service |
b886ba |
base64 encoded sha1 digests you might want to append the redundant
|
|
Packit Service |
b886ba |
string "=" to the result.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item sha1_transform($data)
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Implements the basic SHA1 transform on a 64 byte block. The $data
|
|
Packit Service |
b886ba |
argument and the returned $digest are in binary form. This algorithm
|
|
Packit Service |
b886ba |
is used in NIST FIPS 186-2
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=back
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=head1 METHODS
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The object oriented interface to C<Digest::SHA1> is described in this
|
|
Packit Service |
b886ba |
section. After a C<Digest::SHA1> object has been created, you will add
|
|
Packit Service |
b886ba |
data to it and finally ask for the digest in a suitable format. A
|
|
Packit Service |
b886ba |
single object can be used to calculate multiple digests.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The following methods are provided:
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=over 4
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1 = Digest::SHA1->new
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The constructor returns a new C<Digest::SHA1> object which encapsulate
|
|
Packit Service |
b886ba |
the state of the SHA-1 message-digest algorithm.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
If called as an instance method (i.e. $sha1->new) it will just reset the
|
|
Packit Service |
b886ba |
state the object to the state of a newly created object. No new
|
|
Packit Service |
b886ba |
object is created in this case.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->reset
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
This is just an alias for $sha1->new.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->clone
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
This a copy of the $sha1 object. It is useful when you do not want to
|
|
Packit Service |
b886ba |
destroy the digests state, but need an intermediate value of the
|
|
Packit Service |
b886ba |
digest, e.g. when calculating digests iteratively on a continuous data
|
|
Packit Service |
b886ba |
stream. Example:
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
my $sha1 = Digest::SHA1->new;
|
|
Packit Service |
b886ba |
while (<>) {
|
|
Packit Service |
b886ba |
$sha1->add($_);
|
|
Packit Service |
b886ba |
print "Line $.: ", $sha1->clone->hexdigest, "\n";
|
|
Packit Service |
b886ba |
}
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->add($data,...)
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The $data provided as argument are appended to the message we
|
|
Packit Service |
b886ba |
calculate the digest for. The return value is the $sha1 object itself.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
All these lines will have the same effect on the state of the $sha1
|
|
Packit Service |
b886ba |
object:
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
$sha1->add("a"); $sha1->add("b"); $sha1->add("c");
|
|
Packit Service |
b886ba |
$sha1->add("a")->add("b")->add("c");
|
|
Packit Service |
b886ba |
$sha1->add("a", "b", "c");
|
|
Packit Service |
b886ba |
$sha1->add("abc");
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->addfile($io_handle)
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The $io_handle will be read until EOF and its content appended to the
|
|
Packit Service |
b886ba |
message we calculate the digest for. The return value is the $sha1
|
|
Packit Service |
b886ba |
object itself.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The addfile() method will croak() if it fails reading data for some
|
|
Packit Service |
b886ba |
reason. If it croaks it is unpredictable what the state of the $sha1
|
|
Packit Service |
b886ba |
object will be in. The addfile() method might have been able to read
|
|
Packit Service |
b886ba |
the file partially before it failed. It is probably wise to discard
|
|
Packit Service |
b886ba |
or reset the $sha1 object if this occurs.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
In most cases you want to make sure that the $io_handle is in
|
|
Packit Service |
b886ba |
C<binmode> before you pass it as argument to the addfile() method.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->add_bits($data, $nbits)
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->add_bits($bitstring)
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
This implementation of SHA-1 only supports byte oriented input so you
|
|
Packit Service |
b886ba |
might only add bits as multiples of 8. If you need bit level support
|
|
Packit Service |
b886ba |
please consider using the C<Digest::SHA> module instead. The
|
|
Packit Service |
b886ba |
add_bits() method is provided here for compatibility with other digest
|
|
Packit Service |
b886ba |
implementations. See L<Digest> for description of the arguments that
|
|
Packit Service |
b886ba |
add_bits() take.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->digest
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Return the binary digest for the message. The returned string will be
|
|
Packit Service |
b886ba |
20 bytes long.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Note that the C<digest> operation is effectively a destructive,
|
|
Packit Service |
b886ba |
read-once operation. Once it has been performed, the C<Digest::SHA1>
|
|
Packit Service |
b886ba |
object is automatically C<reset> and can be used to calculate another
|
|
Packit Service |
b886ba |
digest value. Call $sha1->clone->digest if you want to calculate the
|
|
Packit Service |
b886ba |
digest without reseting the digest state.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->hexdigest
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Same as $sha1->digest, but will return the digest in hexadecimal
|
|
Packit Service |
b886ba |
form. The length of the returned string will be 40 and it will only
|
|
Packit Service |
b886ba |
contain characters from this set: '0'..'9' and 'a'..'f'.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=item $sha1->b64digest
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Same as $sha1->digest, but will return the digest as a base64 encoded
|
|
Packit Service |
b886ba |
string. The length of the returned string will be 27 and it will only
|
|
Packit Service |
b886ba |
contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+'
|
|
Packit Service |
b886ba |
and '/'.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
The base64 encoded string returned is not padded to be a multiple of 4
|
|
Packit Service |
b886ba |
bytes long. If you want interoperability with other base64 encoded
|
|
Packit Service |
b886ba |
SHA-1 digests you might want to append the string "=" to the result.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=back
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=head1 SEE ALSO
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
L<Digest>, L<Digest::HMAC_SHA1>, L<Digest::SHA>, L<Digest::MD5>
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
http://www.itl.nist.gov/fipspubs/fip180-1.htm
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
http://en.wikipedia.org/wiki/SHA_hash_functions
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=head1 COPYRIGHT
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
This library is free software; you can redistribute it and/or
|
|
Packit Service |
b886ba |
modify it under the same terms as Perl itself.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Copyright 1999-2004 Gisle Aas.
|
|
Packit Service |
b886ba |
Copyright 1997 Uwe Hollerbach.
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=head1 AUTHORS
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
Peter C. Gutmann,
|
|
Packit Service |
b886ba |
Uwe Hollerbach <uh@alumni.caltech.edu>,
|
|
Packit Service |
b886ba |
Gisle Aas <gisle@aas.no>
|
|
Packit Service |
b886ba |
|
|
Packit Service |
b886ba |
=cut
|