/ 
PerlCryptLib-1.05
River stage zero No dependents
/ 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

INSTALLATION

Starting from version 1.04, PerlCryptLib has the ablility to match the correct version of the 'cryptlib' library used by your 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 /home directory.

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