Crypt::GCrypt(3pm)

📦
version 1.26 · 8 versions
, in ubuntu stonking

🌸 Crypt::GCrypt 🌸

okay bestie, this is the manual page for Crypt::GCrypt(3pm) and it's genuinely iconic — it's the Perl interface to the GNU Cryptographic library, aka libgcrypt, and we're gonna walk through the whole thing together. grab a strawberry 🍓 and let's go.

✨ NAME ✨

Crypt::GCrypt — Perl interface to the GNU Cryptographic library. that's it, that's the vibe. 💅

🦋 SYNOPSIS 🦋

here's the whole flow, start to finish:

use Crypt::GCrypt;

my $cipher = Crypt::GCrypt->new(
  type => 'cipher',
  algorithm => 'aes',
  mode => 'cbc'
);
$cipher->start('encrypting');

$cipher->setkey('my secret key');
$cipher->setiv('my init vector');

my $ciphertext  = $cipher->encrypt('plaintext');
$ciphertext .= $cipher->finish;

my $plaintext  = $cipher->decrypt($ciphertext);
$plaintext .= $cipher->finish;

look at that. encrypt, finish, decrypt, finish. chef's kiss 👑

💜 ABSTRACT 💜

so Crypt::GCrypt gives you an object interface to the C libgcrypt library. right now it supports symmetric encryption/decryption and message digests, and asymmetric cryptography is being worked on — it's giving "coming soon, stay tuned" energy. 👀

🎀 BINDING INFO 🎀

gcrypt_version()

returns a string that tells you the running version of gcrypt. literally just vibes-checking which gcrypt you're actually running.

built_against_version()

returns a string telling you the version of gcrypt that this module was built against. bestie, this is likely only to be useful in a debugging situation — so if you're not debugging, don't stress about it. 🔧

🌈 SYMMETRIC CRYPTOGRAPHY 🌈

cipher_algo_available()

figures out whether a given cipher algorithm is available in your local gcrypt installation:

if (Crypt::GCrypt::cipher_algo_available('aes')) {
  # do stuff with aes
}

check first, then do stuff. that's the move. ✨

new()

to encrypt/decrypt your data with a symmetric cipher, first you gotta build a Crypt::GCrypt object:

my $cipher = Crypt::GCrypt->new(
  type => 'cipher',
  algorithm => 'aes',
  mode => 'cbc'
);

the type argument must be "cipher", and algorithm is required too. now here's the description of the available algorithms and all the other init parameters, no skips:

  • algorithm — this may be one of the following:
    • 3des — Triple-DES with 3 Keys as EDE. the key size of this algorithm is 168 but you have to pass 192 bits because the most significant bits of each byte are ignored.
    • aes — AES (Rijndael) with a 128 bit key.
    • aes192 — AES (Rijndael) with a 192 bit key.
    • aes256 — AES (Rijndael) with a 256 bit key.
    • blowfish — the blowfish algorithm. the current implementation allows only for a key size of 128 bits (and thus is not compatible with Crypt::Blowfish).
    • cast5 — CAST128-5 block cipher algorithm. the key size is 128 bits.
    • des — Standard DES with a 56 bit key. you need to pass 64 bit but the high bits of each byte are ignored. > ⚠️ note, that this is a weak algorithm which can be broken in reasonable time using a brute force approach. so like… don't, bestie. 💀
    • twofish — the Twofish algorithm with a 256 bit key.
    • twofish128 — the Twofish algorithm with a 128 bit key.
    • arcfour — an algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm. note that this is a stream cipher and must be used very carefully to avoid a couple of weaknesses. 🙈
  • mode — a string specifying one of the following encryption/decryption modes:
    • stream — only available for stream ciphers.
    • ecb — doesn't use an IV, encrypts each block independently.
    • cbc — the current ciphertext block is encryption of current plaintext block xor-ed with last ciphertext block.
    • cfb — the current ciphertext block is the current plaintext block xor-ed with the current keystream block, which is the encryption of the last ciphertext block.
    • ofb — the current ciphertext block is the current plaintext block xor-ed with the current keystream block, which is the encryption of the last keystream block.

