PKCS#11 Wrapper

Please notice that this library does not come with a JCA or JCE provider implementation. For this purpose there is a different product – the IAIK PKCS#11 Provider .

The Layer Model of the System

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.

The Object-Oriented API for PKCS#11 for the Java™ platform

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.11 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 API 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.

The Native Module of the Wrapper

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.
Compatibility
This implementation should be compatible to all Java™2 (and also JDK 1.1.8) and JNI 1.1. It relies on the PKCS#11 version 2.11 but it should also work with any 2.x driver. The native code is written in C and can be compiled on different Windows and Unix platforms. The reference platform is Windows2000 and Sun JDK 1.3. The compiler used for development under Windows is Microsoft Visual C++ 2008. For Unix platforms, we used the GCC 3.2 compiler and the GNU make utility. For Solaris, we used SUN JDK 1.4.2 on Solaris 9 and the SUN C compiler 5.7.

Performance

Tests showed that the calls through the Java™ Native Interface (JNI) and the parameter conversions do not take much time. We did a short test on an AMD Athlon 1.4 GHz using SUN JDK 1.3.1_04. It showed that an update call to a digest through the wrapper, providing a 1024 bytes block of data, takes not even 0.01 milliseconds on average. This time includes the Java™ call in the PKCS#11 Wrapper, in the native code of the wrapper (including conversion of parameters from Java™ to PKCS#11 structures) and down to the call to the PKCS#11 module. This excludes the time for the calculation time in the PKCS#11 module. We tested this by using a dummy PKCS#11 module that does nothing in its digest functions. The core code from the testing routine looks like this:

We took a time difference of about 90 milliseconds between t1 and t0, which results in 0.009 milliseconds per call. This value is roughly the same for a data buffer of 1024 bytes and 4096 bytes.

Sending a file with 4.372.615 bytes to the PKCS#11 module took about 70 milliseconds sending the data in 1024 byte blocks; this results in 4271 calls to the update method. Increasing the block size to 4096 bytes improves the performance significantly. The test with the file includes reading the data directly from file and feeding it to the PKCS#11 Wrapper on the fly. However, we read the complete file once, before we did the test run, what causes the operating system the have the file cached in memory for the real test run. Then sending the same amount of data takes 30 milliseconds; this results in 1068 calls to the update method.

During the performance tests it showed out that it is even worth to calculate relatively simple cryptographic operations likes hashes through a PKCS#11 module. For example, we compared a pure Java™ implementation and C implementation of the SHA-1 hashing algorithm. Both use very similar code; i.e. the compression function is nearly a copy and paste from Java™ to C. However, the C implementation, accessed through the PKCS#11 Wrapper, is about double as fast as the Java™ implementation (using the same environment as before).
These tests unquestionably prove that this library is suitable for high performance server applications.

Includes:

Full source of all components under an Apache-style license, precompiled DLLs for Windows, Linux, Solaris and WinCE 3.0 (ARM, MIPS, SH3, SH4, x86, x86em)
Requirements:

JDK 1.2 or higher (jdk 1.1.8 support possible), 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 compileand run. Simply place the iaik_jce_full.jar in the demo\lib directory.