Package com.pdftools.crypto.providers.pkcs11

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