Configure Card Job Encryption For Card SDK

Starting with Identity Manager version 6.1.0 you can optionally encrypt all card jobs sent between Identity Manager and Nexus Card SDK.

It is not yet integrated into IDM’s tooling for certificate bootstrapping and requires manual setup described below. Nexus Card SDK also requires manual setup.

Version Requirements

• Identity Manager 6.1.0 or later versions

• Card SDK 6.6.0.15 or later versions

Overview

In order to encrypt card jobs to Card SDK, a common keypair is first generated and uploaded to every Card SDK installation.

• A keypair is generated, stored in PKCS#12 file and then uploaded to every Card SDK instance (the password is stored in encrypted form by Card SDK).

• A self-signed certificate for that keypair is issued and either imported into an HSM or stored in a PKCS#12 file (without the private key!) for IDM.
  See Configure HSM in Identity Manager for general info concerning HSM configuration.

• The CardJobEncForCardSDK descriptor is configured in IDM referencing the above certificate and its public key.
  See section “CardJobEncForCardSDK“ in Sign and encrypt engine descriptors.

• For each card job request from IDM to Card SDK, an ephemeral AES key is generated with which the card job and its response shall be encrypted. To transfer the AES key to Card SDK, it is encrypted with the above public key.

Setup

Common Preparations

1. Create a RSA key pair (4096 bits recommended) with a certificate (may be self-signed or CA-issued) and save it in a PKCS#12 file named cardJobEncKeypair.p12 with a strong, randomly generated password.
   Recommended key-usages: dataEncipherment, keyEncipherment.

2. Export the certificate (without private key) in binary format as cardJobEncCert.cer.

3. Either…

   1. PKCS#12 only: Create a new PKCS#12 file cardJobEncCert.p12 containing just the above certificate (without private key). It shall have a different password from cardJobEncKeypair.p12's password.

   2. HSM only: import cardJobEncCert.cer into the HSM and set the CKA_LABEL attribute to cardJobEncCert

4. Upload cardJobEncKeypair.p12 to every Card SDK instance that you intend to use with the IDM installation in question.
   Steps per Card SDK instance:

   1. open Configuration Manager

   2. double-click the IDProductionService entry

   3. click CardJob PKCS#12 button

   4. browse to cardJobEncKeypair.p12

   5. enter the P12 password

Tomcat Deployment

Identity Manager Tomcat Deployment

1. stop Tomcat running IDM Operator

2. PKCS#12 only: copy cardJobEncCert.p12 into the folder webapps/idm-operator/WEB-INF/classes/

3. edit webapps/idm-operator/WEB-INF/classes/engineSignEncrypt.xml as follows

   1. add the following entry to the <descriptors> section

      XML

      <descriptor name="CardJobEncForCardSDK" version="1">
        <type algorithm="AES/CBC/PKCS7Padding" size="256" result="" 
          key="cardJobEncCert"
          asymCipher="RSA/ECB/OAEPWithSHA3-512AndMGF1Padding"/>
      </descriptor>
      

   2. add one of following entries to the <keys> sections (depending on whether you stored the certificate in a HSM or PKCS#12 file)

      XML

      <!-- HSM - make sure you adjust the example parameters below -->
      <key name="cardJobEncCert">
        <type name="HSM"
          locationValue="/path/to/the/hsmPkcs11LibWithoutFileExtension"
          pin.encrypted="hsmUserPinGoesHere" alias="ckaLabelOfCertGoesHere"
          slot="slotNumGoesHere" />
      </key>
      

      XML

      <!-- PKCS#12 - make sure you adjust the example parameters below -->
      <key name="cardJobEncCert">
        <type name="pkcs12" locationValue="classpath:cardJobEncCert.p12"
          pin.encrypted="thePasswordGoesHere" />
      </key>
      

4. restart Tomcat
   => from now on this instance will encrypt all card jobs sent to Card SDK and expect an encrypted response (plain-text responses are rejected)

Identity Manager Docker Deployment

1. shut down IDM Operator container

   Bash

   # run this as root/a member of the "docker" group (if rootful Docker daemon)
   # or else as the user running the rootless Docker daemon
   cd docker/compose/identitymanager/operator
   docker compose down
   

2. PKCS#12 only: copy cardJobEncCert.p12 into the certs folder and make sure the IDM operator container will be able to read it.
   Global read permissions are OK here, as cardJobEncCert.p12 contains only public data.

   Bash

   # run these as a user who has write permissions in the certs/ folder,
   # adjust paths accordingly
   cp /THE/PATH/TO/cardJobEncCert.p12 docker/compopse/certs/cardJobEncCert.p12
   chmod a+r docker/compopse/certs/cardJobEncCert.p12
   

3. edit identitymanager/config/signencrypt.xml as follows:

   1. add the following entry to the <descriptors> section

      XML

      <descriptor name="CardJobEncForCardSDK" version="1">
        <type algorithm="AES/CBC/PKCS7Padding" size="256" result="" 
          key="cardJobEncCert"
          asymCipher="RSA/ECB/OAEPWithSHA3-512AndMGF1Padding"/>
      </descriptor>
      

   2. add one of following entries to the <keys> sections (depending on whether you stored the certificate in a HSM or PKCS#12 file)

      XML

      <!-- HSM - make sure you adjust the example parameters below -->
      <key name="cardJobEncCert">
        <type name="HSM"
          locationValue="/path/to/the/hsmPkcs11LibWithoutFileExtension"
          pin.encrypted="hsmUserPinGoesHere" alias="ckaLabelOfCertGoesHere"
          slot="slotNumGoesHere" />
      </key>
      

      XML

      <!-- PKCS#12 - make sure you set the correct password -->
      <key name="cardJobEncCert">
        <type name="pkcs12" locationValue="file:/certs/cardJobEncCert.p12"
          pin.encrypted="thePasswordGoesHere" />
      </key>
      

4. restart IDM Operator container (we assume you are still inside the identitymanager/operator/ folder)

   Bash

   # run this as root/a member of the "docker" group (if rootful Docker daemon)
   # or else as the user running the rootless Docker daemon
   docker compose up -d
   

   => from now on this instance will encrypt all card jobs sent to Card SDK and expect an encrypted response (plain-text responses are rejected)

Limitations

• Merely configuring a card job encryption keypair in Card SDK will not enforce encryption of card jobs (configuring the CardJobEncForCardSDK descriptor in IDM is required).

• Once the CardJobEncForCardSDK descriptor is configured, IDM can only exchange card jobs with Card SDK instances that have the matching keypair P12 uploaded.

• In cluster deployments, all IDM Operator nodes require an identical setup of the CardJobEncForCardSDK descriptor. Otherwise card jobs might be unencrypted or incorrectly encrypted in some cases.

Last updated: July 07, 2026