Comment: 24.R1 - updated use cases and other information across the article.

Remember to update the release version number before publishing externally.

This article includes updates for Smart ID Identity Manager 24.R1.

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.

The following use cases support storing the keys in an HSM:

Encryption and decryption of fields in the Identity Manager database (descriptor: encryptedFields)
Signing and verification of the object history (descriptor: objectHistorySigner)
Signing and validation of the configuration files (descriptor: configZipSigner)
Encryption of the configuration files (descriptor: configZipEncrypter)
Signing of emails (descriptor: signEmailDescriptor)
Creation of JWS signatures used for Smart ID messaging content provider API (descriptor: ContentProviderJWSSigner)
Authentication of Smart ID Self-Service users to the Identity Manager backend (descriptor: SelfServiceJWTSigner)
Decryption of PIN blobs from pre-personalized smart-cards created with the Personal Desktop Client (arbitrarily named descriptors)
Attestation for provisioning to Smart ID Mobile / Desktop Apps (descriptors: att_*)

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

Certificate Manager SDK 8.4 and later (as used in Identity Manager 21.10 and later) 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

For more information, see Configure Tomcat below.

Prerequisites

Installed Smart ID 24.R1 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, this depends on your use cases. Alias, slot, and PIN will be required in the configuration to access the 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 32 bit and 64 bit version. Use the 64 bit version with Identity Manager.

Tomcat deployment on Windows

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 deployment, libjpkcs11 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.

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

Configure engineSignEncryptConfig.xml/signencrypt.xml

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.

All Identity Manager clients that use the same database must have the same keys and certificates configured in the XML.

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>

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/.so (without extension) OR the DLL/.so's filename without extension
`pin`	The user PIN of the HSM.	The `pin.encrypted` attribute is also supported to scramble the PIN. 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.	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.

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 soft token requests, for example:
Caused by: java.lang.ClassNotFoundException: org.bouncycastle.jce.provider.BouncyCastleProvider

To avoid this, 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.

CMSDK JARs:

cmcommon*.jar
cmsdk-*.jar
common-*.jar

BouncyCastle JARs:

bcmail-*.jar
bcpgp-*.jar
bcpkix-*.jar
bcprov-*.jar (including bcprov-ext-*.jar)

Additional information

Useful links

Configure HSM in Identity Manager