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:
AutoCloseable
public class Module extends NativeObject implements 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 Details

    • load

      public static Module load(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.
      IllegalArgumentException - The given library is not a PKCS#11 driver module.
      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, 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 AutoCloseable
      Throws:
      PdfToolsException - only explicitly stated in a superclass
      IOException