NAME
Crypt::Digest - Generic interface to hash/digest functions
SYNOPSIS
### Functional interface:
use Crypt::Digest qw( digest_data digest_data_hex digest_data_b64 digest_data_b64u
digest_file digest_file_hex digest_file_b64 digest_file_b64u );
my $data = 'data string';
my $filename = 'filename.dat';
open my $filehandle, '<:raw', $filename or die "cannot open $filename: $!";
# calculate digest from string/buffer
my $digest_raw = digest_data('SHA256', $data);
my $digest_hex = digest_data_hex('SHA256', $data);
my $digest_b64 = digest_data_b64('SHA256', $data);
my $digest_b64u = digest_data_b64u('SHA256', $data);
# calculate digest from file
my $file_digest_raw = digest_file('SHA256', $filename);
my $file_digest_hex = digest_file_hex('SHA256', $filename);
my $file_digest_b64 = digest_file_b64('SHA256', $filename);
my $file_digest_b64u = digest_file_b64u('SHA256', $filename);
# calculate digest from filehandle
my $fh_digest_raw = digest_file('SHA256', $filehandle);
### OO interface:
use Crypt::Digest;
my $d = Crypt::Digest->new('SHA1');
$d->add('any data');
$d->addfile('filename.dat');
$d->addfile($filehandle);
my $result_raw = $d->digest; # raw bytes
my $result_hex = $d->hexdigest; # hexadecimal form
my $result_b64 = $d->b64digest; # Base64 form
my $result_b64u = $d->b64udigest; # Base64 URL Safe formDESCRIPTION
Provides an interface to various hash/digest algorithms.
All functions and methods return raw bytes unless the method name explicitly ends in _hex, _b64, or _b64u. Invalid algorithm names croak.
EXPORT
Nothing is exported by default.
You can export selected functions:
use Crypt::Digest qw( digest_data digest_data_hex digest_data_b64 digest_data_b64u
digest_file digest_file_hex digest_file_b64 digest_file_b64u );Or all of them at once:
use Crypt::Digest ':all';FUNCTIONS
Please note that all functions take as its first argument the algorithm name, supported values are:
'CHAES', 'MD2', 'MD4', 'MD5', 'RIPEMD128', 'RIPEMD160',
'RIPEMD256', 'RIPEMD320', 'SHA1', 'SHA224', 'SHA256',
'SHA384', 'SHA512', 'SHA512_224', 'SHA512_256', 'Tiger192', 'Whirlpool',
'SHA3_224', 'SHA3_256', 'SHA3_384', 'SHA3_512',
'Keccak224', 'Keccak256', 'Keccak384', 'Keccak512',
'BLAKE2b_160', 'BLAKE2b_256', 'BLAKE2b_384', 'BLAKE2b_512',
'BLAKE2s_128', 'BLAKE2s_160', 'BLAKE2s_224', 'BLAKE2s_256'
(simply any <NAME> for which there is Crypt::Digest::<NAME> module)digest_data
Logically joins all arguments into a single string, and returns the digest for the selected algorithm encoded as a binary string.
Data arguments are converted to byte strings using Perl's usual scalar stringification. Defined scalars, including numbers and string-overloaded objects, are accepted. undef is treated as an empty string and may emit Perl's usual "uninitialized value" warning. The same rules apply to digest_data_hex, digest_data_b64, and digest_data_b64u.
my $digest_raw = digest_data('SHA256', 'data string');
#or
my $digest_raw = digest_data('SHA256', 'any data', 'more data', 'even more data');digest_data_hex
Logically joins all arguments into a single string, and returns the digest for the selected algorithm encoded as a hexadecimal string.
my $digest_hex = digest_data_hex('SHA256', 'data string');
#or
my $digest_hex = digest_data_hex('SHA256', 'any data', 'more data', 'even more data');digest_data_b64
Logically joins all arguments into a single string, and returns the digest for the selected algorithm encoded as a Base64 string, with trailing '=' padding.
my $digest_b64 = digest_data_b64('SHA256', 'data string');
#or
my $digest_b64 = digest_data_b64('SHA256', 'any data', 'more data', 'even more data');digest_data_b64u
Logically joins all arguments into a single string, and returns the digest for the selected algorithm encoded as a Base64 URL Safe string (see RFC 4648 section 5).
my $digest_b64url = digest_data_b64u('SHA256', 'data string');
#or
my $digest_b64url = digest_data_b64u('SHA256', 'any data', 'more data', 'even more data');digest_file
Reads file (defined by filename or filehandle) content, and returns its digest encoded as a binary string.
my $digest_raw = digest_file('SHA256', 'filename.dat');
#or
my $filehandle = ...; # existing binary-mode filehandle
my $digest_raw = digest_file('SHA256', $filehandle);digest_file_hex
Reads file (defined by filename or filehandle) content, and returns its digest encoded as a hexadecimal string.
my $digest_hex = digest_file_hex('SHA256', 'filename.dat');
#or
my $filehandle = ...; # existing binary-mode filehandle
my $digest_hex = digest_file_hex('SHA256', $filehandle);BEWARE: You have to make sure that the filehandle is in binary mode before you pass it as argument to the addfile() method.
digest_file_b64
Reads file (defined by filename or filehandle) content, and returns its digest encoded as a Base64 string, with trailing '=' padding.
my $digest_b64 = digest_file_b64('SHA256', 'filename.dat');
#or
my $filehandle = ...; # existing binary-mode filehandle
my $digest_b64 = digest_file_b64('SHA256', $filehandle);digest_file_b64u
Reads file (defined by filename or filehandle) content, and returns its digest encoded as a Base64 URL Safe string (see RFC 4648 section 5).
my $digest_b64url = digest_file_b64u('SHA256', 'filename.dat');
#or
my $filehandle = ...; # existing binary-mode filehandle
my $digest_b64url = digest_file_b64u('SHA256', $filehandle);METHODS
Unless noted otherwise, assume $d is an existing digest object created via new, for example:
my $d = Crypt::Digest->new('SHA256');new
Constructor, returns a reference to the digest object.
my $d = Crypt::Digest->new($name);
# $name could be: 'CHAES', 'MD2', 'MD4', 'MD5', 'RIPEMD128', 'RIPEMD160',
# 'RIPEMD256', 'RIPEMD320', 'SHA1', 'SHA224', 'SHA256', 'SHA384',
# 'SHA512', 'SHA512_224', 'SHA512_256', 'SHA3_224', 'SHA3_256',
# 'SHA3_384', 'SHA3_512', 'Keccak224', 'Keccak256', 'Keccak384',
# 'Keccak512', 'BLAKE2b_160', 'BLAKE2b_256', 'BLAKE2b_384',
# 'BLAKE2b_512', 'BLAKE2s_128', 'BLAKE2s_160', 'BLAKE2s_224',
# 'BLAKE2s_256', 'Tiger192', 'Whirlpool'
#
# simply any <FUNCNAME> for which there is Crypt::Digest::<FUNCNAME> moduleclone
Creates a copy of the digest object state and returns a reference to the copy.
$d->clone();reset
Reinitialize the digest object state and returns a reference to the digest object.
$d->reset();add
All arguments are appended to the message we calculate digest for. The return value is the digest object itself.
Each argument is converted to bytes using Perl's usual scalar stringification. Defined scalars, including numbers and string-overloaded objects, are accepted. undef is treated as an empty string and may emit Perl's usual "uninitialized value" warning.
$d->add('any data');
#or
$d->add('any data', 'more data', 'even more data');Note that all the following cases are equivalent:
# case 1
$d->add('aa', 'bb', 'cc');
# case 2
$d->add('aa');
$d->add('bb');
$d->add('cc');
# case 3
$d->add('aabbcc');
# case 4
$d->add('aa')->add('bb')->add('cc');addfile
The content of the file (or filehandle) is appended to the message we calculate digest for. The return value is the digest object itself.
$d->addfile('filename.dat');
#or
my $filehandle = ...; # existing binary-mode filehandle
$d->addfile($filehandle);BEWARE: You have to make sure that the filehandle is in binary mode before you pass it as argument to the addfile() method.
hashsize
Returns the length of calculated digest in bytes (e.g. 32 for SHA-256).
$d->hashsize;
#or
Crypt::Digest->hashsize('SHA1');
#or
Crypt::Digest::hashsize('SHA1');digest
Returns the binary digest (raw bytes). The first call finalizes the digest object. Any later add(), addfile(), digest(), hexdigest(), b64digest(), or b64udigest() call will fail until you call reset().
my $result_raw = $d->digest();hexdigest
Returns the digest encoded as a hexadecimal string. Like digest(), the first call finalizes the digest object.
my $result_hex = $d->hexdigest();b64digest
Returns the digest encoded as a Base64 string, with trailing '=' padding (BEWARE: this padding style might differ from other Digest::<SOMETHING> modules on CPAN). Like digest(), the first call finalizes the digest object.
my $result_b64 = $d->b64digest();b64udigest
Returns the digest encoded as a Base64 URL Safe string (see RFC 4648 section 5). Like digest(), the first call finalizes the digest object.
my $result_b64url = $d->b64udigest();SEE ALSO
Crypt::Digest tries to be compatible with Digest interface.
Check subclasses like Crypt::Digest::SHA1, Crypt::Digest::MD5, ...