PKCS#11 Wrapper

PKCS#11 Wrapper

This is a library for the Java™ platform which makes PKCS#11 (also known as Cryptoki) modules accessible from within Java™. A PKCS#11 module is a software library with a defined API which allows access to cryptographic hardware. It usually comes with hardware security modules (HSM), smart cards and crypto tokens (e.g. USB tokens). Thus, the PKCS#11 Wrapper provides Java™ software access to almost any crypto hardware. For example, a Java™ application can use it to integrate a HSM or a smart card to create digital signatures, to decrypt data or to unwrap keys. We provide this library with an apache-style license.

Main Features

Please notice that this library does not come with a JCA or JCE provider implementation. For this purpose there is a different product:

IAIK PKCS#11 Provider

Download

After registering, you can Download and use the PKCS#11 Wrapper for free!

Download

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.

pkcs11_layer_model

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

System Properties

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

Includes:

Full source of all components under an Apache-style license as well as precompiled binaries for Windows, Linux and Mac OS X.

Requirements:

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.

API Documentation

 

 

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.

IAIK PKCS#11 Wrapper License

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.

Changes introduced in 1.6.10

  • Added a version check to ensure that the Java part version e.g. 1.6.10 matches the version the native lib was compiled for. Can be disabled with -DPKCS11_DISABLE_VERSION_CHECK=true
  • Added support for HSMs that generate the IV and write it back into CK_GCM_PARAMS in C_WrapKey
  • Added CKUserType for login and loginUser in Session (uses long instead of boolean)
  • Deprecated: UserType, login and loginUser that use boolean UserType

Changes introduced in 1.6.9

  • Updated mechanismCodeToString() in Functions (SHA3*, SHA3*HMAC)
  • Updated string constants for the mechanism names in PKCS11Constants (SHA3*, SHA3*HMAC)
  • Updated MessageGenerationFunctionTypes (SHA3*) in RSAPkcsParameters

Changes introduced in 1.6.8

  • Fix: Fixed segmentation fault in C_GetAttributeValue when wrap/unwrap templates are used
  • Fix: Fixed NullPointerException in Attribute.java
  • Fix: Fixed stateKnown not set in Attribute.java
  • Added more arguments and return value logging

Changes introduced in 1.6.7

  • Fix: Added -Wl,–add-stdcall-alias for 32bit windows (fixes UnsatisfiedLinkError on 32bit Windows)
  • Fix: Fixed NULL check in printCkParameters

Changes introduced in 1.6.6

  • customize directory for .so/.dll/.dylib when extracted from pkcs11wrapper.jar file
  • force pkcs#11 2.40 via environment variable (disable pkcs#11 v3 support)

Changes introduced in 1.6.5

  • Performance improvements
  • PKCS#11 v3.0 compatibillity, backward compatible to pkcs#11 2.x
  • Disable buffer preallocation for C_GetAttributeValue

Changes introduced in 1.6.1

  • Fixed bugs in C_Decrypt, C_DecryptUpdate, C_DecryptFinal

Changes introduced in 1.6

  • Fixed bug in C_GetAttributeValue
  • Native binary for Solaris Sparkv9 not included anymore
  • Updated CK?_ Constants to latest 2.40 version.

Changes introduced in 1.5

  • Support for AES GCM and CCM has been added.
  • Changes in Buffer handling when using calling PKCS11 functions to improve performance.
  • This is the last version with a Solaris Sparkv9 binary included in .jar file

Changes introduced in 1.4

  • The binaries of the native PKCS#11 wrapper for supported operating systems are now included in the PCKS#11 wrapper jar file. If no wrapper library
    can be found in the search path or library path or has been passed as parameter during module instantiation,
    the wrapper will automatically copy the appropriate library for the current system to your local temporary directory
    and load it from there. If the native library still can’t be found, the used system or architecture may not be supported.
  • Directory structure of the native libraries has been modified a bit (unified).
  • Fix a minor bug with null objects as attribute array.

