Versions Compared

Version Old Version 41 New Version 42
Changes made by

Ylva Andersson

Ylva Andersson

Saved on

Key

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

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

Remember to update the release version number before publishing externally.

Info

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

...

title
Note

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

Expand

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

Code Block
languagexml
<?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.

...

  • bcmail-*.jar

  • bcpgp-*.jar

  • bcpkix-*.jar

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

Additional information

Expand
titleUseful links