if no mode is specified then cbc is selected for block ciphers, and stream for stream ciphers. defaults, slay. ✨

  • padding — when the last block of plaintext is shorter than the block size, it must be padded before encryption. padding should permit a safe unpadding after decryption. Crypt::GCrypt currently supports two methods… okay technically it lists three, here they all are:
    • standard — this is also known as PKCS#5 padding, as it's binary safe. the string is padded with the number of bytes that should be truncated. it's compatible with Crypt::CBC.
    • null — only for text strings. the block will be padded with null bytes (00). if the last block is a full block and blocksize is 8, a block of 0000000000000000 will be appended.
    • none — by setting the padding method to "none", Crypt::GCrypt will only accept a multiple of blklen as input for encrypt().
  • secure — if this option is set to a true value, all data associated with this cipher will be put into non-swappable storage, if possible. keeping it safe in RAM, we love to see it. 🫶
  • enable_sync — enable the CFB sync operation.

once you've got your cipher object, the following methods are available:

start()

$cipher->start('encrypting');
$cipher->start('decrypting');

this method must be called before any call to setkey() or setiv(). it prepares the cipher for encryption or decryption, resetting the internal state. it's the little "okay we're doing this now" moment. 💫

setkey()

$cipher->setkey('my secret key');

encryption and decryption operations will use this key until a different one is set. if your key is shorter than the cipher's keylen (see the "keylen" method) it will be zero-padded, if it is longer it will be truncated. the algorithm said what it said. 🤷♀️

setiv()

$cipher->setiv('my iv');

set the initialisation vector for the next encrypt/decrypt operation. if the IV is missing, a "standard" IV of all zero is used. the same IV is set in newly created cipher objects.

encrypt()

$ciphertext = $cipher->encrypt($plaintext);

this method encrypts $plaintext with $cipher, returning the corresponding ciphertext. the output is buffered — this means that you'll only get multiples of $cipher's block size and that at the end you'll have to call "finish()". don't forget the finish, fr fr. 😤

finish()

$ciphertext .= $cipher->finish;

$plaintext .= $cipher->finish;

the CBC algorithm must buffer data blocks internally until there are even multiples of the encryption algorithm's blocksize (typically 8 or 16 bytes). after the last call to encrypt() or decrypt() you should call finish() to flush the internal buffer and return any leftover data. this method will also take care of padding/unpadding of data (see the "padding" option above). it's the closer, the final rose ceremony. 🌹

decrypt()

$plaintext = $cipher->decrypt($ciphertext);

the counterpart to encrypt — decrypt takes a $ciphertext and produces the original plaintext (given that the right key was used, of course 😌). the output is buffered — you'll only get multiples of $cipher's block size and at the end you'll have to call "finish()". same rules, same energy.

keylen()

print "Key length is " . $cipher->keylen();

returns the number of bytes of keying material this cipher needs. ✨

blklen()

print "Block size is " . $cipher->blklen();

as the name implies, block ciphers operate on blocks of data. this method returns the size of these blocks in bytes for this particular cipher. for stream ciphers, 1 is returned, since this implementation does not feed less than a byte into the cipher. tiny but mighty. 🐛

sync()

$cipher->sync();

apply the CFB sync operation.

🧚 MESSAGE DIGESTS 🧚

digest_algo_available()

figures out whether a given digest algorithm is available in your local gcrypt installation:

if (Crypt::GCrypt::digest_algo_available('sha256')) {
   # do stuff with sha256
}

new()

to create a message digest, you first have to build a Crypt::GCrypt object:

my $digest = Crypt::GCrypt->new(
  type => 'digest',
  algorithm => 'sha256',
);

