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 algoritm
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
65        (simply any <FUNCNAME> for which there is Crypt::Digest::<FUNCNAME> module)
66
67   digest_data
68       Logically joins all arguments into a single string, and returns its
69       SHA1 digest encoded as a binary string.
70
71        $digest_raw = digest_data('SHA1', 'data string');
72        #or
73        $digest_raw = digest_data('SHA1', 'any data', 'more data', 'even more data');
74
75   digest_data_hex
76       Logically joins all arguments into a single string, and returns its
77       SHA1 digest encoded as a hexadecimal string.
78
79        $digest_hex = digest_data_hex('SHA1', 'data string');
80        #or
81        $digest_hex = digest_data_hex('SHA1', 'any data', 'more data', 'even more data');
82
83   digest_data_b64
84       Logically joins all arguments into a single string, and returns its
85       SHA1 digest encoded as a Base64 string, with trailing '=' padding.
86
87        $digest_b64 = digest_data_b64('SHA1', 'data string');
88        #or
89        $digest_b64 = digest_data_b64('SHA1', 'any data', 'more data', 'even more data');
90
91   digest_data_b64u
92       Logically joins all arguments into a single string, and returns its
93       SHA1 digest encoded as a Base64 URL Safe string (see RFC 4648 section
94       5).
95
96        $digest_b64url = digest_data_b64u('SHA1', 'data string');
97        #or
98        $digest_b64url = digest_data_b64u('SHA1', 'any data', 'more data', 'even more data');
99
100   digest_file
101       Reads file (defined by filename or filehandle) content, and returns its
102       digest encoded as a binary string.
103
104        $digest_raw = digest_file('SHA1', 'filename.dat');
105        #or
106        $digest_raw = digest_file('SHA1', *FILEHANDLE);
107
108   digest_file_hex
109       Reads file (defined by filename or filehandle) content, and returns its
110       digest encoded as a hexadecimal string.
111
112        $digest_hex = digest_file_hex('SHA1', 'filename.dat');
113        #or
114        $digest_hex = digest_file_hex('SHA1', *FILEHANDLE);
115
116       BEWARE: You have to make sure that the filehandle is in binary mode
117       before you pass it as argument to the addfile() method.
118
119   digest_file_b64
120       Reads file (defined by filename or filehandle) content, and returns its
121       digest encoded as a Base64 string, with trailing '=' padding.
122
123        $digest_b64 = digest_file_b64('SHA1', 'filename.dat');
124        #or
125        $digest_b64 = digest_file_b64('SHA1', *FILEHANDLE);
126
127   digest_file_b64u
128       Reads file (defined by filename or filehandle) content, and returns its
129       digest encoded as a Base64 URL Safe string (see RFC 4648 section 5).
130
131        $digest_b64url = digest_file_b64u('SHA1', 'filename.dat');
132        #or
133        $digest_b64url = digest_file_b64u('SHA1', *FILEHANDLE);
134

METHODS

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

NAME

SYNOPSIS

DESCRIPTION

EXPORT

FUNCTIONS

METHODS

SEE ALSO