File Coverage

blib/lib/Crypt/Digest.pm
Criterion Covered Total %
statement 33 34 97.0
branch 5 8 62.5
condition n/a
subroutine 9 10 90.0
pod 5 5 100.0
total 52 57 91.2


line stmt bran cond sub pod time code
1             package Crypt::Digest;
2              
3 50     50   2344352 use strict;
  50         421  
  50         1515  
4 50     50   267 use warnings;
  50         108  
  50         6332  
5             our $VERSION = '0.080_001';
6              
7             require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import';
8             our %EXPORT_TAGS = ( all => [qw( digest_data digest_data_hex digest_data_b64 digest_data_b64u digest_file digest_file_hex digest_file_b64 digest_file_b64u )] );
9             our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10             our @EXPORT = qw();
11              
12 50     50   396 use Carp;
  50         114  
  50         4073  
13             $Carp::Internal{(__PACKAGE__)}++;
14 50     50   14042 use CryptX;
  50         121  
  50         23853  
15              
16             ### the following methods/functions are implemented in XS:
17             # - new
18             # - hashsize
19             # - clone
20             # - reset
21             # - digest
22             # - hexdigest
23             # - b64digest
24             # - add
25             # - digest_data
26             # - digest_data_hex
27             # - digest_data_b64
28             # - digest_data_b64u
29             # - DESTROY
30              
31             ### METHODS
32              
33             sub addfile {
34 1188     1188 1 3006 my ($self, $file) = @_;
35              
36 1188         1653 my $handle;
37 1188 100       3547 if (ref(\$file) eq 'SCALAR') { #filename
38 1056 50       41214 open($handle, "<", $file) || croak "FATAL: cannot open '$file': $!";
39 1056         4813 binmode($handle);
40             }
41             else { #handle
42 132         254 $handle = $file
43             }
44 1188 50       3167 croak "FATAL: invalid handle" unless defined $handle;
45              
46 1188         1680 my $n;
47 1188         2190 my $buf = "";
48 1188         22771 while (($n = read($handle, $buf, 32*1024))) {
49 1188         48992 $self->add($buf)
50             }
51 1188 50       2695 croak "FATAL: read failed: $!" unless defined $n;
52              
53 1188         30200 return $self;
54             }
55              
56 0     0   0 sub CLONE_SKIP { 1 } # prevent cloning
57              
58             ### FUNCTIONS
59              
60 264     264 1 1348 sub digest_file { local $SIG{__DIE__} = \&CryptX::_croak; Crypt::Digest->new(shift)->addfile(@_)->digest }
  264         2285  
61 264     264 1 1285 sub digest_file_hex { local $SIG{__DIE__} = \&CryptX::_croak; Crypt::Digest->new(shift)->addfile(@_)->hexdigest }
  264         2381  
62 264     264 1 1269 sub digest_file_b64 { local $SIG{__DIE__} = \&CryptX::_croak; Crypt::Digest->new(shift)->addfile(@_)->b64digest }
  264         2424  
63 132     132 1 744 sub digest_file_b64u { local $SIG{__DIE__} = \&CryptX::_croak; Crypt::Digest->new(shift)->addfile(@_)->b64udigest }
  132         1254  