Changes introduced in 1.3

  • Labels and PINs are now saved and interpreted using UTF8 encoding per default as given in the PKCS#11 specification. Convert
    labels or PINs that contain special characters, e.g. by using the provided demos in the util package of the examples. Use slot.setUtf8Encoding(false);
    to continue using the old character encoding for the given slot.
  • Attribute arrays can now be filled with any iaik.pkcs.pkcs11.object.Object. Therefore wrap/unwrap templates
    are much easier to use for example.
  • The Attribute API now offers an alternative way of selecting attributes. The new methods
    setValue(java.lang.Object) as well as getAttribute(…), putAttribute(…), and
    removeAttribute(…) allow for attribute management at runtime. It is no more necessary to know each
    and every needed attribute at compile time.
  • The path to the native library of the IAIK PKCS#11 Wrapper can now be specified as relative path.

Changes introduced in 1.2.18

  • Fix: check attribute length in GetAttributeValue to prevent OutOfMemoryException if PKCS#11 module doesn’t
    return correct return code although attribute length is -1
  • Fix: adapt code to handle null objects under AIX if allocating memory of size 0
  • Added PKCS11 v2.20 object types WTLSCertificate, UserInterface and Mechanism
  • Added X9.42 DH primitives
  • Added EC primitives
  • Refactored demos to be more readable

Changes introduced in 1.2.17

  • Added 64-bit version for Windows.
  • Added new parameter classes for CBC key derivation, iaik.pkcs.pkcs11.parameters.DesCbcEncryptDataParameters,
    iaik.pkcs.pkcs11.parameters.AesCbcEncryptDataParameters, iaik.pkcs.pkcs11.parameters.CbcEncryptDataParameters,
    iaik.pkcs.pkcs11.wrapper.CK_DES_CBC_ENCRYPT_DATA_PARAMS and iaik.pkcs.pkcs11.wrapper.CK_AES_CBC_ENCRYPT_DATA_PARAMS.
  • Added classes for in PKCS#11 v2.20 newly invented attributes, eg. CKA_WRAP_TEMPLATE.
  • Fixed incorrect time handling for clock on token, time was in UTC although specified as local time.
  • Invented new method iaik.pkcs.pkcs11.objects.Object.getAttributeValues, which reads the attributes
    in a similar way as iaik.pkcs.pkcs11.objects.Object.getAttributeValue, but a complete array at once.
    This can lead to performance improvements.
  • Added new method iaik.pkcs.pkcs11.Module.getInstance(String pkcs11ModuleName, String pkcs11WrapperPath),
    which enables to specify the absolute path to the IAIK PKCS#11 Wrapper library when instantiating the PKCS#11 module.

Changes introduced in 1.2.16

  • added a Mac OS X version. special thanks to Marc Nelson from
    Nelson Brothers Racing.
  • fixed a bug in the equals method of the Attribute class which may cause
    a NullPointerException for objects with sensitive attributes.
  • improved error handling in native code in case the system runs out
    of memrory, i.e. if malloc returns NULL. the wrapper now tries to throw
    an java.lang.OutOfMemoryError.
  • improved handling or allocated structures to avoid memory leaks with
    complex mechanism parameters.

Changes introduced in 1.2.15

  • added 64-bit versions for Linux (x86-64) and Solaris (SPARC v9)
  • compiled native library for Solaris with SUN C compiler.
    the wrapper will now run on a Solaris system without libgcc.
  • set object class attribute in constructor of DomainParameters object.

Changes introduced in 1.2.14

  • added constants for mask generation functions based on SHA-256/384/512

Changes introduced in 1.2.13

  • fixed an issue in the native part of Linux and Solaris.
    this issue regarding handling or error messages may crash or halt
    th Java VM if the application tries to load a module which does
    not exist. it was cause by calling free() on the result of
    dlerror().
  • removed GNU Makefiles, use the ANT scripts instead.
  • adapted applet demo to use extension installation feature of
    Java plugin.
  • added constants from version 2.20 of PKCS#11.
  • added blowfish and twofish key classes

Changes introduced in 1.2.12

  • fixed toString() method of the GenericTemplate object class
    to provide a better readable output.
  • removed some unused local variables in classes of package
    iaik.pkcs.pkcs11.objects.
  • extended JavaDoc in Module class
  • fixed toString() of Version class to display all version
    numbers as positiv integers
  • fixed a bug in the ReadDataObject demo
  • added demo for creating self-signed certificate

