Comment: Remember to update the release version number before publishing externally.
| Info |
|---|
This article includes updates for Smart ID Identity Manager 24.R1. |
...
For more information, see Configure Tomcat below.
Prerequisites
...
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 , 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.
...
For 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.yml and 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.
...
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 deployment, edit the file docker/compose/identitymanager/config/signencrypt.xml needs to be edited instead.
| Note |
|---|
All Identity Manager clients that use the same database must have the same keys and certificates configured in the XML. |
| Expand |
|---|
| title | 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. | Code Block |
|---|
| <?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> |
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
| | | pin
| The user PIN of the HSM. | The pin.encrypted attribute is also supported to scramble the PIN.Note that for For Docker deployments it is required to scramble the PINs before starting the Identity Manager Admin and Identity Manager Operator containers (stop them by invoking docker compose down from within docker/compose/identitymanager/admin and docker/compose/identitymanager/operator, if already running).
This is done by first replacing each pin="thePlainTextPin" with pin.encrypted="thePlainTextPin" and then invoking the following command from within the docker/compose/identitymanager/bootstrap folder: docker compose run --rm scramble_sign_encrypt_config | 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 stored in HSM slot 0. | Note that the The first slot is not guaranteed to be 0. Slot numbering may differ, depending on the HSM. |
For more information, see Sign and encrypt engine in Identity Manager for further use cases that can be configured. |
...
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 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 instead. This ensures that the JARs are served from the Tomcat common classloader for all web apps.
...
bcmail-*.jar
bcpgp-*.jar
bcpkix-*.jar
bcprov-*.jar (including bcprov-ext-*.jar)
