1PerlCryptLib(3)       User Contributed Perl Documentation      PerlCryptLib(3)
2
3
4

NAME

6       PerlCryptLib - Perl interface to Peter Guttman's cryptlib API
7

DESCRIPTION

9       PerlCryptLib is an interface module to access cryptlib API.
10
11               cryptlib (Copyright 1992-2005 Peter Gutmann. All rights
12               reserved.) is a powerful encryption and security software
13               toolkit that allows even inexperienced crypto-programmers to
14               easily add world-leading encryption and authentication services
15               to their software.
16
17               For more information about cryptlib features and state-of-the-
18               art, please visit its official web-site at:
19
20               ·   http://www.cs.auckland.ac.nz/~pgut001/cryptlib
21

INSTALLATION

23       Starting from version 1.04, PerlCryptLib got the capability to match
24       the correct version of the 'cryptlib' library used by the guest system.
25       This is done translating on-the-fly the cryptlib.h header file into a
26       correspondent Perl header file (named PerlCryptLib.ph) that will be
27       used by the main module.  PerlCryptLib need to know the path to
28       cryptlib.h header file for the libcl installed in the system.  You can
29       set (export) environment variable PERL_CRYPT_LIB_HEADER or,
30       alternatively, Makefile.PL try itself to search for cryptlib.h in /usr
31       and /home directories.  If it found more than one version of
32       cryptlib.h, it will use the one with greater version number.
33
34        perl Makefile.PL
35        make
36        make test TEST_VERBOSE=1  # or, simply, the canonical  make test
37        sudo make install
38

SYNOPSIS

40        use PerlCryptLib qw(:all);
41
42        my $envelope = CRYPT_ENVELOPE;
43        if ( cryptInit() == CRYPT_OK ) {
44          if ( cryptCreateEnvelope($envelope,
45                                   CRYPT_UNUSED,
46                                   CRYPT_FORMAT_CRYPTLIB) == CRYPT_OK ) {
47
48            # set some attributes with cryptSetAttribute() or cryptSetAttributeString()
49            # set some other crypto-stuff
50            # push or pop data with cryptPushData() and cryptPopData()
51
52            cryptDestroyEnvelope($envelope);
53          }
54          cryptEnd();
55        }
56
57   Notes
58       cryptUIDisplayCert() and cryptUIGenerateKey() cryptlib functions are
59       not implemented.
60

EXPORT/IMPORT

62       PerlCryptLib doesn't export anything by default.  You can choose to
63       explicitly import specifics exported tags:
64
65       :constants
66           all of the CRYPT_* cryptlib constants
67
68       :functions
69           all of the crypt* cryptlib functions
70
71       :all
72           all of the cryptlib constants and functions
73
74       For example, to import only functions name:
75
76        use PerlCryptLib ':functions';
77
78       Alternatively, you can import such functions or constants by specifying
79       each of them in the 'use' statement:
80
81        use PerlCryptLib qw(cryptInit cryptEnd CRYPT_OK);
82

CONVENTIONS