Changes introduced in 1.2.11

  • fixed a bug in a date conversion used for start date and end
    date attributes of keys.

Changes introduced in 1.2.10

  • modified some object classes to be more robust against
    missing attributes

Changes introduced in 1.2.9

  • changed toString() methods of certain objects to be more
    robust agains missing attributes
  • some minor improvments in native code

Changes introduced in 1.2.8

  • fixed bug in C_Sign which was introduced in version 1.2.8
    workaround

Changes introduced in 1.2.7

  • added workaround in native part to avoid bug in sign
    operation of certain PKCS#11 modules (e.g. iButton)
  • more sample code in the usage documentation

Changes introduced in 1.2.6

  • fixed method getMessage() in PKCS11Exception to provide error
    name reliably even in multithreaded applications
  • small improvement in native implementation of C_GetSlotList
    which also avoids a bug in iKey 2032 drivers to occur

Changes introduced in 1.2.5

  • added methods to MechanismInfo for logic combinations (and,
    or, not)
  • fixed bug in native part to handle attributes correctly that
    are new in PKCS#11 v2.11
  • changed license to a more liberal Apache style license
  • moved some simple helper classes for demos from demo/test to
    demo/src/demo/pkcs/pkcs11.

Changes introduced in 1.2.4

  • fixed method supports(MechanismInfo) in MechanismInfo

Changes introduced in 1.2.3

  • additional constructor in iaik.pkcs.pkcs11.MechanismInfo and
    made constructors public

Changes introduced in 1.2.2

  • implemented equals and hashCode in iaik.pkcs.pkcs11.Module
    and in iaik.pkcs.pkcs11.wrapper.PKCS11Implementation

Changes introduced in 1.2.1

  • a littel performance improvement in the native part
  • included an applet demo

Changes introduced in 1.2

  • all PKCS#11 objects and parameters are now deep
    cloneable
  • improved attribute handling of objects
  • fixed a bug in the X942DHParams class
  • improved demo samples
  • renamed isLocal() to getLocal() in Key class to be
    consistent
  • fixed some typos

Changes introduced in 1.1

  • support for PKCS#11 v2.11 including new key and parameters
    classes
  • improved demo samples
  • fixed a bug in the native part for CK_SSL3_KEY_MAT_OUT
    conversion

Changes introduced in 1.0

  • fixed problems and bugs in some parameter classes for certain
    mechanisms.
  • added some more demos: decrypting PKCS#7 enveloped data,
    signing a certificate request, signing a CRL and signing an OCSP
    request.

Changes introduced in 1.0Beta1

  • improved the wrapper to pass back data in the parameters of
    SSL and other mechanisms.
  • added some more demos. among others, one that shows how to
    sign data using a PKCS#7 signed data object and another that
    signs a certificate.
  • added a generic search template to enable more advanced
    search operations.
  • put a simple example in the Usage document.
  • reorganized native part into platform dependent and portable
    code. eases porting to new platforms.
  • improved synchronization in native part.
  • added methods to Functions class the check the type of a
    mechanism.
  • implemented hashCode() and equals() method of most
    classes.

Changes introduced in 1.0Alpha8

  • introduced simple default implementations for InitializeArgs
    and MutexHandler.
  • improved some demos.
  • fixed a mojor bug in the native part which may cause the
    program to hang upon closing a session.
  • fixed some cosmetic bugs in code and docu.

Changes introduced in 1.0Alpha7

  • introduced this changes list.
  • fixed a mojor bug in the native part of
    C_GenerateKeyPair.
  • fixed some cosmetic bugs in code and docu.

Changes introduced in 1.0Alpha6

  • rework project structure to make structure clearer and more
    intuitive.
  • improved initialization arguments handling.
  • added support for parameter objects that return values from
    certain mechanisms; e.g. some special SSL mechanisms for
    generating key material.

Changes introduced in 1.0Alpha5

  • introduced parameters package to make handling of parameters
    for certain mechanisms easier.
  • added solaris support out-of-the box and included precompiled
    shard library.

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.

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.

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.

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.

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();

There is a demo included to do that. It is called UploadPrivateKey.

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();

There is a demo included to do that. It is called UploadPrivateKey.

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.

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.

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.

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.

Any questions?

Don‘t hestitate to ask us about our products.

Contact us