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

NAME

6       Crypt::GCrypt - Perl interface to the GNU Cryptographic library
7

SYNOPSIS

9         use Crypt::GCrypt;
10
11         my $cipher = Crypt::GCrypt->new(
12           type => 'cipher',
13           algorithm => 'aes',
14           mode => 'cbc'
15         );
16         $cipher->start('encrypting');
17
18         $cipher->setkey('my secret key');
19         $cipher->setiv('my init vector');
20
21         my $ciphertext  = $cipher->encrypt('plaintext');
22         $ciphertext .= $cipher->finish;
23
24         my $plaintext  = $cipher->decrypt($ciphertext);
25         $plaintext .= $cipher->finish;
26

ABSTRACT

28       Crypt::GCrypt provides an object interface to the C libgcrypt library.
29       It currently supports symmetric encryption/decryption and message
30       digests, while asymmetric cryptography is being worked on.
31

BINDING INFO

33   gcrypt_version()
34       Returns a string indicating the running version of gcrypt.
35
36   built_against_version()
37       Returns a string indicating the version of gcrypt that this module was
38       built against.  This is likely only to be useful in a debugging
39       situation.
40

SYMMETRIC CRYPTOGRAPHY

42   cipher_algo_available()
43       Determines whether a given cipher algorithm is available in the local
44       gcrypt installation:
45
46         if (Crypt::GCrypt::cipher_algo_available('aes')) {
47           # do stuff with aes
48         }
49
50   new()
51       In order to encrypt/decrypt your data using a symmetric cipher you
52       first have to build a Crypt::GCrypt object:
53
54         my $cipher = Crypt::GCrypt->new(
55           type => 'cipher',
56           algorithm => 'aes',
57           mode => 'cbc'
58         );
59
60       The type argument must be "cipher" and algorithm is required too. See
61       below for a description of available algorithms and other
62       initialization parameters:
63
64       algorithm
65           This may be one of the following:
66
67           3des    Triple-DES with 3 Keys as EDE.  The key size of this
68                   algorithm is 168 but you have to pass 192 bits because the
69                   most significant bits of each byte are ignored.
70
71           aes     AES (Rijndael) with a 128 bit key.
72
73           aes192  AES (Rijndael) with a 192 bit key.
74
75           aes256  AES (Rijndael) with a 256 bit key.
76
77           blowfish
78                   The blowfish algorithm. The current implementation allows
79                   only for a key size of 128 bits (and thus is not compatible
80                   with Crypt::Blowfish).
81
82           cast5   CAST128-5 block cipher algorithm.  The key size is 128
83                   bits.
84
85           des     Standard DES with a 56 bit key. You need to pass 64 bit but
86                   the high bits of each byte are ignored.  Note, that this is
87                   a weak algorithm which can be broken in reasonable time
88                   using a brute force approach.
89
90           twofish The Twofish algorithm with a 256 bit key.
91
92           twofish128
93                   The Twofish algorithm with a 128 bit key.
94
95           arcfour An algorithm which is 100% compatible with RSA Inc.'s RC4
96                   algorithm.  Note that this is a stream cipher and must be
97                   used very carefully to avoid a couple of weaknesses.
98
99       mode
100           This is a string specifying one of the following
101           encryption/decryption modes:
102
103           stream  only available for stream ciphers
104
105           ecb     doesn't use an IV, encrypts each block independently
106
107           cbc     the current ciphertext block is encryption of current
108                   plaintext block xor-ed with last ciphertext block
109
110           cfb     the current ciphertext block is the current plaintext block
111                   xor-ed with the current keystream block, which is the
112                   encryption of the last ciphertext block
113
114           ofb     the current ciphertext block is the current plaintext block
115                   xor-ed with the current keystream block, which is the
116                   encryption of the last keystream block
117
118           If no mode is specified then cbc is selected for block ciphers, and
119           stream for stream ciphers.
120
121       padding
122           When the last block of plaintext is shorter than the block size, it
123           must be padded before encryption. Padding should permit a safe
124           unpadding after decryption. Crypt::GCrypt currently supports two
125           methods:
126
127           standard
128                   This is also known as PKCS#5 padding, as it's binary safe.
129                   The string is padded with the number of bytes that should
130                   be truncated. It's compatible with Crypt::CBC.
131
132           null    Only for text strings. The block will be padded with null
133                   bytes (00). If the last block is a full block and blocksize
134                   is 8, a block of "0000000000000000" will be appended.
135
136           none    By setting the padding method to "none", Crypt::GCrypt will
137                   only accept a multiple of blklen as input for "encrypt()".
138
139       secure
140           If this option is set to a true value, all data associated with
141           this cipher will be put into non-swappable storage, if possible.
142
143       enable_sync
144           Enable the CFB sync operation.
145
146       Once you've got your cipher object the following methods are available:
147
148   start()
149          $cipher->start('encrypting');
150          $cipher->start('decrypting');
151
152       This method must be called before any call to setkey() or setiv(). It
153       prepares the cipher for encryption or decryption, resetting the
154       internal state.
155
156   setkey()
157          $cipher->setkey('my secret key');
158
159       Encryption and decryption operations will use this key until a
160       different one is set. If your key is shorter than the cipher's keylen
161       (see the "keylen" method) it will be zero-padded, if it is longer it
162       will be truncated.
163
164   setiv()
165          $cipher->setiv('my iv');
166
167       Set the initialisation vector for the next encrypt/decrypt operation.
168       If IV is missing a "standard" IV of all zero is used. The same IV is
169       set in newly created cipher objects.
170
171   encrypt()
172          $ciphertext = $cipher->encrypt($plaintext);
173
174       This method encrypts $plaintext with $cipher, returning the
175       corresponding ciphertext. The output is buffered; this means that
176       you'll only get multiples of $cipher's block size and that at the end
177       you'll have to call "finish()".
178
179   finish()
180           $ciphertext .= $cipher->finish;
181
182           $plaintext .= $cipher->finish;
183
184       The CBC algorithm must buffer data blocks internally until there are
185       even multiples of the encryption algorithm's blocksize (typically 8 or
186       16 bytes).  After the last call to encrypt() or decrypt() you should
187       call finish() to flush the internal buffer and return any leftover
188       data. This method will also take care of padding/unpadding of data (see
189       the "padding" option above).
190
191   decrypt()
192          $plaintext = $cipher->decrypt($ciphertext);
193
194       The counterpart to encrypt, decrypt takes a $ciphertext and produces
195       the original plaintext (given that the right key was used, of course).
196       The output is buffered; this means that you'll only get multiples of
197       $cipher's block size and that at the end you'll have to call
198       "finish()".
199
200   keylen()
201          print "Key length is " . $cipher->keylen();
202
203       Returns the number of bytes of keying material this cipher needs.
204
205   blklen()
206          print "Block size is " . $cipher->blklen();
207
208       As their name implies, block ciphers operate on blocks of data. This
209       method returns the size of this blocks in bytes for this particular
210       cipher. For stream ciphers 1 is returned, since this implementation
211       does not feed less than a byte into the cipher.
212
213   sync()
214          $cipher->sync();
215
216       Apply the CFB sync operation.
217

