PerlCryptLib(3)

📦
version 3.4.9.6 · 5 versions
, in fedora 43

💖 PerlCryptLib — the Perl glow-up for cryptlib 💖

okay bestie, gather round, because this is the Perl interface to Peter Guttman's cryptlib API and it's genuinely iconic. 💅

(this one lives in the User Contributed Perl Documentation section of your man pages, just so u know where u found it 🫶)

✨ NAME ✨

PerlCryptLib — it's the Perl interface to Peter Guttman's cryptlib API. no cap, that's the whole vibe.

🌸 DESCRIPTION 🌸

PerlCryptLib is an interface module to access the cryptlib API. literally its whole job. 💖

cryptlib (Copyright 1992-2005 Peter Gutmann. All rights reserved.) is a powerful encryption and security software toolkit that allows even inexperienced crypto-programmers to easily add world-leading encryption and authentication services to their software.

okay so — that's cryptlib hyping itself up, and honestly? it earned it. it lets even baby crypto-programmers (no shade, we've all been there 🥲) drop world-leading encryption and authentication into their software like it's nothing.

if u wanna know more about cryptlib features and its whole state-of-the-art situation, go check its official web-site:

🎀 INSTALLATION 🎀

so since version 1.04, PerlCryptLib got the ability to match whatever the correct version of the 'cryptlib' library is on the guest system. how? it translates the cryptlib.h header file on-the-fly into a corresponding Perl header file (named PerlCryptLib.ph) which the main module then uses. slay, honestly. ✨

but PerlCryptLib needs to know the path to the cryptlib.h header file for the libcl installed on the system. u can set (export) the environment variable PERL_CRYPT_LIB_HEADER, or alternatively Makefile.PL will try to search for cryptlib.h itself in the /usr and /home directories. and if it finds more than one version of cryptlib.h, it uses the one with the greater version number. it picks the main character fr. 👑

perl Makefile.PL
make
make test TEST_VERBOSE=1  # or, simply, the canonical  make test
sudo make install

⭐ SYNOPSIS ⭐

use PerlCryptLib qw(:all);

my $envelope = CRYPT_ENVELOPE;
if ( cryptInit() == CRYPT_OK ) {
  if ( cryptCreateEnvelope($envelope,
                           CRYPT_UNUSED,
                           CRYPT_FORMAT_CRYPTLIB) == CRYPT_OK ) {

    # set some attributes with cryptSetAttribute() or cryptSetAttributeString()
    # set some other crypto-stuff
    # push or pop data with cryptPushData() and cryptPopData()

    cryptDestroyEnvelope($envelope);
  }
  cryptEnd();
}

💭 Notes

just so we're clear, bestie: cryptUIDisplayCert() and cryptUIGenerateKey() cryptlib functions are not implemented. they just didn't show up to the party. 🙈

💅 EXPORT/IMPORT 💅

PerlCryptLib doesn't export anything by default. she's private like that. but u can choose to explicitly import specific exported tags:

  • :constants — all of the CRYPT_* cryptlib constants
  • :functions — all of the crypt* cryptlib functions
  • :all — all of the cryptlib constants and functions

for example, if u only wanna import functions:

use PerlCryptLib ':functions';

alternatively, u can import those functions or constants by naming each one right there in the use statement:

use PerlCryptLib qw(cryptInit cryptEnd CRYPT_OK);

🦋 CONVENTIONS 🦋

Object-type declaration

cryptlib object-handles MUST BE INITIALIZED with the appropriated object-type constant (CRYPT_CERTIFICATE, CRYPT_CONTEXT, CRYPT_DEVICE, CRYPT_ENVELOPE, CRYPT_KEYSET, CRYPT_SESSION, CRYPT_USER, CRYPT_HANDLE) or, at least, with a numeric value (generally 0).

so using

my $envelope = CRYPT_ENVELOPE;
my $context = CRYPT_CONTEXT;
my $certificate = CRYPT_CERTIFICATE;

is the same as using

my $envelope = 0;
my $context = 0;
my $certificate = 0;

...but it's much more comprehensive. like, one of these actually tells u what's happening. periodt. 💅

Pass-by-reference

to pass-by-reference cryptlib object-handles, as shown in the example up in the SYNOPSIS section, u don't need to use the 'back-slash' reference operator (\). it's giving effortless. ✨

Buffers

to handle binary buffers (i.e., while enveloping data), u need to initialize them by "allocating" the needed space, for example using:

my $maxLength = 1024;
my $key = ' ' x $maxLength;
cryptWrapKey($key, $maxLength, $keyLength, $context, $cert);

NULL values

NULL values can be handled in different ways:

