Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updates in the Configure Tomcat section

Smart ID Identity Manager offers support for HSM (Hardware Security Model) for several use cases:

  • encrypting and decrypting of secrets in BPMN processes using the Identity Manager SecretFieldStore
  • signing of Identity Manager configuration zip files
  • signing of S/MIME emails with the Identity Manager MailTask

This is a more secure solution for signing and encryption than PKCS#12 files, which are files in the file system, only protected by a PIN code.



  • Installed PRIME 3.7 or newer
  • Installed and running HSM with PKCS#11 library available on the Identity Manager server

Step-by-step instructions

Prepare and install HSM

titleInstall HSM
  1. Install the HSM PKCS#11 middleware on the PRIME server. The PKCS#11 DLL/.so file will later be referenced in the Identity Manager configuration.
  2. Install or create a signing and encryption certificate on the HSM as needed - depending on your use cases. Alias and PIN will be required in the configuration to access these certificates.

Configure Identity Manager

titleInstall the PKCS#11 bridge DLL

Identity Manager requires a native bridge DLL for the access to the HSM's PKCS#11 library, jpkcs11.dll/

  • The library is provided with your Identity Manager package or on request.
  • The library exists as 32bit and 64bit version. The bit version must correspond to the JRE used with the Identity Manager server.
  1. To be accessed, the library needs to be available in the PATH environment variable.
    1. Create a new folder for it and add the folder to the PATH

    2. Copy it to your C:\Windows\System32 folder (in case you are using the 64bit DLL on a 64bit system with 64bit JRE - the same with a pure 32bit solution).

titleConfigure Identity Manager with the engineSignEncrypt.xml

This section describes the engineSignEncrypt.xml valid from Identity Manager 3.12. For older versions, see Smart ID Identity Manager archive.

  1. Do the Identity Manager HSM configuration in the file engineSignEncrypt.xml in the WEB-INF/classes folder for each of the Identity Manager clients.

All Identity Manager clients that use the same database, must have the same engineSignEncrypt.xml configuration.

The following example is an extract showing four use cases configured for HSM (see also Sign and encrypt engine in Identity Manager for further use cases that can be configured in engineSignEncrypt.xml).

  • descriptor EncryptedFields is used for handling secrets with the Identity Manager SecretFieldStore
  • descriptor ConfigZipSigner is used for signing and verifying Identity Manager configuration zip files
  • descriptor ObjectHistorySigner is used for signing and verifying the Identity Manager Object History
  • descriptor SignEmailDescriptor is used for signing S/MIME mails with MailService tasks

All four use different HSM certificates, see below in the keys section. The example uses the Utimaco CryptoServer.

Code Block
titleExample extract of engineSignEncrypt.xml
<?xml version="1.0" encoding="UTF-8"?>
        <!-- other descriptors go here... ->
        <descriptor name="EncryptedFields" version="1">
            <type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="encryptedFieldsCertificateV1" asymCipher="RSA/ECB/OAEPWithSHA-384AndMGF1Padding"/>
        <descriptor name="ConfigZipSigner" version="1">
            <type algorithm="SHA-256" size="" result="" key="configZipSignerCertificateV1" />
        <descriptor name="ObjectHistorySigner" version="1">
            <type algorithm="SHA-256" size="" result="" key="objectHistorySignerCertificateV1" />
        <descriptor name="SignEmailDescriptor" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="signEmailCertificateV1"/>
        <!-- other keys go here... ->
        <key name="encryptedFieldsCertificateV1">
            <type name="HSM" locationValue="C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2" pin.encrypted="132435" alias="encryptedFieldsCertificateV1" slot="0" />
        <key name="configZipSignerCertificateV1">
            <type name="HSM" locationValue="C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2" pin.encrypted="132435" alias="configZipSignerCertificateV1" slot="0" />
        <key name="objectHistorySignerCertificateV1">
            <type name="HSM" locationValue="C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2" pin.encrypted="132435" alias="objectHistorySignerCertificateV1" slot="0" />
        <key name="signEmailCertificateV1">
            <type name="HSM" locationValue="C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2" pin.encrypted="132435" alias="signEmailCertificateV1" slot="0" />

Configuration attributeValueComments

Must be declared so the iD2 provider accepts it:

  • "None" is not supported as cipher mode but "ECB" is
  • In OAEP padding, all SHA-x hashes must be given with a dash in the name
<keys> section:

type name

HSMMust be "HSM" for keys stored in the HSM.
  • Either the absolute path of the HSM's P11 DLL (without extension) OR
  • the DLL's filename without extension

pinThe user PIN of the HSM.From and including PRIME 3.8, the pin.encrypted attribute is also supported, to scramble the PIN.
aliasThe alias of the respective key.In the HSM, the keypair and the certificate must be stored within the same label/alias.
slotOptional if your keys are in HSM slot 0. Note that the first slot is not always 0.

titleConfigure Tomcat

There is an issue with the iD2 security provider when you have two or more web clients, for example Identity Manager Operator and Identity Manager Admin, deployed in the same Tomcat that uses it to load a PKCS#11 keystore from the HSM.

If you do not handle this, errors like this can occur:

Code Block
Caused by: java.lang.IllegalArgumentException:
Parameter must be of type
but is

In addition, you may get a ClassNotFoundException for various BouncyCastle classes in crypto-related use-cases like softtoken requests, for example:

Code Block
Caused by: java.lang.ClassNotFoundException: org.bouncycastle.jce.provider.BouncyCastleProvider

  1. To avoid this, you have these options:
    1. Deploy each Identity Manager webapp on its own dedicated Tomcat instance.

    2. Remove all CMSDK JARs and all BouncyCastle JARs from all webapps'  webapps' tomcat\<webapp>\WEB-INF\lib folders folders and place them in Tomcat's lib folder tomcat\libs instead (this ensures those JARs are served from the Tomcat common classloader for all webapps).
        Also remove the following libs from the WEB-INF\lib folders and move them to tomcat\libs
        1. CMSDK JARs:
          • cmcommon*.jar
          • cmsdk-*.jar
          • common-*.jar
          • csp-*.jar
        2. BouncyCastle JARs:
          • bcmail-*.jar
          • bcpgp-*.jar
          • bcpkix-*.jar
          • bcprov-*.jar (including bcprov-ext-*.jar)

    Make sure you avoid leftover JAR versions when upgrading.

This article is valid for Smart ID 20.11 and later.

Related information