Figure 1 shows the layer model of this library. This library consists of the Object Oriented (OO) Wrapper API for PKCS#11 for the Java™ platform, the (non-Object Oriented) Wrapper API for PKCS#11 for the Java™ platform and the Native Module of the Wrapper, the green layers in the figure. The following paragraphs describe these parts. The lowest layer, the PKCS#11 Module of the Smart Card, is the PKCS#11 module that the smart card manufacturer supplies. This is normally a DLL or shared library. As the arrows show, the uppermost layer depends on the Wrapper for PKCS#11 for the Java™ platform, but not vice versa. This means you can use the Wrapper for PKCS#11 for the Java™ platform directly and build your application upon it without using the OO layer. This can be useful to create smaller applications, because you do not need most of the classes of the package iaik.pkcs.pkcs11 and no class from iaik.pkcs.pkcs11.objects and iaik.pkcs.pkcs11.parameters. The only classes from iaik.pkcs.pkcs11 you need are the exception classes.
This object-oriented API for the Java™ platform resides in the packages iaik.pkcs.pkcs11, iaik.pkcs.pkcs11.objects and iaik.pkcs.pkcs11.parameters. It provides a straight forward mapping of the PKCS#11 v2.20 standard to a set of classes and interfaces. The package iaik.pkcs.pkcs11.objects is a model of the object hierarchy presented in this PKCS#11 standard. The package iaik.pkcs.pkcs11.parameters provides classes for objects that act as parameters for mechanisms which require specific arguments. This layer solely builds upon the API for the Java™ platform for PKCS#11 as implemented by the Wrapper for PKCS#11 for the Java™ platform.
The non-Object Oriented Wrapper API for PKCS#11 for the Java™ platform is a set of Java™ classes and interfaces that reflects the PKCS#11 API. It is a straightforward realization of the data structures as defined in PKCS#11. For each structure in the pkcs11t.h header file of PKCS#11, there is a corresponding class in the package iaik.pkcs.pkcs11.wrapper. Notice, that this is not an object oriented approach at this level; it is just a straightforward mapping of the data structures to Java™. All adoptions to the PKCS#11 API, including wrapping into an object oriented approach, appear in the Object Oriented Wrapper API for PKCS#11 for the Java™ platform. The interface PKCS11 in the iaik.pkcs.pkcs11.wrapper package is the interface to a PKCS#11 module and provides access to the functions defined by PKCS#11. All names of classes, data structures and methods are the same as the corresponding PKCS#11 counterpart. The PKCS11Connector instantiates an object that implements this PKCS11 interface. The returned object gives access to the PKCS#11 module of the smart card; it is the Java™-Counterpart to the CK_C_GetFunctionList returned by the C_GetFunctionList function in PKCS#11. The Module class in the object-oriented layer provides the respective functionality. Have a look at the demo.pkcs.pkcs11 package in the demo directory for sample programs.
This native module of the wrapper is responsible for translation of the Java™ data structures, which the API for PKCS#11 for the Java™ platform part defines, to native PKCS#11 data structures and vice versa. This module of the system does not include any additional logic, it only provides a straightforward mapping from the API for PKCS#11 for the Java™ platform to the PKCS#11 Module of the Smart Card. This layer is necessary, because the JNI requires the native functions to have a special signature that is defined by JNI itself. PKCS#11 and JNI are not compatible as they are, and this is the reason why this layer is necessary at all. In compiled form, this module is a native DLL or shared library.
PKCS11_TEMP_DIR: sets the directory where the native .dll/.so/.jnilib will be extracted from the iaikPkcs11Wrapper.jar file. Default value is whatever ‘java.io.tmpdir‘ is set to.
PKCS11_DISABLE_BUFFER_PREALLOCATION: the wrapper tries to ‘guess’ the needed sizes for the buffers in the C_GetAttribute calls. This causes problems with some HSMs/smartcards. Default is ‘false‘
PKCS11_USE_240_ONLY: skips the initialization for pkcs#11 v3 and uses 2.40 implentation. Default is ‘false‘.
Full source of all components under an Apache-style license as well as precompiled binaries for Windows, Linux and Mac OS X.
JDK 1.3 or higher, GNU make for building the project using the included make files, MS VC++ 6.0 for building the DLLs for Windows, GCC for building the shared libraries for Linux and Solaris (or SUN C compiler).
Some of the included demo programs require the IAIK-JCE to compile and run. Simply place the iaik_jce_full.jar in the examples\lib directory.
The Stiftung SIC (Stiftung Secure Information and Communication Technologies, Inffeldgasse16a, A-8010 Graz, Austria / Europe), hereafter referred to as “Stiftung SIC”, provides the IAIK PKCS#11 Wrapper under an Apache-style license. In short, this means that you can use the IAIK PKCS#11 Wrapper for free for noncommercial and commercial developments provided you meet the conditions of the license text. The complete license text is as follows.
Copyright (c) 2002 IAIK, 2003 Stiftung SIC. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:
“This product includes software developed by Stiftung SIC.”
Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
4. The names “Stiftung SIC” and “IAIK of Graz University of Technology” must not be used to endorse or promote products derived from this software without prior written permission.
5. Products derived from this software may not be called “IAIK PKCS Wrapper”, nor may “IAIK” or “Stiftung SIC” appear in their name, without prior written permission of Stiftung SIC.
THIS SOFTWARE IS PROVIDED “AS IS” AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This is a list of changes between the different versions of the PKCS#11 wrapper.
"RSAPrivateKey.294, RSAPrivateKey.Allowed Mechanisms, RSAPrivateKey.295, X509PublicKeyCertificate.138,"When running some of the samples which try to generate keys, I get an iaik.pkcs.pkcs11.wrapper.PKCS11Exception: CKR_TEMPLATE_INCOMPLETE. What is wrong?
Some PKCS#11 modules restrict changing of certain attributes or setting of certain combinations (e.g. key value and key length). Please consult your module’s documentation for further details.
When running some of the samples which try to generate keys, I get an iaik.pkcs.pkcs11.wrapper.PKCS11Exception: CKR_ATTRIBUTE_VALUE_INVALID. What is wrong?
Some PKCS#11 modules restrict changing of certain attributes or setting of certain combinations (e.g. key value and key length). Please consult your module’s documentation for further details.
When running some of the samples which try to generate keys, I get an iaik.pkcs.pkcs11.wrapper.PKCS11Exception: CKR_ATTRIBUTE_TYPE_INVALID. What is wrong?
Some PKCS#11 modules do not support certain attributes or modifying certain attributes (e.g. object class or key type). As workaround you can try to set the class and key-type attributes as not present. This may look like this:
secretEnrcyptionKeyTemplate.getObjectClass().setPresent(false);
secretEnrcyptionKeyTemplate.getKeyType().setPresent(false);
maybe the driver accepts the key template if you try this.
Why do I always get an java.lang.UnsatisfiedLinkError: no pkcs11wrapper in java.library.path?
It seems that you do not have the pkcs11wrapper.dll (or libpkcs11wrapper.so under Unix) in you search path. You can provide such a path directly to the Java™ VM setting the java.library.path system property like:
java -Djava.library.path==../bin/<windows|unix>/<platform>/release;.
-cp classes;../bin/iaikPkcs11Wrapper.jar demo.pkcs.pkcs11.GetInfo cryptoki.dll
where ../bin/ <windows|unix >/ /release is the path where the pkcs11wrapper.dll (or libpkcs11wrapper.so under unix) file is. You can also place the file in the folder for binary files of you Java™ Runtime Environment; e.g. the jre/bin folder. Alternatively, you can also place the file pkcs11wrapper.dll in the system directory of Windows. On Unix systems you can place the libpkcs11wrapper.so in a lib directory of the system.
How can I export certificates from my smart card?
Extract the DER encoding (value attribute) of the certificate with
certificate.getValue().getByteArrayValue();
and write this bytes to a file like this:
FileOutputStream certificateDumpStream = new FileOutputStream(certificateDumpFilename);
certificateDumpStream.write(value);
certificateDumpStream.flush();
certificateDumpStream.close();
How can I import my private key and certificate into the smart card?
There is a demo included to do that. It is called UploadPrivateKey.
How can I export certificates from my smart card?
Extract the DER encoding (value attribute) of the certificate with
certificate.getValue().getByteArrayValue();
and write this bytes to a file like this:
FileOutputStream certificateDumpStream = new FileOutputStream(certificateDumpFilename);
certificateDumpStream.write(value);
certificateDumpStream.flush();
certificateDumpStream.close();
How can I import my private key and certificate into the smart card?
There is a demo included to do that. It is called UploadPrivateKey.
When running some of the samples which try to generate keys, I get an iaik.pkcs.pkcs11.wrapper.PKCS11Exception: CKR_TEMPLATE_INCOMPLETE. What is wrong?
Some PKCS#11 modules restrict changing of certain attributes or setting of certain combinations (e.g. key value and key length). Please consult your module’s documentation for further details.
When running some of the samples which try to generate keys, I get an iaik.pkcs.pkcs11.wrapper.PKCS11Exception: CKR_ATTRIBUTE_VALUE_INVALID. What is wrong?
Some PKCS#11 modules restrict changing of certain attributes or setting of certain combinations (e.g. key value and key length). Please consult your module’s documentation for further details.
When running some of the samples which try to generate keys, I get an iaik.pkcs.pkcs11.wrapper.PKCS11Exception: CKR_ATTRIBUTE_TYPE_INVALID. What is wrong?
Some PKCS#11 modules do not support certain attributes or modifying certain attributes (e.g. object class or key type). As workaround you can try to set the class and key-type attributes as not present. This may look like this:
secretEnrcyptionKeyTemplate.getObjectClass().setPresent(false);
secretEnrcyptionKeyTemplate.getKeyType().setPresent(false);
maybe the driver accepts the key template if you try this.
Why do I always get an java.lang.UnsatisfiedLinkError: no pkcs11wrapper in java.library.path?
It seems that you do not have the pkcs11wrapper.dll (or libpkcs11wrapper.so under Unix) in you search path. You can provide such a path directly to the Java™ VM setting the java.library.path system property like:
java -Djava.library.path==../bin/<windows|unix>/<platform>/release;.
-cp classes;../bin/iaikPkcs11Wrapper.jar demo.pkcs.pkcs11.GetInfo cryptoki.dll
where ../bin/ <windows|unix >/ /release is the path where the pkcs11wrapper.dll (or libpkcs11wrapper.so under unix) file is. You can also place the file in the folder for binary files of you Java™ Runtime Environment; e.g. the jre/bin folder. Alternatively, you can also place the file pkcs11wrapper.dll in the system directory of Windows. On Unix systems you can place the libpkcs11wrapper.so in a lib directory of the system.