Crypt::Digest(3pm)

1Crypt::Digest(3)      User Contributed Perl Documentation     Crypt::Digest(3)
2
3
4

NAME

6       Crypt::Digest - Generic interface to hash/digest functions
7

SYNOPSIS

9          ### Functional interface:
10          use Crypt::Digest qw( digest_data digest_data_hex digest_data_b64 digest_data_b64u
11                                digest_file digest_file_hex digest_file_b64 digest_file_b64u );
12
13          # calculate digest from string/buffer
14          $digest_raw  = digest_data('SHA1', 'data string');
15          $digest_hex  = digest_data_hex('SHA1', 'data string');
16          $digest_b64  = digest_data_b64('SHA1', 'data string');
17          $digest_b64u = digest_data_b64u('SHA1', 'data string');
18          # calculate digest from file
19          $digest_raw  = digest_file('SHA1', 'filename.dat');
20          $digest_hex  = digest_file_hex('SHA1', 'filename.dat');
21          $digest_b64  = digest_file_b64('SHA1', 'filename.dat');
22          $digest_b64u = digest_file_b64u('SHA1', 'filename.dat');
23          # calculate digest from filehandle
24          $digest_raw  = digest_file('SHA1', *FILEHANDLE);
25          $digest_hex  = digest_file_hex('SHA1', *FILEHANDLE);
26          $digest_b64  = digest_file_b64('SHA1', *FILEHANDLE);
27          $digest_b64u = digest_file_b64u('SHA1', *FILEHANDLE);
28
29          ### OO interface:
30          use Crypt::Digest;
31
32          $d = Crypt::Digest->new('SHA1');
33          $d->add('any data');
34          $d->addfile('filename.dat');
35          $d->addfile(*FILEHANDLE);
36          $result_raw  = $d->digest;     # raw bytes
37          $result_hex  = $d->hexdigest;  # hexadecimal form
38          $result_b64  = $d->b64digest;  # Base64 form
39          $result_b64u = $d->b64udigest; # Base64 URL Safe form
40

DESCRIPTION

42       Provides an interface to various hash/digest algorithms.
43

EXPORT

45       Nothing is exported by default.
46
47       You can export selected functions:
48
49         use Crypt::Digest qw( digest_data digest_data_hex digest_data_b64 digest_data_b64u
50                               digest_file digest_file_hex digest_file_b64 digest_file_b64u );
51
52       Or all of them at once:
53
54         use Crypt::Digest ':all';
55

FUNCTIONS

57       Please note that all functions take as its first argument the algorithm
58       name, supported values are:
59
60        'CHAES', 'MD2', 'MD4', 'MD5', 'RIPEMD128', 'RIPEMD160',
61        'RIPEMD256', 'RIPEMD320', 'SHA1', 'SHA224', 'SHA256',
62        'SHA384', 'SHA512', 'SHA512_224', 'SHA512_256', 'Tiger192', 'Whirlpool',
63        'SHA3_224', 'SHA3_256', 'SHA3_384', 'SHA3_512',
64        'BLAKE2b_160', 'BLAKE2b_256', 'BLAKE2b_384', 'BLAKE2b_512',
65        'BLAKE2s_128', 'BLAKE2s_160', 'BLAKE2s_224', 'BLAKE2s_256'
66
67        (simply any <NAME> for which there is Crypt::Digest::<NAME> module)
68
69   digest_data
70       Logically joins all arguments into a single string, and returns its
71       SHA1 digest encoded as a binary string.
72
73        $digest_raw = digest_data('SHA1', 'data string');
74        #or
75        $digest_raw = digest_data('SHA1', 'any data', 'more data', 'even more data');
76
77   digest_data_hex
78       Logically joins all arguments into a single string, and returns its
79       SHA1 digest encoded as a hexadecimal string.
80
81        $digest_hex = digest_data_hex('SHA1', 'data string');
82        #or
83        $digest_hex = digest_data_hex('SHA1', 'any data', 'more data', 'even more data');
84
85   digest_data_b64
86       Logically joins all arguments into a single string, and returns its
87       SHA1 digest encoded as a Base64 string, with trailing '=' padding.
88
89        $digest_b64 = digest_data_b64('SHA1', 'data string');
90        #or
91        $digest_b64 = digest_data_b64('SHA1', 'any data', 'more data', 'even more data');
92
93   digest_data_b64u
94       Logically joins all arguments into a single string, and returns its
95       SHA1 digest encoded as a Base64 URL Safe string (see RFC 4648 section
96       5).
97
98        $digest_b64url = digest_data_b64u('SHA1', 'data string');
99        #or
100        $digest_b64url = digest_data_b64u('SHA1', 'any data', 'more data', 'even more data');
101
102   digest_file
103       Reads file (defined by filename or filehandle) content, and returns its
104       digest encoded as a binary string.
105
106        $digest_raw = digest_file('SHA1', 'filename.dat');
107        #or
108        $digest_raw = digest_file('SHA1', *FILEHANDLE);
109
110   digest_file_hex
111       Reads file (defined by filename or filehandle) content, and returns its
112       digest encoded as a hexadecimal string.
113
114        $digest_hex = digest_file_hex('SHA1', 'filename.dat');
115        #or
116        $digest_hex = digest_file_hex('SHA1', *FILEHANDLE);
117
118       BEWARE: You have to make sure that the filehandle is in binary mode
119       before you pass it as argument to the addfile() method.
120
121   digest_file_b64
122       Reads file (defined by filename or filehandle) content, and returns its
123       digest encoded as a Base64 string, with trailing '=' padding.
124
125        $digest_b64 = digest_file_b64('SHA1', 'filename.dat');
126        #or
127        $digest_b64 = digest_file_b64('SHA1', *FILEHANDLE);
128
129   digest_file_b64u
130       Reads file (defined by filename or filehandle) content, and returns its
131       digest encoded as a Base64 URL Safe string (see RFC 4648 section 5).
132
133        $digest_b64url = digest_file_b64u('SHA1', 'filename.dat');
134        #or
135        $digest_b64url = digest_file_b64u('SHA1', *FILEHANDLE);
136

