1Crypt::GCrypt(3) User Contributed Perl Documentation Crypt::GCrypt(3)
2
6 Crypt::GCrypt - Perl interface to the GNU Cryptographic library
7
9 use Crypt::GCrypt;
10 my $cipher = Crypt::GCrypt->new(
12 type => 'cipher',
13 algorithm => 'aes',
14 mode => 'cbc'
15 );
16 $cipher->start('encrypting');
17 $cipher->setkey('my secret key');
19 $cipher->setiv('my init vector');
20 my $ciphertext = $cipher->encrypt('plaintext');
22 $ciphertext .= $cipher->finish;
23 my $plaintext = $cipher->decrypt($ciphertext);
25 $plaintext .= $cipher->finish;
26
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
33 gcrypt_version()
34 Returns a string indicating the running version of gcrypt.
35 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
42 cipher_algo_available()
43 Determines whether a given cipher algorithm is available in the local
44 gcrypt installation:
45 if (Crypt::GCrypt::cipher_algo_available('aes')) {
47 # do stuff with aes
48 }
49 new()
51 In order to encrypt/decrypt your data using a symmetric cipher you
52 first have to build a Crypt::GCrypt object:
53 my $cipher = Crypt::GCrypt->new(
55 type => 'cipher',
56 algorithm => 'aes',
57 mode => 'cbc'
58 );
59 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 algorithm
65 This may be one of the following:
66 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 aes AES (Rijndael) with a 128 bit key.
72 aes192 AES (Rijndael) with a 192 bit key.
74 aes256 AES (Rijndael) with a 256 bit key.
76 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 cast5 CAST128-5 block cipher algorithm. The key size is 128
83 bits.
84 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 twofish The Twofish algorithm with a 256 bit key.
91 twofish128
93 The Twofish algorithm with a 128 bit key.
94 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 mode
100 This is a string specifying one of the following
101 encryption/decryption modes:
102 stream only available for stream ciphers
104 ecb doesn't use an IV, encrypts each block independently
106 cbc the current ciphertext block is encryption of current
108 plaintext block xor-ed with last ciphertext block
109 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 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 If no mode is specified then cbc is selected for block ciphers, and
119 stream for stream ciphers.
120 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 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 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 none By setting the padding method to "none", Crypt::GCrypt will
137 only accept a multiple of blklen as input for "encrypt()".
138 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 enable_sync
144 Enable the CFB sync operation.
145 Once you've got your cipher object the following methods are available:
147 start()
149 $cipher->start('encrypting');
150 $cipher->start('decrypting');
151 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 setkey()
157 $cipher->setkey('my secret key');
158 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 setiv()
165 $cipher->setiv('my iv');
166 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 encrypt()
172 $ciphertext = $cipher->encrypt($plaintext);
173 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 finish()
180 $ciphertext .= $cipher->finish;
181 $plaintext .= $cipher->finish;
183 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 decrypt()
192 $plaintext = $cipher->decrypt($ciphertext);
193 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 keylen()
201 print "Key length is " . $cipher->keylen();
202 Returns the number of bytes of keying material this cipher needs.
204 blklen()
206 print "Block size is " . $cipher->blklen();
207 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 sync()
214 $cipher->sync();
215 Apply the CFB sync operation.
217
219 digest_algo_available()
220 Determines whether a given digest algorithm is available in the local
221 gcrypt installation:
222 if (Crypt::GCrypt::digest_algo_available('sha256')) {
224 # do stuff with sha256
225 }
226 new()
228 In order to create a message digest, you first have to build a
229 Crypt::GCrypt object:
230 my $digest = Crypt::GCrypt->new(
232 type => 'digest',
233 algorithm => 'sha256',
234 );
235 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 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 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 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 Once you've got your digest object the following methods are available:
266 digest_length()
268 my $len = $digest->digest_length();
269 Returns the length in bytes of the digest produced by this algorithm.
271 write()
273 $digest->write($data);
274 Feeds data into the hash context. Once you have called read(), this
276 method can't be called anymore.
277 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 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 read()
288 my $md = $digest->read();
289 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
295 libgcrypt is initialized with support for Pthread, so this module
296 should be thread safe.
297
299 Crypt::GCrypt::MPI supports Multi-precision integers (bignum math)
300 using libgcrypt as the backend implementation.
301
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
308 Alessandro Ranellucci <aar@cpan.org>
309 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
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
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.
334perl v5.36.0 2023-01-27 Crypt::GCrypt(3)