NAME

PerlCryptLib - Perl interface to Peter Guttman's cryptlib API

DESCRIPTION

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:

• http://www.cs.auckland.ac.nz/~pgut001/cryptlib

INSTALLATION

Starting from version 1.04, PerlCryptLib got the capability to match the correct version of the 'cryptlib' library used by the guest system. This is done translating on-the-fly the cryptlib.h header file into a correspondent Perl header file (named PerlCryptLib.ph) that will be used by the main module. PerlCryptLib need to know the path to cryptlib.h header file for the libcl installed in the system. You can set (export) environment variable PERL_CRYPT_LIB_HEADER or, alternatively, Makefile.PL try itself to search for cryptlib.h in /usr and /home directories. If it found more than one version of cryptlib.h, it will use the one with greater version number.

 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

cryptUIDisplayCert() and cryptUIGenerateKey() cryptlib functions are not implemented.

EXPORT/IMPORT

PerlCryptLib doesn't export anything by default. You can choose to explicitly import specifics 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, to import only functions name:

 use PerlCryptLib ':functions';

Alternatively, you can import such functions or constants by specifying each of them 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 is much more comprehensive.

Pass-by-reference

To pass-by-reference cryptlib object-handles, as shown in the above example in SYNOPSIS section, it's not necessary to use the 'back-slash' reference operator ('\').

Buffers

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

 my $maxLength = 1024;
 my $key = ' ' x $maxLength;
 cryptExportKey($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, MUST be declared as 0x0 scalar values:

 $null = 0x0;
 cryptExportKey($null, 0, $maxLength, $context, $cert);

Accessing low-level components

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";

Querying objects

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";

PREREQUIREMENT

• cryptlib v. 3.2.2 (or later)

  CRYPTLIB Security Toolkit(c) by Peter Guttman

SEE ALSO

See Peter Guttman's cryptlib web site:

• http://www.cs.auckland.ac.nz/~pgut001/cryptlib/

and cryptlib official mailing-list:

• http://news.gmane.org/gmane.comp.encryption.cryptlib

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/. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Alvaro Livraghi, <perlcryptlib@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2006-2010 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.

cpanm PerlCryptLib

perl -MCPAN -e shell
install PerlCryptLib