Configure HSM in Identity Manager

This article is valid for Smart ID 21.10 and later.

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.

The set of JAR files in Certificate Manager (CM) 8.4 has changed. This version of CM is used with Identity Manager in Smart ID 21.10, see this note for the updates, see also section "Configure Tomcat" below.

Different set of JAR files for Identity Manager in Smart ID 21.10 and later

Identity Manager in Smart ID 20.10 is based on Certificate Manager SDK 8.4, which has a different set of JAR files compared to previous versions:

cmcommon-x.y.z.jar => renamed to cm-common-x.y.z.jar
cmsdk-x.y.z.jar => renamed to cm-sdk-x.y.z.jar
csp-x.y.z.jar => removed, all code moved to common-x.y.z.jar
common-x.y.z.jar => now includes csp code as well and carries JCE provider signature

Prerequisites

Installed Smart ID 21.10 or later
Installed and running HSM with PKCS#11 library available on the Identity Manager server

Step-by-step instructions

Prepare and install HSM

Install the HSM PKCS#11 middleware on the Identity Manager server. The PKCS#11 DLL/.so file will later be referenced in the Identity Manager configuration.
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.

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.

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

CODE

<?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 attribute	Value	Comments
`asymCipher`	RSA/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`	HSM	Must 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
`pin`	The user PIN of the HSM.	From and including PRIME 3.8, the `pin.encrypted` attribute is also supported, to scramble the PIN.
`alias`	The alias of the respective key.	In the HSM, the keypair and the certificate must be stored within the same label/alias.
`slot`	Optional 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 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:

Caused by: java.lang.IllegalArgumentException:
Parameter must be of type
com.id2tech.security.store.Pkcs11LoadStoreParameters
but is
com.id2tech.security.store.Pkcs11LoadStoreParameters

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

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

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 and all BouncyCastle JARs from all webapps' tomcat\<webapp>\WEB-INF\lib folders and place them in tomcat\libs instead (this ensures those JARs are served from the Tomcat common classloader for all webapps).
  1. CMSDK JARs:
    - cmcommon*.jar
    - cmsdk-*.jar
    - common-*.jar
  2. BouncyCastle JARs:
    - bcmail-*.jar
    - bcpgp-*.jar
    - bcpkix-*.jar
    - bcprov-*.jar (including bcprov-ext-*.jar)

Additional information

Useful links