1PerlCryptLib(3) User Contributed Perl Documentation PerlCryptLib(3)
2
6 PerlCryptLib - Perl interface to Peter Guttman's cryptlib API
7
9 PerlCryptLib is an interface module to access cryptlib API.
10 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 For more information about cryptlib features and state-of-the-
18 art, please visit its official web-site at:
19 · http://www.cs.auckland.ac.nz/~pgut001/cryptlib
21
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 perl Makefile.PL
35 make
36 make test TEST_VERBOSE=1 # or, simply, the canonical make test
37 sudo make install
38
40 use PerlCryptLib qw(:all);
41 my $envelope = CRYPT_ENVELOPE;
43 if ( cryptInit() == CRYPT_OK ) {
44 if ( cryptCreateEnvelope($envelope,
45 CRYPT_UNUSED,
46 CRYPT_FORMAT_CRYPTLIB) == CRYPT_OK ) {
47 # set some attributes with cryptSetAttribute() or cryptSetAttributeString()
49 # set some other crypto-stuff
50 # push or pop data with cryptPushData() and cryptPopData()
51 cryptDestroyEnvelope($envelope);
53 }
54 cryptEnd();
55 }
56 Notes
58 cryptUIDisplayCert() and cryptUIGenerateKey() cryptlib functions are
59 not implemented.
60
62 PerlCryptLib doesn't export anything by default. You can choose to
63 explicitly import specifics exported tags:
64 :constants
66 all of the CRYPT_* cryptlib constants
67 :functions
69 all of the crypt* cryptlib functions
70 :all
72 all of the cryptlib constants and functions
73 For example, to import only functions name:
75 use PerlCryptLib ':functions';
77 Alternatively, you can import such functions or constants by specifying
79 each of them in the 'use' statement:
80 use PerlCryptLib qw(cryptInit cryptEnd CRYPT_OK);
82
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 So, using
92 my $envelope = CRYPT_ENVELOPE;
94 my $context = CRYPT_CONTEXT;
95 my $certificate = CRYPT_CERTIFICATE;
96 is the same as using
98 my $envelope = 0;
100 my $context = 0;
101 my $certificate = 0;
102 but is much more comprehensive.
104 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 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 my $maxLength = 1024;
115 my $key = ' ' x $maxLength;
116 cryptExportKey($key, $maxLength, $keyLength, $context, $cert);
117 NULL values
119 NULL values can be handled in different ways:
120 # 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 However, when used in pass-by-reference calls, MUST be declared as
129 0x0 scalar values:
130 $null = 0x0;
132 cryptExportKey($null, 0, $maxLength, $context, $cert);
133 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 cryptSetComponent($componentInfo, $element, $source, $length)
140 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 cryptFinalizeComponents($componentInfo, $blob, $size)
147 Here is an example "translated" in PerlCryptLib:
149 ##### Create objects
151 $cryptContext = CRYPT_CONTEXT;
152 $rsaKey = CRYPT_PKCINFO_RSA;
153 ##### 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 ##### 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 ##### 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 ##### Destroy objects
177 cryptDestroyComponents($rsaKey);
178 cryptDestroyContext($cryptContext);
179 Note: to access single data-structure elements (if really needed)
181 you can do as follow:
182 print "rsaKey modulus length: ", $rsaKey->{nLen}, "\n";
184 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 $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 $cryptQueryInfo = CRYPT_QUERY_INFO;
197 cryptQueryCapability(CRYPT_ALGO_3DES, $cryptQueryInfo);
198 print "Algo-name: ", $cryptQueryInfo->{algoName}, "\n";
199
201 · cryptlib v. 3.2.2 (or later)
202 CRYPTLIB Security Toolkit(c) by Peter Guttman
204
206 See Peter Guttman's cryptlib web site:
207 · http://www.cs.auckland.ac.nz/~pgut001/cryptlib/
209 and cryptlib official mailing-list:
211 · http://news.gmane.org/gmane.comp.encryption.cryptlib
213
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
221 Alvaro Livraghi, <perlcryptlib@gmail.com>
222
224 Copyright (C) 2006-2010 Alvaro Livraghi. All Rights Reserved.
225 This library is free software; you can redistribute it and/or modify it
227 under the same terms as Perl itself.
228perl v5.32.0 2020-07-27 PerlCryptLib(3)