METHODS

138   new
139       Constructor, returns a reference to the digest object.
140
141        $d = Crypt::Digest->new($name);
142        # $name could be: 'CHAES', 'MD2', 'MD4', 'MD5', 'RIPEMD128', 'RIPEMD160',
143        #                 'RIPEMD256', 'RIPEMD320', 'SHA1', 'SHA224', 'SHA256', 'SHA384',
144        #                 'SHA512', 'SHA512_224', 'SHA512_256', 'Tiger192', 'Whirlpool'
145        #
146        # simply any <FUNCNAME> for which there is Crypt::Digest::<FUNCNAME> module
147
148   clone
149       Creates a copy of the digest object state and returns a reference to
150       the copy.
151
152        $d->clone();
153
154   reset
155       Reinitialize the digest object state and returns a reference to the
156       digest object.
157
158        $d->reset();
159
160   add
161       All arguments are appended to the message we calculate digest for.  The
162       return value is the digest object itself.
163
164        $d->add('any data');
165        #or
166        $d->add('any data', 'more data', 'even more data');
167
168       Note that all the following cases are equivalent:
169
170        # case 1
171        $d->add('aa', 'bb', 'cc');
172
173        # case 2
174        $d->add('aa');
175        $d->add('bb');
176        $d->add('cc');
177
178        # case 3
179        $d->add('aabbcc');
180
181        # case 4
182        $d->add('aa')->add('bb')->add('cc');
183
184   addfile
185       The content of the file (or filehandle) is appended to the message we
186       calculate digest for.  The return value is the digest object itself.
187
188        $d->addfile('filename.dat');
189        #or
190        $d->addfile(*FILEHANDLE);
191
192       BEWARE: You have to make sure that the filehandle is in binary mode
193       before you pass it as argument to the addfile() method.
194
195   add_bits
196       This method is available mostly for compatibility with other
197       Digest::SOMETHING modules on CPAN, you are very unlikely to need it.
198       The return value is the digest object itself.
199
200        $d->add_bits($bit_string);   # e.g. $d->add_bits("111100001010");
201        #or
202        $d->add_bits($data, $nbits); # e.g. $d->add_bits("\xF0\xA0", 16);
203
204       BEWARE: It is not possible to add bits that are not a multiple of 8.
205
206   hashsize
207       Returns the length of calculated digest in bytes (e.g. 32 for SHA-256).
208
209        $d->hashsize;
210        #or
211        Crypt::Digest->hashsize('SHA1');
212        #or
213        Crypt::Digest::hashsize('SHA1');
214
215   digest
216       Returns the binary digest (raw bytes).
217
218        $result_raw = $d->digest();
219
220   hexdigest
221       Returns the digest encoded as a hexadecimal string.
222
223        $result_hex = $d->hexdigest();
224
225   b64digest
226       Returns the digest encoded as a Base64 string, with trailing '='
227       padding (BEWARE: this padding style might differ from other
228       Digest::<SOMETHING> modules on CPAN).
229
230        $result_b64 = $d->b64digest();
231
232   b64udigest
233       Returns the digest encoded as a Base64 URL Safe string (see RFC 4648
234       section 5).
235
236        $result_b64url = $d->b64udigest();
237

NAME

SYNOPSIS

DESCRIPTION

EXPORT

FUNCTIONS

METHODS

SEE ALSO