84   Object-type declaration
85           cryptlib object-handles MUST BE INITIALIZED with the appropriated
86           object-type constant (CRYPT_CERTIFICATE, CRYPT_CONTEXT,
87           CRYPT_DEVICE, CRYPT_ENVELOPE, CRYPT_KEYSET, CRYPT_SESSION,
88           CRYPT_USER, CRYPT_HANDLE) or, at least, with a numeric value
89           (generally 0).
90
91           So, using
92
93            my $envelope = CRYPT_ENVELOPE;
94            my $context = CRYPT_CONTEXT;
95            my $certificate = CRYPT_CERTIFICATE;
96
97           is the same as using
98
99            my $envelope = 0;
100            my $context = 0;
101            my $certificate = 0;
102
103           but is much more comprehensive.
104
105   Pass-by-reference
106           To pass-by-reference cryptlib object-handles, as shown in the above
107           example in SYNOPSIS section, it's not necessary to use the
108           'back-slash' reference operator ('\').
109
110   Buffers
111           To handle binary buffers (i.e., while enveloping data), you need to
112           initialize them "allocating" the needed space, for example using:
113
114            my $maxLength = 1024;
115            my $key = ' ' x $maxLength;
116            cryptExportKey($key, $maxLength, $keyLength, $context, $cert);
117
118   NULL values
119           NULL values can be handled in different ways:
120
121            # Those three calls are all valid calls
122            use constant NULL => 0x0;
123            $null = 0x0;
124            cryptGetPublicKey($cryptKeyset, $cert, CRYPT_KEYID_NONE, 0);
125            cryptGetPublicKey($cryptKeyset, $cert, CRYPT_KEYID_NONE, NULL);
126            cryptGetPublicKey($cryptKeyset, $cert, CRYPT_KEYID_NONE, $null);
127
128           However, when used in pass-by-reference calls, MUST be declared as
129           0x0 scalar values:
130
131            $null = 0x0;
132            cryptExportKey($null, 0, $maxLength, $context, $cert);
133
134   Accessing low-level components
135           In order to allow the access to low-level components, I've made
136           some small changes to the cryptlib macro cryptSetComponent(), for
137           which Perl syntax became:
138
139            cryptSetComponent($componentInfo, $element, $source, $length)
140
141           where $componentInfo is the data-structure itself and $element is
142           the data-structure element-name to set.  In addition I've added a
143           NEW low-level macro to retrieve data-structure in the appropriated
144           format:
145
146            cryptFinalizeComponents($componentInfo, $blob, $size)
147
148           Here is an example "translated" in PerlCryptLib:
149
150            ##### Create objects
151            $cryptContext = CRYPT_CONTEXT;
152            $rsaKey = CRYPT_PKCINFO_RSA;
153
154            ##### Initialize objects
155            cryptCreateContext($cryptContext, $cryptUser, CRYPT_ALGO_RSA);
156            cryptSetAttributeString($cryptContext, CRYPT_CTXINFO_LABEL, "RSA key", 7);
157            cryptInitComponents($rsaKey, CRYPT_KEYTYPE_PRIVATE);
158
159            ##### Set data-structure elements: note arguments syntax
160            cryptSetComponent($rsaKey, 'n', $modulus, 2048);
161            cryptSetComponent($rsaKey, 'e', $pubExponent, 17);
162            cryptSetComponent($rsaKey, 'd', $privExponent, 2047);
163            cryptSetComponent($rsaKey, 'p', $primeFactor1, 1024);
164            cryptSetComponent($rsaKey, 'q', $primeFactor2, 1024);
165            cryptSetComponent($rsaKey, 'u', $multInverse, 1020);
166            cryptSetComponent($rsaKey, 'e1', $privExponent1, 1024);
167            cryptSetComponent($rsaKey, 'e2', $privExponent2, 1019);
168
169            ##### Finalize component to retrieve data to pass to cryptSetAttributeString
170            $rsaKeyBlob = '';
171            $rsaKeyBlobSize = 0;
172            cryptFinalizeComponents($rsaKey, $rsaKeyBlob, $rsaKeyBlobSize);
173            cryptSetAttributeString($cryptContext, CRYPT_CTXINFO_KEY_COMPONENTS,
174                                    $rsaKeyBlob, $rsaKeyBlobSize );
175
176            ##### Destroy objects
177            cryptDestroyComponents($rsaKey);
178            cryptDestroyContext($cryptContext);
179
180           Note: to access single data-structure elements (if really needed)
181           you can do as follow:
182
183            print "rsaKey modulus length: ", $rsaKey->{nLen}, "\n";
184
185   Querying objects
186           To query objects such exported keys, signatures or cryptlib
187           capabilities, you can use standard functions cryptQueryObject() and
188           cryptQueryCapability() as follow:
189
190            $cryptObjectInfo = CRYPT_OBJECT_INFO;
191            cryptQueryObject($encryptedKey, $encryptedKeyLength, $cryptObjectInfo);
192            if ( $cryptObjectInfo->{objectType} == CRYPT_OBJECT_ENCRYPTED_KEY ) {
193                warn "Import the key using conventional encryption!", "\n";
194            }
195
196            $cryptQueryInfo = CRYPT_QUERY_INFO;
197            cryptQueryCapability(CRYPT_ALGO_3DES, $cryptQueryInfo);
198            print "Algo-name: ", $cryptQueryInfo->{algoName}, "\n";
199

PREREQUIREMENT

201       ·   cryptlib v. 3.2.2 (or later)
202
203           CRYPTLIB Security Toolkit(c) by Peter Guttman
204

SEE ALSO

206       See Peter Guttman's cryptlib web site:
207
208       ·   http://www.cs.auckland.ac.nz/~pgut001/cryptlib/
209
210       and cryptlib official mailing-list:
211
212       ·   http://news.gmane.org/gmane.comp.encryption.cryptlib
213

BUGS AND REQUESTS

215       Please report any bugs or feature requests to perlcryptlib@gmail.com,
216       or through the web interface at http://rt.cpan.org/Public/.  I will be
217       notified, and then you'll automatically be notified of progress on your
218       bug as I make changes.
219

AUTHOR

221       Alvaro Livraghi, <perlcryptlib@gmail.com>
222
224       Copyright (C) 2006-2010 Alvaro Livraghi. All Rights Reserved.
225
226       This library is free software; you can redistribute it and/or modify it
227       under the same terms as Perl itself.
228
229
230
231perl v5.32.0                      2020-07-27                   PerlCryptLib(3)
Impressum