Versions Compared

Version Old Version 18 New Version 19
Changes made by

David Banz

David Banz

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

This article is valid for Smart ID 24.R1 and later.

...

Smart ID Identity Manager offers support for HSM (Hardware Security Model) for several use cases:

...

The set of JAR files in Certificate Manager (CM) 8.4 and later has changed. This applies to Identity Manager in Smart ID 21.10 and later - see this note for the updates, see also section "Configure Tomcat" below.

Note

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 IDM 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

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

  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 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 32 bit and 64 bit version. Use the 64 bit version with the Identity Manager.

Tomcat Deployment on Windows

To be accessed, the library needs to be available in the PATH environment variable.

...

Copy it to your C:\Windows\System32 folder.

Docker Deployment

For Docker deployment, libjpkcs11 needs to be placed onto the docker host and then mounted into a the respective containers.
This is done by adding a volume mount to docker/compose/identitymanager/admin/docker-compose.yml and docker/compose/identitymanager/operator/docker-compose.yml.
In the example below we have libjpkcs11_x64-3.6.3.1.so (version number may vary) placed into the docker/compose/identitymanager/config/ folder, which is then mounted into the container’s Tomcat folder for native libs as libjpkcs11.so.

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

Configure engineSignEncryptConfig.xml / signencrypt.xml

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

...

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

Example extract of config XML
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

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

Note that for Docker deployments it is required to scramble the PINs before starting the IDM Admin and IDM 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 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.

...

  1. To avoid this, you have these options:

    1. Deploy each Identity Manager webapp on its own dedicated Tomcat instance (Docker deployments always work like this).

      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

Expand
titleUseful links