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.
Create a new folder for it and add the folder to the PATH
OR
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 SecretFieldStoredescriptor
ConfigZipSigner
is used for signing and verifying Identity Manager configuration zip filesdescriptor
ObjectHistorySigner
is used for signing and verifying the Identity Manager Object Historydescriptor
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 attribute | Value | Comments |
---|---|---|
| RSA/ECB/OAEPWithSHA-384AndMGF1Padding | Must be declared so the iD2 provider accepts it:
|
| Â | Â |
| HSM | Must be "HSM" for keys stored in the HSM. |
|
| Â |
| The user PIN of the HSM. | From and including PRIME 3.8, the |
| The alias of the respective key. | In the HSM, the keypair and the certificate must be stored within the same label/alias. |
| 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:
|
In addition, you may get a ClassNotFoundException for various BouncyCastle classes in crypto-related use-cases like softtoken requests, for example:
|
To avoid this, you have these options:
Deploy each Identity Manager webapp on its own dedicated Tomcat instance.
OR
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).
CMSDK JARs:
cmcommon*.jar
cmsdk-*.jar
common-*.jar
BouncyCastle JARs:
bcmail-*.jar
bcpgp-*.jar
bcpkix-*.jar
bcprov-*.jar (including bcprov-ext-*.jar)
Additional information
Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions