Nexus' software components have new names:

Nexus PRIME -> Smart ID Identity Manager
Nexus Certificate Manager -> Smart ID Certificate Manager
Nexus Hybrid Access Gateway -> Smart ID Digital Access component
Nexus Personal -> Smart ID clients

Go to Nexus homepage for overviews of Nexus' solutions, customer cases, news and more.


Skip to end of metadata
Go to start of metadata

Smart ID Identity Manager (PRIME) 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.

Expand/Collapse All

Prerequisites

 Prerequisites
  • 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

 Install 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

 Install the PKCS#11 bridge DLL

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

  • 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

      OR
    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).
 Configure Identity Manager with the engineSignEncrypt.xml

This section describes the engineSignEncrypt.xml valid from Identity Manager 3.12. For older versions, see PRIME 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.

Example extract of engineSignEncrypt.xml
<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>    
    <descriptors>
        <!-- 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>
        <descriptor name="ConfigZipSigner" version="1">
            <type algorithm="SHA-256" size="" result="" key="configZipSignerCertificateV1" />
        </descriptor>
        <descriptor name="ObjectHistorySigner" version="1">
            <type algorithm="SHA-256" size="" result="" key="objectHistorySignerCertificateV1" />
        </descriptor>
        <descriptor name="SignEmailDescriptor" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="signEmailCertificateV1"/>
        </descriptor>
	</descriptors>
    <keys>
        <!-- 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>
        <key name="configZipSignerCertificateV1">
            <type name="HSM" locationValue="C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2" pin.encrypted="132435" alias="configZipSignerCertificateV1" slot="0" />
        </key>
        <key name="objectHistorySignerCertificateV1">
            <type name="HSM" locationValue="C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2" pin.encrypted="132435" alias="objectHistorySignerCertificateV1" slot="0" />
        </key>
        <key name="signEmailCertificateV1">
            <type name="HSM" locationValue="C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2" pin.encrypted="132435" alias="signEmailCertificateV1" slot="0" />
        </key>
	</keys>
</engineSignEncrypt>
Configuration attributeValueComments
asymCipherRSA/ECB/OAEPWithSHA-384AndMGF1Padding

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.
locationValue
  • 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.
 Configure Tomcat

There is an issue with the iD2 security provider when you have two or more web clients, for example Identity Manager operator UI (PRIME Explorer) and Identity Manager Admin (PRIME Designer), 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:

Caused by: java.lang.IllegalArgumentException:
Parameter must be of type
com.id2tech.security.store.Pkcs11LoadStoreParameters
but is
com.id2tech.security.store.Pkcs11LoadStoreParameters
  1. To avoid this, you have these options:
    1. Deploy each Identity Manager webapp on its own dedicated Tomcat instance.

      OR
    2. Remove all CMSDK JARs from all webapps' WEB-INF\lib folders and place them in Tomcat's lib folder instead (this ensures those JARs are served from the Tomcat common classloader for all webapps).
    3. Also remove the following libs from the WEB-INF\lib folders and move them to tomcat\libs:
      1. cmcommon*.jar
      2. cmsdk-*.jar
      3. common-*.jar
      4. csp-*.jar