64              
65             1;
66              
67             =pod
68              
69             =head1 NAME
70              
71             Crypt::Digest - Generic interface to hash/digest functions
72              
73             =head1 SYNOPSIS
74              
75             ### Functional interface:
76             use Crypt::Digest qw( digest_data digest_data_hex digest_data_b64 digest_data_b64u
77             digest_file digest_file_hex digest_file_b64 digest_file_b64u );
78              
79             # calculate digest from string/buffer
80             $digest_raw = digest_data('SHA1', 'data string');
81             $digest_hex = digest_data_hex('SHA1', 'data string');
82             $digest_b64 = digest_data_b64('SHA1', 'data string');
83             $digest_b64u = digest_data_b64u('SHA1', 'data string');
84             # calculate digest from file
85             $digest_raw = digest_file('SHA1', 'filename.dat');
86             $digest_hex = digest_file_hex('SHA1', 'filename.dat');
87             $digest_b64 = digest_file_b64('SHA1', 'filename.dat');
88             $digest_b64u = digest_file_b64u('SHA1', 'filename.dat');
89             # calculate digest from filehandle
90             $digest_raw = digest_file('SHA1', *FILEHANDLE);
91             $digest_hex = digest_file_hex('SHA1', *FILEHANDLE);
92             $digest_b64 = digest_file_b64('SHA1', *FILEHANDLE);
93             $digest_b64u = digest_file_b64u('SHA1', *FILEHANDLE);
94              
95             ### OO interface:
96             use Crypt::Digest;
97              
98             $d = Crypt::Digest->new('SHA1');
99             $d->add('any data');
100             $d->addfile('filename.dat');
101             $d->addfile(*FILEHANDLE);
102             $result_raw = $d->digest; # raw bytes
103             $result_hex = $d->hexdigest; # hexadecimal form
104             $result_b64 = $d->b64digest; # Base64 form
105             $result_b64u = $d->b64udigest; # Base64 URL Safe form
106              
107             =head1 DESCRIPTION
108              
109             Provides an interface to various hash/digest algorithms.
110              
111             =head1 EXPORT
112              
113             Nothing is exported by default.
114              
115             You can export selected functions:
116              
117             use Crypt::Digest qw( digest_data digest_data_hex digest_data_b64 digest_data_b64u
118             digest_file digest_file_hex digest_file_b64 digest_file_b64u );
119              
120             Or all of them at once:
121              
122             use Crypt::Digest ':all';
123              
124             =head1 FUNCTIONS
125              
126             Please note that all functions take as its first argument the algorithm name, supported values are:
127              
128             'CHAES', 'MD2', 'MD4', 'MD5', 'RIPEMD128', 'RIPEMD160',
129             'RIPEMD256', 'RIPEMD320', 'SHA1', 'SHA224', 'SHA256',
130             'SHA384', 'SHA512', 'SHA512_224', 'SHA512_256', 'Tiger192', 'Whirlpool',
131             'SHA3_224', 'SHA3_256', 'SHA3_384', 'SHA3_512',
132             'BLAKE2b_160', 'BLAKE2b_256', 'BLAKE2b_384', 'BLAKE2b_512',
133             'BLAKE2s_128', 'BLAKE2s_160', 'BLAKE2s_224', 'BLAKE2s_256'
134              
135             (simply any for which there is Crypt::Digest:: module)
136              
137             =head2 digest_data
138              
139             Logically joins all arguments into a single string, and returns its SHA1 digest encoded as a binary string.
140              
141             $digest_raw = digest_data('SHA1', 'data string');
142             #or
143             $digest_raw = digest_data('SHA1', 'any data', 'more data', 'even more data');
144              
145             =head2 digest_data_hex
146              
147             Logically joins all arguments into a single string, and returns its SHA1 digest encoded as a hexadecimal string.
148              
149             $digest_hex = digest_data_hex('SHA1', 'data string');
150             #or
151             $digest_hex = digest_data_hex('SHA1', 'any data', 'more data', 'even more data');
152              
153             =head2 digest_data_b64
154              
155             Logically joins all arguments into a single string, and returns its SHA1 digest encoded as a Base64 string, B trailing '=' padding.
156              
157             $digest_b64 = digest_data_b64('SHA1', 'data string');
158             #or
159             $digest_b64 = digest_data_b64('SHA1', 'any data', 'more data', 'even more data');
160              
161             =head2 digest_data_b64u
162              
163             Logically joins all arguments into a single string, and returns its SHA1 digest encoded as a Base64 URL Safe string (see RFC 4648 section 5).
164              
165             $digest_b64url = digest_data_b64u('SHA1', 'data string');
166             #or
167             $digest_b64url = digest_data_b64u('SHA1', 'any data', 'more data', 'even more data');
168              
169             =head2 digest_file
170              
171             Reads file (defined by filename or filehandle) content, and returns its digest encoded as a binary string.
172              
173             $digest_raw = digest_file('SHA1', 'filename.dat');
174             #or
175             $digest_raw = digest_file('SHA1', *FILEHANDLE);
176              
177             =head2 digest_file_hex
178              
179             Reads file (defined by filename or filehandle) content, and returns its digest encoded as a hexadecimal string.
180              
181             $digest_hex = digest_file_hex('SHA1', 'filename.dat');
182             #or
183             $digest_hex = digest_file_hex('SHA1', *FILEHANDLE);
184              
185             B You have to make sure that the filehandle is in binary mode before you pass it as argument to the addfile() method.
186              
187             =head2 digest_file_b64
188              
189             Reads file (defined by filename or filehandle) content, and returns its digest encoded as a Base64 string, B trailing '=' padding.
190              
191             $digest_b64 = digest_file_b64('SHA1', 'filename.dat');
192             #or
193             $digest_b64 = digest_file_b64('SHA1', *FILEHANDLE);
194              
195             =head2 digest_file_b64u
196              
197             Reads file (defined by filename or filehandle) content, and returns its digest encoded as a Base64 URL Safe string (see RFC 4648 section 5).
198              
199             $digest_b64url = digest_file_b64u('SHA1', 'filename.dat');
200             #or
201             $digest_b64url = digest_file_b64u('SHA1', *FILEHANDLE);
202              
203             =head1 METHODS
204              
205             =head2 new
206              
207             Constructor, returns a reference to the digest object.
208              
209             $d = Crypt::Digest->new($name);
210             # $name could be: 'CHAES', 'MD2', 'MD4', 'MD5', 'RIPEMD128', 'RIPEMD160',
211             # 'RIPEMD256', 'RIPEMD320', 'SHA1', 'SHA224', 'SHA256', 'SHA384',
212             # 'SHA512', 'SHA512_224', 'SHA512_256', 'Tiger192', 'Whirlpool'
213             #
214             # simply any for which there is Crypt::Digest:: module
215              
216             =head2 clone
217              
218             Creates a copy of the digest object state and returns a reference to the copy.
219              
220             $d->clone();
221              
222             =head2 reset
223              
224             Reinitialize the digest object state and returns a reference to the digest object.
225              
226             $d->reset();
227              
228             =head2 add
229              
230             All arguments are appended to the message we calculate digest for.
231             The return value is the digest object itself.
232              
233             $d->add('any data');
234             #or
235             $d->add('any data', 'more data', 'even more data');
236              
237             Note that all the following cases are equivalent:
238              
239             # case 1
240             $d->add('aa', 'bb', 'cc');
241              
242             # case 2
243             $d->add('aa');
244             $d->add('bb');
245             $d->add('cc');
246              
247             # case 3
248             $d->add('aabbcc');
249              
250             # case 4
251             $d->add('aa')->add('bb')->add('cc');
252              
253             =head2 addfile
254              
255             The content of the file (or filehandle) is appended to the message we calculate digest for.
256             The return value is the digest object itself.
257              
258             $d->addfile('filename.dat');
259             #or
260             $d->addfile(*FILEHANDLE);
261              
262             B You have to make sure that the filehandle is in binary mode before you pass it as argument to the addfile() method.
263              
264             =head2 add_bits
265              
266             This method is available mostly for compatibility with other Digest::SOMETHING modules on CPAN, you are very unlikely to need it.
267             The return value is the digest object itself.
268              
269             $d->add_bits($bit_string); # e.g. $d->add_bits("111100001010");
270             #or
271             $d->add_bits($data, $nbits); # e.g. $d->add_bits("\xF0\xA0", 16);
272              
273             B It is not possible to add bits that are not a multiple of 8.
274              
275             =head2 hashsize
276              
277             Returns the length of calculated digest in bytes (e.g. 32 for SHA-256).
278              
279             $d->hashsize;
280             #or
281             Crypt::Digest->hashsize('SHA1');
282             #or
283             Crypt::Digest::hashsize('SHA1');
284              
285             =head2 digest
286              
287             Returns the binary digest (raw bytes).
288              
289             $result_raw = $d->digest();
290              
291             =head2 hexdigest
292              
293             Returns the digest encoded as a hexadecimal string.
294              
295             $result_hex = $d->hexdigest();
296              
297             =head2 b64digest
298              
299             Returns the digest encoded as a Base64 string, B trailing '=' padding (B this padding
300             style might differ from other Digest:: modules on CPAN).
301              
302             $result_b64 = $d->b64digest();
303              
304             =head2 b64udigest
305              
306             Returns the digest encoded as a Base64 URL Safe string (see RFC 4648 section 5).
307              
308             $result_b64url = $d->b64udigest();
309              
310             =head1 SEE ALSO
311              
312             =over
313              
314             =item * L
315              
316             =item * L tries to be compatible with L interface.
317              
318             =item * Check subclasses like L, L, ...
319              
320             =back
321              
322             =cut