Keys and certificates for the sign and encrypt engine can be stored in a Hardware Security Model (HSM) for several use cases. 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.

...

For more information, see Configure Tomcat below.

Prerequisites

• Installed Smart ID 24.R1 IDM 5.0.0 or later

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

...

1. 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.

2. Install or create a signing and encryption certificate on the HSM as needed - depending , this depends on your use cases. Alias, slot, and PIN will be required in the configuration to access these the certificates.

Configure Identity Manager

...

Tomcat deployment on Windows

To be accessed, the The library must be available in the PATH environment variable.

• Create a new folder for it and add the folder to the PATH or copy it to your C:\Windows\System32 folder.

Docker deployment

For Docker docker deployment, libjpkcs11 needs to must be placed onto the docker host and then mounted into the respective containers.

Add a volume mount to docker/compose/identitymanager/admin/docker-compose.ymland docker/compose/identitymanager/operator/docker-compose.yml. In the example below, libjpkcs11_x64-3.6.3.1.so (version number may vary) is placed into the docker/compose/identitymanager/config/ folder, which is then mounted into the container’s Tomcat folder for native libs as libjpkcs11.so.

    volumes:
      - "../config/libjpkcs11_x64-3.6.3.1.so:/usr/local/tomcat/native-jni-lib/libjpkcs11.so:ro"

Configure engineSignEncryptConfig.xml/signencrypt.xml

Do Perform the Identity Manager HSM configuration in the file engineSignEncryptConfig.xml in the WEB-INF/classes folder for each of the relevant Identity Manager clients. In case of Docker docker deployment, edit the file docker/compose/identitymanager/config/signencrypt.xml needs to be edited instead.

Example: Four use cases configured for HSM

The following example is an extract showing four use cases configured for HSM:

• 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 Mail service tasks

All four use different HSM certificates, see below in the keys section. The example uses the Utimaco CryptoServer with Identity Manager running on Windows.

Example extract of config 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" key="configZipSignerCertificateV1" />
        </descriptor>
        <descriptor name="ObjectHistorySigner" version="1">
            <type algorithm="SHA-256" key="objectHistorySignerCertificateV1" />
        </descriptor>
        <descriptor name="SignEmailDescriptor" version="1">
            <type algorithm="SHA256withRSA" 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>

...

...

...

For more information, see Sign and encrypt engine in Identity Manager for further use cases that can be configured.

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.

...

In addition, you may get a ClassNotFoundException for various BouncyCastle classes in crypto-related use - cases like soft token requests, for example:
Caused by: java.lang.ClassNotFoundException: org.bouncycastle.jce.provider.BouncyCastleProvider

To avoid this, you can deploy each Identity Manager web app on its own dedicated Tomcat instance (Docker docker deployments always work like this) or remove all CMSDK JARs and all BouncyCastle JARs from all webapps' tomcat\<webapp>\WEB-INF\lib folders and place them in tomcat\libs libs instead. This ensures that the JARs are served from the Tomcat common classloader for all web apps.

CMSDK JARs:

• cmcommon*.jar

• cmsdk-*.jar

• common-*.jar

BouncyCastle JARs:

• bcmail-*.jar

• bcpgp-*.jar

• bcpkix-*.jar

• bcprov-*.jar (including bcprov-ext-*.jar)

Additional information