# Those three calls are all valid calls
use constant NULL => 0x0;
$null = 0x0;
cryptGetPublicKey($cryptKeyset, $cert, CRYPT_KEYID_NONE, 0);
cryptGetPublicKey($cryptKeyset, $cert, CRYPT_KEYID_NONE, NULL);
cryptGetPublicKey($cryptKeyset, $cert, CRYPT_KEYID_NONE, $null);

However, when used in pass-by-reference calls, they MUST be declared as 0x0 scalar values:

$null = 0x0;
cryptWrapKey($null, 0, $maxLength, $context, $cert);
⚠️ bestie READ THIS ONE. the 0x0 scalar thing in pass-by-reference calls is not a suggestion, it's a MUST. don't be out here rolling the dice on your NULLs. 😭

Accessing low-level components

in order to allow access to low-level components, they made some small changes to the cryptlib macro cryptSetComponent(), for which the Perl syntax became:

cryptSetComponent($componentInfo, $element, $source, $length)

where $componentInfo is the data-structure itself and $element is the data-structure element-name to set. in addition, a NEW low-level macro was added to retrieve a data-structure in the appropriated format:

cryptFinalizeComponents($componentInfo, $blob, $size)

here's an example "translated" into PerlCryptLib:

##### Create objects
$cryptContext = CRYPT_CONTEXT;
$rsaKey = CRYPT_PKCINFO_RSA;

##### Initialize objects
cryptCreateContext($cryptContext, $cryptUser, CRYPT_ALGO_RSA);
cryptSetAttributeString($cryptContext, CRYPT_CTXINFO_LABEL, "RSA key", 7);
cryptInitComponents($rsaKey, CRYPT_KEYTYPE_PRIVATE);

##### Set data-structure elements: note arguments syntax
cryptSetComponent($rsaKey, 'n', $modulus, 2048);
cryptSetComponent($rsaKey, 'e', $pubExponent, 17);
cryptSetComponent($rsaKey, 'd', $privExponent, 2047);
cryptSetComponent($rsaKey, 'p', $primeFactor1, 1024);
cryptSetComponent($rsaKey, 'q', $primeFactor2, 1024);
cryptSetComponent($rsaKey, 'u', $multInverse, 1020);
cryptSetComponent($rsaKey, 'e1', $privExponent1, 1024);
cryptSetComponent($rsaKey, 'e2', $privExponent2, 1019);

##### Finalize component to retrieve data to pass to cryptSetAttributeString
$rsaKeyBlob = '';
$rsaKeyBlobSize = 0;
cryptFinalizeComponents($rsaKey, $rsaKeyBlob, $rsaKeyBlobSize);
cryptSetAttributeString($cryptContext, CRYPT_CTXINFO_KEY_COMPONENTS,
                        $rsaKeyBlob, $rsaKeyBlobSize );

##### Destroy objects
cryptDestroyComponents($rsaKey);
cryptDestroyContext($cryptContext);

Note: to access single data-structure elements (if u really need to), u can do this:

print "rsaKey modulus length: ", $rsaKey->{nLen}, "\n";

Querying objects

to query objects such as exported keys, signatures or cryptlib capabilities, u can use the standard functions cryptQueryObject() and cryptQueryCapability() like this:

$cryptObjectInfo = CRYPT_OBJECT_INFO;
cryptQueryObject($encryptedKey, $encryptedKeyLength, $cryptObjectInfo);
if ( $cryptObjectInfo->{objectType} == CRYPT_OBJECT_ENCRYPTED_KEY ) {
    warn "Import the key using conventional encryption!", "\n";
}

$cryptQueryInfo = CRYPT_QUERY_INFO;
cryptQueryCapability(CRYPT_ALGO_3DES, $cryptQueryInfo);
print "Algo-name: ", $cryptQueryInfo->{algoName}, "\n";

🌈 PREREQUIREMENT 🌈

  • cryptlib v. 3.2.2 (or later)

CRYPTLIB Security Toolkit(c) by Peter Guttman

like, u literally can't run this without it, so. get the lib bestie. 🫶

👀 SEE ALSO 👀

check out Peter Guttman's cryptlib web site:

and the cryptlib official mailing-list:

💀 BUGS AND REQUESTS 💀

please report any bugs or feature requests to perlcryptlib@gmail.com, or through the web interface at http://rt.cpan.org/Public/. u will be notified, and then u'll automatically be notified of progress on your bug as changes get made. so like, u don't have to chase anybody. the system handles it. iconic behavior actually. 🔥

👑 AUTHOR 👑

Alvaro Livraghi, <perlcryptlib@gmail.com>

Copyright (C) 2006-2010 Alvaro Livraghi. All Rights Reserved.

This library is free software; u can redistribute it and/or modify it under the same terms as Perl itself.

okay that's the whole thing, bestie, u made it to the end 💖 and for the record, this little doc was served up by perl v5.42.3, dated 2026-10-10, under the title PerlCryptLib(3). go encrypt something cute. mwah. 🧚🌸✨

📦 where this page comes from