the type argument must be "digest" and algorithm is required too. here's the rundown of available algorithms and other initialization parameters:

  • algorithm — depending on your available version of gcrypt, this can be one of the following hash algorithms. note that some gcrypt installations do not implement certain algorithms (see digest_algo_available()).
    • md4
    • md5
    • ripemd160
    • sha1
    • sha224
    • sha256
    • sha384
    • sha512
    • tiger192
    • whirlpool
  • secure — if this option is set to a true value, all data associated with this digest will be put into non-swappable storage, if possible.
  • hmac — if the digest is expected to be used as a keyed-Hash Message Authentication Code (HMAC), supply the key with this argument. it is good practice to ensure that the key is at least as long as the digest used. bestie that's not a suggestion, that's good practice. 🔐

once you've got your digest object, the following methods are available:

digest_length()

my $len = $digest->digest_length();

returns the length in bytes of the digest produced by this algorithm.

write()

$digest->write($data);

feeds data into the hash context. once you have called read(), this method can't be called anymore. 🚫

reset()

re-initializes the digest with the same parameters it was initially created with. this allows write()ing again, after a call to read(). it's the glow-up comeback. 💅

clone()

creates a new digest object with the exact same internal state. this is useful if you want to retrieve intermediate digests (i.e. read() from the copy and continue write()ing to the original). parallel processing moment. ✨

read()

my $md = $digest->read();

completes the digest and returns the resultant string. you can call this multiple times, and it will return the same information. once a digest object has been read(), it may not be written to. no take-backs. 😭

🌸 THREAD SAFETY 🌸

libgcrypt is initialized with support for Pthread, so this module should be thread safe. should! it's giving responsible and stable. 🫶

⭐ SEE ALSO ⭐

Crypt::GCrypt::MPI supports Multi-precision integers (bignum math) using libgcrypt as the backend implementation. that's the other one, go check it out too. 👑

💖 BUGS AND FEEDBACK 💖

There are no known bugs. iconic behaviour honestly. you are very welcome to write mail to the author (aar@cpan.org) with your contributions, comments, suggestions, bug reports or complaints. complaints are literally listed, so bring them. 📬

👑 AUTHORS AND CONTRIBUTORS 👑

  • Alessandro Ranellucci <aar@cpan.org>
  • Daniel Kahn Gillmor (message digests) <dkg@fifthhorseman.net>

Copyright (c) Alessandro Ranellucci. Crypt::GCrypt is free software, you may redistribute it and/or modify it under the same terms as Perl itself. periodt.

🎀 ACKNOWLEDGEMENTS 🎀

this module was initially inspired by the GCrypt.pm bindings made by Robert Bihlmeyer in 2002. thanks to users who give feedback and submit patches (see Changelog). the community said "we got you" and meant it. 🫶

💀 DISCLAIMER 💀

okay bestie, legal o'clock, and no i'm not kidding around this time 🙈

This software is handed to you by the copyright holders and contributors exactly as-is — ``as is'' — and they're not promising you anything. Like, no express or implied warranties at all, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. all of those are disclaimed, gone, not a thing. 💅

And in no event shall the regents or the contributors be liable for any damages — direct, indirect, incidental, special, exemplary, or consequential — including but not limited to:

  • procurement of substitute goods or services 🛒
  • loss of use, data, or profits 😭
  • business interruption 💀

...and that's regardless of how it happened and on any theory of liability whatsoever — whether in contract, strict liability, or tort (including negligence or otherwise) — arising in any way out of the use of this software.

and yes, this holds even if they were advised of the possibility of such damage. they know the risk exists, they're still not liable. periodt. ✨

ngl bestie, that's a whole lot of "we warned you" energy, but it's the real deal — it's giving very much "read before you ship to prod" 🫶

and that's a wrap on the whole page!! 🎀 thanks for reading all the way through, you're genuinely the main character for that 👑

this little legend came from the Crypt::GCrypt(3pm) manual, generated with perl v5.42.3, all the way back on 2026-08-20. go encrypt something cute, stay safe out there, and remember: always check your return values 🌈💖🦋

📦 where this page comes from