NAME¶
Rhash - Perl extension for LibRHash Hash library
SYNOPSIS¶
use Rhash;
my $msg = "a message text";
print "MD5 = " . Rhash->new(Rhash::MD5)->update($msg)->hash() . "\n";
# more complex example - calculate two hash functions simultaniously
my $r = Rhash->new(Rhash::MD5 | Rhash::SHA1);
$r->update("a message text")->update(" another message");
print "MD5 = ". $r->hash(Rhash::MD5) . "\n";
print "SHA1 = ". $r->hash(Rhash::SHA1) . "\n";
DESCRIPTION¶
Rhash module is an object-oriented interface to the LibRHash library, which
allows one to simultaniously calculate several hash functions for a file or a
text message.
SUPPORTED ALGORITHMS¶
The module supports the following hashing algorithms: CRC32, MD4, MD5, SHA1,
SHA256, SHA512, AICH, ED2K, Tiger, DC++ TTH, BitTorrent BTIH, GOST R 34.11-94,
RIPEMD-160, HAS-160, EDON-R 256/512, Whirlpool and Snefru-128/256.
CONSTRUCTOR¶
Creates and returns new Rhash object.
my $r = Rhash->new($hash_id);
my $p = new Rhash($hash_id); # alternative way to call the constructor
The $hash_id parameter can be union (via bitwise OR) of any of the following
bit-flags:
Rhash::CRC32,
Rhash::MD4,
Rhash::MD5,
Rhash::SHA1,
Rhash::TIGER,
Rhash::TTH,
Rhash::BTIH,
Rhash::ED2K,
Rhash::AICH,
Rhash::WHIRLPOOL,
Rhash::RIPEMD160,
Rhash::GOST,
Rhash::GOST_CRYPTOPRO,
Rhash::HAS160,
Rhash::SNEFRU128,
Rhash::SNEFRU256,
Rhash::SHA224,
Rhash::SHA256,
Rhash::SHA384,
Rhash::SHA512,
Rhash::EDONR256,
Rhash::EDONR512
Also the Rhash::ALL bit mask is the union of all listed bit-flags. So the object
created via Rhash->new(Rhash::ALL) calculates all supported hash functions
for the same data.
COMPUTING HASHES¶
- $rhash->update( $msg )
- Calculates hashes of the $msg string. The method can be
called repeatedly with chunks of the message to be hashed. It returns the
$rhash object itself allowing the following construct:
$rhash = Rhash->new(Rhash::MD5)->update( $chunk1 )->update( $chunk2 );
- $rhash->update_file( $file_path, $start, $size )
- $rhash->update_fd( $fd, $start, $size )
- Calculate a hash of the file (or its part) specified by
$file_path or a file descriptor $fd. The update_fd method doesn't close
the $fd, leaving the file position after the hashed block. The optional
$start and $size specify the block of the file to hash. No error is
reported if the $size is grater than the number of the unread bytes left
in the file.
Returns the number of characters actually read, 0 at end of file, or undef
if there was an error (in the latter case $! is also set).
use Rhash;
my $r = new Rhash(Rhash::SHA1);
open(my $fd, "<", "input.txt") or die "cannot open < input.txt: $!";
while ((my $n = $r->update_fd($fd, undef, 1024) != 0) {
print "$n bytes hashed. The SHA1 hash is " . $r->final()->hash() . "\n";
$r->reset();
}
defined($n) or die "read error for input.txt: $!";
close($fd);
- $rhash->final()
- Finishes calculation for all data buffered by updating
methods and stops hash calculation. The function is called automatically
by any of the $rhash->hash*() methods if the final() call was
skipped.
- $rhash->reset()
- Resets the $rhash object to the initial state.
- $rhash->hashed_length()
- Returns the total length of the hashed message.
- $rhash->hash_id()
- Returns the hash mask, the $rhash object was constructed
with.
Computed hash can be formated as a hexadecimal string (in the forward or reverse
byte order), a base32/base64-encoded string or as raw binary data.
- $rhash->hash( $hash_id )
- Returns the hash string in the default format, which can be
hexadecimal or base32. Actually the method is equvalent of
(Rhash::is_base32($hash_id) ? $rhash->hash_base32($hash_id) :
$rhash->hash_hex($hash_id))
If the optional $hash_id parameter is omited or zero, then the method
returns the hash for the algorithm contained in $rhash with the lowest
identifier.
- $rhash->hash_hex( $hash_id )
- Returns a specified hash in the hexadecimal format.
- $rhash->hash_rhex( $hash_id )
- Returns a hexadecimal string of the hash in reversed bytes
order. Some programs prefer to output GOST hash in this format.
- $rhash->hash_base32( $hash_id )
- Returns a specified hash in the base32 format.
- $rhash->hash_base64( $hash_id )
- Returns a specified hash in the base64 format.
- $rhash->magnet_link( $filename, $hash_mask )
- Returns the magnet link containing the computed hashes,
filesize, and, optionaly, $filename. The $filename (if specified) is
URL-encoded, by converting special characters into the
%<hexadecimal-code> form. The optional parameter $hash_mask can
limit which hash values to put into the link.
- Rhash::count()
- Returns the number of supported hash algorithms
- Rhash::is_base32($hash_id)
- Returns nonzero if default output format is Base32 for the
hash function specified by $hash_id. Retruns zero if default format is
hexadecimal.
- Rhash::get_digest_size($hash_id)
- Returns the size in bytes of raw binary hash of the
specified hash algorithm.
- Rhash::get_hash_length($hash_id)
- Returns the length of a hash string in default output
format for the specified hash algorithm.
- Rhash::get_name($hash_id)
- Returns the name of the specified hash algorithm.
ALTERNATIVE WAY TO COMPUTE HASH¶
- Rhash::msg($hash_id, $message)
- Computes and returns a single hash (in its default format)
of the $message by the selected hash algorithm.
use Rhash;
print "SHA1( 'abc' ) = " . Rhash::msg(Rhash::SHA1, "abc");
LICENSE¶
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so.
The Software is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. Use this program at your own risk!
