PerlCryptLib - Perl interface to Peter Guttman's cryptlib API
PerlCryptLib is an interface module to access cryptlib API.
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.
For more information about cryptlib features and state-of-the-art, please visit its official web-site at:
In order to "make" PerlCryptLib properly you need cryptlib source distribution in your system and you have to modify the pre-processed line in PerlCryptLib.xs:
#include "../cryptlib322/cryptlib.h"
to point to cryptlib source-directory.
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();
}
cryptUIDisplayCert() and cryptUIGenerateKey() cryptlib functions are not implemented.
PerlCryptLib doesn't export anything by default. You can choose to explicitly import specifics exported tags:
all of the CRYPT_* constants and data-types (CRYPT_USER, CRYPT_KEYSET, etc.)
all of the crypt* API functions and macros (cryptInit, cryptImportKey, etc.)
all of the cryptlib constants, data-types and functions
For example, to import only function names:
use PerlCryptLib ':functions';
Alternatively, as usual, you can import such functions or constants by specifying each of them in the 'use' statement:
use PerlCryptLib qw(cryptInit cryptEnd CRYPT_OK);
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 is much more comprehensive.
To pass-by-reference cryptlib object-handles, as shown in the above example in SYNOPSIS section, don't use the 'back-slash' reference operator ('\').
To handle binary buffers (i.e., while enveloping data), you need to initialize them "allocating" the needed space, for example using:
my $buffer = ' ' x 1204;
NULL values can be handled in different ways:
# Those three calls are all valid 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, MUST be declared as 0x0 scalar values:
$null = 0x0; cryptExportKey($null, 0, $maxLength, $context, $cert); $key = ' ' x $maxLength; cryptExportKey($key, $maxLength, $keyLength, $context, $cert);
In order to allow the access to low-level components, I've made some small changes to the cryptlib macro cryptSetComponent(), for which 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 I've added a NEW low-level macro to retrieve data-structure in the appropriated format:
cryptFinalizeComponents($componentInfo, $blob, $size)Here is an example "translated" in 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 really needed) you can do as follow:
print "rsaKey modulus length: ", $rsaKey->{nLen}, "\n";
To query objects such exported keys, signatures or cryptlib capabilities, you can use standard functions cryptQueryObject() and cryptQueryCapability() as follow:
$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";
CRYPTLIB Security Toolkit(c) by Peter Guttman
enum - C style enumerated types and bitmask flags in Perl
Visit Peter Guttman's web site to get latest informations about cryptlib:
Visit cryptlib official mailing-list to get support over cryptlib itself:
Please report any bugs or feature requests to perlcryptlib@gmail.com, or through the web interface at http://rt.cpan.org/Public/. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
Alvaro Livraghi, <perlcryptlib@gmail.com>
Copyright (C) 2006 Alvaro Livraghi. All Rights Reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
