Package com.pdftools.crypto.providers.pkcs11

Class Module

java.lang.Object

com.pdftools.internal.NativeBase

com.pdftools.internal.NativeObject

com.pdftools.crypto.providers.pkcs11.Module

All Implemented Interfaces:

java.lang.AutoCloseable

public class Module
extends NativeObject
implements java.lang.AutoCloseable

The PKCS#11 driver module

The PKCS#11 driver module (middleware) manages the cryptographic devices of a particular type.

Note: The PKCS#11 interface requires special handling of the driver modules:

• In each application, the module can only be loaded once, so there can only be a single Module instance for each driver. Since this object is fully thread-safe, it might be used by multiple threads though.
• The object must be closed before the application terminates.

Method Summary

Modifier and Type	Method	Description
void	close()	Close all open sessions and unload the module
DeviceList	getDevices()	The list of devices managed by this module (Getter)
boolean	getEnableFullParallelization()	Enable full parallelization (Getter)
static Module	load(java.lang.String library)	Load a PKCS#11 driver module
void	setEnableFullParallelization(boolean value)	Enable full parallelization (Setter)

Methods inherited from class com.pdftools.internal.NativeObject

equals, hashCode

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

load

public static Module load(java.lang.String library)
                   throws NotFoundException,
                          ExistsException

Load a PKCS#11 driver module

Parameters:

library -

The name or path to the driver module (middleware). This can be found in the documentation of your cryptographic device.

Examples:

• For Securosys SA Primus HSM or CloudsHSM use primusP11.dll on Windows and libprimusP11.so on Linux.
• For Google Cloud HSM (Cloud KMS) use libkmsp11.so and Session.createSignatureFromKeyLabel(java.lang.String, com.pdftools.sys.Stream)
• For SafeNet Luna HSM use cryptoki.dll on Windows or libCryptoki2_64.so on Linux/UNIX.
• The CardOS API from Atos (Siemens) uses siecap11.dll
• The IBM 4758 cryptographic coprocessor uses cryptoki.dll
• Devices from Aladdin Ltd. use etpkcs11.dll

Returns:

Throws:

NotFoundException - The library cannot be found.

ExistsException - The module has been loaded already by this application.

java.lang.IllegalArgumentException - The given library is not a PKCS#11 driver module.

java.lang.IllegalArgumentException - if library is null

getEnableFullParallelization

public boolean getEnableFullParallelization()

Enable full parallelization (Getter)

The PKCS#11 standard specifies that "an application can specify that it will be accessing the library concurrently from multiple threads, and the library must [...] ensure proper thread-safe behavior." However, some PKCS#11 modules (middleware) implementations are not thread-safe. For this reason, the SDK synchronizes all access to the module. If the middleware is thread-safe, full parallel usage of the cryptographic device can be enabled by setting this property to true and thereby improving the performance.

Default: false

setEnableFullParallelization

public void setEnableFullParallelization(boolean value)

Enable full parallelization (Setter)

The PKCS#11 standard specifies that "an application can specify that it will be accessing the library concurrently from multiple threads, and the library must [...] ensure proper thread-safe behavior." However, some PKCS#11 modules (middleware) implementations are not thread-safe. For this reason, the SDK synchronizes all access to the module. If the middleware is thread-safe, full parallel usage of the cryptographic device can be enabled by setting this property to true and thereby improving the performance.

Default: false

getDevices

public DeviceList getDevices()

The list of devices managed by this module (Getter)

Most often there is only a single device, so the method DeviceList.getSingle() can be used.

close

public void close()
           throws PdfToolsException,
                  java.io.IOException

Close all open sessions and unload the module

After unloading, the module cannot be loaded again in the same process. Proper unloading is crucial. Otherwise, the application might crash and/or the HSM, USB token, or smart card might not be unlocked.

When using the C interface, this method must not be called from the context of the destructor of a global or static object, nor an atexit() handler, nor the DllMain() entry point.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

PdfToolsException - only explicitly stated in a superclass

java.io.IOException