MESSAGE DIGESTS

219   digest_algo_available()
220       Determines whether a given digest algorithm is available in the local
221       gcrypt installation:
222
223          if (Crypt::GCrypt::digest_algo_available('sha256')) {
224             # do stuff with sha256
225          }
226
227   new()
228       In order to create a message digest, you first have to build a
229       Crypt::GCrypt object:
230
231         my $digest = Crypt::GCrypt->new(
232           type => 'digest',
233           algorithm => 'sha256',
234         );
235
236       The type argument must be "digest" and algorithm is required too. See
237       below for a description of available algorithms and other
238       initialization parameters:
239
240       algorithm
241           Depending on your available version of gcrypt, this can be one of
242           the following hash algorithms.  Note that some gcrypt installations
243           do not implement certain algorithms (see digest_algo_available()).
244
245           md4
246           md5
247           ripemd160
248           sha1
249           sha224
250           sha256
251           sha384
252           sha512
253           tiger192
254           whirlpool
255       secure
256           If this option is set to a true value, all data associated with
257           this digest will be put into non-swappable storage, if possible.
258
259       hmac
260           If the digest is expected to be used as a keyed-Hash Message
261           Authentication Code (HMAC), supply the key with this argument.  It
262           is good practice to ensure that the key is at least as long as the
263           digest used.
264
265       Once you've got your digest object the following methods are available:
266
267   digest_length()
268           my $len = $digest->digest_length();
269
270       Returns the length in bytes of the digest produced by this algorithm.
271
272   write()
273           $digest->write($data);
274
275       Feeds data into the hash context.  Once you have called read(), this
276       method can't be called anymore.
277
278   reset()
279       Re-initializes the digest with the same parameters it was initially
280       created with.  This allows write()ing again, after a call to read().
281
282   clone()
283       Creates a new digest object with the exact same internal state.  This
284       is useful if you want to retrieve intermediate digests (i.e.  read()
285       from the copy and continue write()ing to the original).
286
287   read()
288           my $md = $digest->read();
289
290       Completes the digest and return the resultant string.  You can call
291       this multiple times, and it will return the same information.  Once a
292       digest object has been read(), it may not be written to.
293

THREAD SAFETY

295       libgcrypt is initialized with support for Pthread, so this module
296       should be thread safe.
297

SEE ALSO

299       Crypt::GCrypt::MPI supports Multi-precision integers (bignum math)
300       using libgcrypt as the backend implementation.
301

BUGS AND FEEDBACK

303       There are no known bugs. You are very welcome to write mail to the
304       author (aar@cpan.org) with your contributions, comments, suggestions,
305       bug reports or complaints.
306

AUTHORS AND CONTRIBUTORS

308       Alessandro Ranellucci <aar@cpan.org>
309
310       Daniel Kahn Gillmor (message digests) <dkg@fifthhorseman.net>
311
313       Copyright (c) Alessandro Ranellucci.  Crypt::GCrypt is free software,
314       you may redistribute it and/or modify it under the same terms as Perl
315       itself.
316

ACKNOWLEDGEMENTS

318       This module was initially inspired by the GCrypt.pm bindings made by
319       Robert Bihlmeyer in 2002. Thanks to users who give feedback and submit
320       patches (see Changelog).
321

DISCLAIMER

323       This software is provided by the copyright holders and contributors
324       ``as is'' and any express or implied warranties, including, but not
325       limited to, the implied warranties of merchantability and fitness for a
326       particular purpose are disclaimed. In no event shall the regents or
327       contributors be liable for any direct, indirect, incidental, special,
328       exemplary, or consequential damages (including, but not limited to,
329       procurement of substitute goods or services; loss of use, data, or
330       profits; or business interruption) however caused and on any theory of
331       liability, whether in contract, strict liability, or tort (including
332       negligence or otherwise) arising in any way out of the use of this
333       software, even if advised of the possibility of such damage.
334
335
336
337perl v5.36.0                      2023-01-27                  Crypt::GCrypt(3)
Impressum