/ 
PerlCryptLib-1.03
/ PerlCryptLib

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

PRE-INSTALLATION NOTES

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.

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_* constants and data-types (CRYPT_USER, CRYPT_KEYSET, etc.)

:functions

all of the crypt* API functions and macros (cryptInit, cryptImportKey, etc.)

:all

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

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, don't 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 $buffer = ' ' x 1204;

NULL values

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

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

    CRYPTLIB Security Toolkit(c) by Peter Guttman

  • enum-1.016

    enum - C style enumerated types and bitmask flags in Perl

SEE ALSO

Visit Peter Guttman's web site to get latest informations about cryptlib:

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

Visit cryptlib official mailing-list to get support over cryptlib itself:

  • 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 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.