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   2350095 use strict;
  50         410  
  50         1450  
4 50     50   264 use warnings;
  50         86  
  50         6362  
5             our $VERSION = '0.079_007';
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         134  
  50         3688  
13             $Carp::Internal{(__PACKAGE__)}++;
14 50     50   14337 use CryptX;
  50         131  
  50         23769  
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 2942 my ($self, $file) = @_;
35              
36 1188         1634 my $handle;
37 1188 100       3376 if (ref(\$file) eq 'SCALAR') { #filename
38 1056 50       41161 open($handle, "<", $file) || croak "FATAL: cannot open '$file': $!";
39 1056         5214 binmode($handle);
40             }
41             else { #handle
42 132         245 $handle = $file
43             }
44 1188 50       3181 croak "FATAL: invalid handle" unless defined $handle;
45              
46 1188         1604 my $n;
47 1188         2165 my $buf = "";
48 1188         24857 while (($n = read($handle, $buf, 32*1024))) {
49 1188         49335 $self->add($buf)
50             }
51 1188 50       2654 croak "FATAL: read failed: $!" unless defined $n;
52              
53 1188         29192 return $self;
54             }
55              
56 0     0   0 sub CLONE_SKIP { 1 } # prevent cloning
57              
58             ### FUNCTIONS
59              
60 264     264 1 1375 sub digest_file { local $SIG{__DIE__} = \&CryptX::_croak; Crypt::Digest->new(shift)->addfile(@_)->digest }
  264         2191  
61 264     264 1 1646 sub digest_file_hex { local $SIG{__DIE__} = \&CryptX::_croak; Crypt::Digest->new(shift)->addfile(@_)->hexdigest }
  264         2329  
62 264     264 1 1251 sub digest_file_b64 { local $SIG{__DIE__} = \&CryptX::_croak; Crypt::Digest->new(shift)->addfile(@_)->b64digest }
  264         2336  
63 132     132 1 702 sub digest_file_b64u { local $SIG{__DIE__} = \&CryptX::_croak; Crypt::Digest->new(shift)->addfile(@_)->b64udigest }
  132         1185  
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