Skip to main content
Skip table of contents

Encoding using Idopte middleware in Identity Manager

This article includes updates for Smart ID 23.04.16 and 23.10.5.

This article describes how you create descriptions for the Idopte middleware. An encoding description contains the information for the electronic personalization of a card. You import the encoding description from a file. This can be used in Smart ID Identity Manager.

Smart ID Desktop App and Smart ID Identity Manager communicate via Smart ID Messaging. Smart ID Identity Manager uses the Inside Server for secure channel establishment and authentication to the card.

Smart ID Identity Manager communicates with the client- and server-side part of the Idopte middleware via the webservice endpoints. Smart ID Messaging and Smart ID Desktop App communicates with the client-side.

Prerequisites

  • The machines with the card readers must have Idopte middleware and Smart ID Desktop App installed locally and a browser to access Smart ID Identity Manager.

  • Smart ID Identity Manager version 23.04.16 or later (for 23.04 series)/ 23.10.15 or later (for 23.10 series).
    Earlier versions have more limited or missing support for Idopte.

Smart ID Identity Manager versions 23.10.0 to 23.10.2 are not supported.

  • Smart ID Desktop App version 1.12.2 or later. 

  • Idopte Middleware  6.23.0.30 or later

  • Inside Server version 1.4.3 or later with attached HSM for handling secrets

Authentication communication

Idopte Web App Certificate authenticates Identity Manager Operator against Idopte middleware installed on the machines with the card readers.

  1. Create a key pair, that is, a private key and a public key.

  2. Send the public key together with a symbolic URL (for example https://smartiddesktopapp.customerdomain), to the Idopte company. You will then receive a certificate in X.509 format (previously a custom format was used).
    This certificate has a limited validity of several months and needs to be refreshed regularly.

Configuration

Configure Idopte web app certificate

The web app certificate is supplied by Idopte in a file like this:
3j$yX...etc...!tM%V|MIIEZ...etc...+3MA=
Note that it is truncated here with ...etc... for brevity.

It contains the certificate in the custom legacy format and in X.509 format, separated by a pipe (|) symbol.

Identity Manager only supports the X.509 format, thus anything before the pipe symbol must be removed when configuring it in Identity Manager. The pipe symbol itself may be retained but is optional.

You must configure the certificate together with the private key in Identity Manager Operator.

  1. Configure the Idopte Web App Certificate in idm-operator/WEB-INF/classes/system.properties. 

    Example: Web App Certificate

    CODE 
    hermodEncodingService.idopteCert=MIIEZ...etc...+3MA=

    For docker-based installations, you must configure the Idopte Web App certificate in docker/compose/identitymanager/operator/docker-compose.yml as shown below:
    Example

CODE 
--- version: "3.7" 
services: smartid-idm-operator:
  extends:
    file: docker-compose-base.yml
    service: smartid-idm-operator
  environment: - 'SYSTEM_PROPERTIES={ ...etc...
                   "hermodEncodingService.idopteCert" : "MIIEZ...etc...+3MA="
 ...etc...

  1. Store the private key in an HSM or encapsulated in a password protected .p12 file (named idopteAuthentication.p12 in the example below) alongside the actual X.509 web application certificate, which contains the symbolic URL as SAN URI extension. 

  2. Configure the .p12 file in idm-operator/WEB-INF/classes/engineSignEncryptConfig.xml.

For docker-based installations, place the idopteAuthentication.p12 into docker/compose/certs/ and reference it in docker/complose/identitymanager/config/signencrypt.xml.

Identity Manager Operator can now prove its identity against the Idopte Middleware when the communication starts.

Example

An HSM can also be used.

Example: engineSignEncryptConfig.xml
CODE 
<?xml version="1.0" encoding="UTF-8"?> 
  <engineSignEncrypt> 
    <descriptors>
    <!-- ... some other configurations ... -->
    <descriptor name="idopteAuthentication" version="1">
      <type algorithm="NONEwithRSA" key="idopteAuthentication" />
    </descriptor>
    <!-- ... some other configurations ... -->
    </descriptors>

    <keys>
    <!-- ... some other configurations ... -->
    <key name="idopteAuthentication"> 
      <type name="pkcs12" locationValue="classpath:idopteAuthentication.p12" pin="thePinGoesHere"/>
    </key>
    <!-- ... some other configurations ... -->
  </keys> 
</engineSignEncrypt>

Configure Inside Server

Identity Manager must connect to the Inside Server to handle certain secrets used for the secure channel and authenticating to the card.

A two-way TLS handshake is needed between Identity Manager and the Inside Server. 

  1. Configure the Inside Server URL in idm-operator/WEB-INF/classes/system.properties. See an example below:

    Example: Inside server URL

    CODE 
    # URL of Inside Server
insideRestClient.url=https://<host_name>:<port>

    For docker-based installations you need to edit docker/compose/smartid.env. See an example below:

    Example: Inside server URL definition (smart.env) - Docker

    CODE 
    INSIDE_SERVER_URL='https://<host_name>:<port>'

    The variable must be referenced by docker/compose/identitymanager/operator/docker-compose.yml. See an example below:

    Example: Inside server URL reference (docker-compose.yml) - Docker

    CODE 
    --- version: "3.7" 
services: smartid-idm-operator:
  extends:
    file: docker-compose-base.yml
    service: smartid-idm-operator
  environment: - 'SYSTEM_PROPERTIES={ ...etc...
                   "insideRestClient.url" : "${INSIDE_SERVER_URL}",
 ...etc...

  2. Configure the Identity Manager p12 file to use as client authentication for the Inside Server in idm-operator/WEB-INF/classes/engineSignEncryptConfig.xml

  3. Add the Inside Server certificate to the Identity Manager truststore (for example tomcat/conf/prime.truststore), via a suitable application like Keystore Explorer or Java's keytool command:

    Keytool import example

    CODE 
    # note that keytool refuses to open keystores with very short passwords (less than 6 characters) - use e.g. Keystore Explorer to set a secure password in that case keytool -importcert -file insideServer.cer -keystore prime.truststore -alias "Inside Server cert"

For docker-based installations:

  • Place the client auth file insideClientAuth.p12 into docker/compose/certs/ and reference it in docker/complose/identitymanager/config/signencrypt.xml.

  • Place the Inside Server certificate into docker/compose/cacerts/.

Example

An HSM can also be used.

Example: Client auth keystore
CODE 
<?xml version="1.0" encoding="UTF-8"?>
  <engineSignEncrypt>
    <descriptors>
       <!-- ... some other configurations ... -->
       <descriptor name="insideClientAuth" version="1">
         <type algorithm="" size="" result="" key="insideClientAuth" />
       </descriptor>
    </descriptors>
    <keys>
      <!-- ... some other configurations ... -->
      <key name="insideClientAuth">
        <type name="pkcs12" locationValue="classpath:insideClientAuth.p12" pin="thePinGoesHere"/>
      </key>
      <!-- ... some other configurations ... -->
  </keys>
</engineSignEncrypt>

Configure Pinpad Timeout

By default the Idopte middleware has a pinpad timeout of 30 seconds.
Starting with version 6.23.0.30 of Idopte SSMW (which ships with IDM 23.04.15 / 23.10.5 and above), this can be overridden as follows:

  1. Create the file idoss.conf in docker/compose/identitymanager/config/ to configure the pinpad timeout as desired (120 seconds in the example below):

    JSON 
    SecuritySuite
{ PinpadTimeout = 120 }

  2. Create a volume mount for the new file in docker/compose/identitymanager/operator/docker-compose.yml. See an example below:

    YAML 
    ...
  volumes:
      - "../config/idoss.conf:/etc/idoss.conf:ro"
	  ...

  3. Restart the IDM Operator container, if already running, by running

    BASH 
    docker compose down && docker compose up -d

    from the docker/compose/identitymanager/operator/ folder, to make sure the new config file is used.

Card support

Supported card types

Only the following cards are supported by IDM when used with the Idopte middleware:

Card type detection

You can detect whether you are dealing with a JCOP 3 or JCOP 4.5 card by reading the token info JSON, as shown in Reader/card selection and information in Identity Manager .

The resulting JSON object will contain the attribute "jcopVersion", set to either "3" or "4.5".

Smart ID Desktop App requirement

Specify device ID

Encoding via the Idopte middleware is supported only for Smart ID Desktop App (version 1.12.2 or higher). 
For encodings on card operation tasks you need to specify the appropriate device ID ("8711").

Define the device ID in the encoding description. See the example below:

Example: Device ID location
CODE 
[Encoding]
Type=1024,Chip
Devices=8711
...

For card production tasks, you must specify "Personal Desktop App (PDA)" as production component on the respective card object.

Middleware selection

Select Idopte middleware

You must specify the name "idopte" since a webservice-interface is used instead of the PKCS#11 interface to enable use of the secure channel.

Add Idopte in the encoding description. 

Example: Select Idopte middleware
CODE 
[Description]
PKCS11Library=idopte
...

Idopte middleware limitations

Idopte incompatibility with Alcor Micro USB smart card readers

The Idopte middleware is incompatible with Alcor Micro USB Smart Card Readers, which are often integrated in Lenovo notebooks. If you try to connect to the card, the PC/SC connection is lost. This appears to be a driver/hardware issue.

Unsupported encoding parameters

The following is a non-exhaustive list of encoding parameters which are unsupported in encodings for the Idopte middleware.

Using unsupported parameters in most cases will result in encoding failure due to an "UnsupportedOperationException". The exception message can include a hint about parameters that possibly need to be removed from the encoding description.

  • PUK=...

  • SignPUK=...

  • CardManagerKey=... (ignored, no exception thrown)

  • NewCardManagerKey=...

  • TokenInfoJsonField=...

  • MDCardID=...

  • MDCardSerialNumber=...

  • CMSCardSerialNumber=...

  • CardOSSkiThumbprintField=...

  • OSVersionField=..

  • PackageInformationField=...

  • DeleteProfile=...

  • UseCardManagerKey=...

  • BlockCard=...

  • InitialSignPUK=... (ignored, no exception thrown)

  • InitialLabel=... (ignored, no exception thrown)

Subject to change in future versions.

Limited PIN dialog support

Card activation (InitPin=true) does not support PIN dialogs (for transport/global/signature PIN). Any PIN must be passed in from the process or entered through a PIN pad.

No CSR signing with keys from card

CSR signing with the corresponding private key on the card is not supported. PKCS#10 certificate requests are protected by the secure channel instead.

Require PIN Input For Renewal

Configure Extra PIN Input

Certificate and key writing is authenticated using various symmetric keys.

If you want to additionally enforce having the card holder enter the PIN / signature PIN during renewal, you can set the IdopteExtraPinInput flag to true and specify which PIN(s) to enter, like in the following examples:

Require input of global PIN via dialog or pinpad (autodetect)
CODE 
[Description]
IdopteExtraPinInput=true
PIN=!FROM_USER_DIALOG_1_FIELD_AUTO
Require input of signature PIN via dialog
CODE 
[Description]
IdopteExtraPinInput=true
SignPIN=!FROM_USER_DIALOG_1_FIELD
Require input of both PINs via pinpad
CODE 
[Description]
IdopteExtraPinInput=true
PIN=!FROM_PROTECTED_AUTHENTICATION_PATH
SignPIN=!FROM_PROTECTED_AUTHENTICATION_PATH

This will force the card holder to authenticate with the required PIN(s) before any certificate requests can be processed.

Setting the IdopteExtraPinInputFlag to true without also specifying which PIN(s) to enter has no effect.

Troubleshooting

ERROR: PinPad unsupported CKR_ARGUMENTS_BAD

This error can occur when using outdated PIN pad reader drivers that are not able to recognize the PIN pad reader. If an older Idopte middleware version is already installed, the installer will only unpack the drivers but not reconfigure the device to use them.

Solution:

  • To use the new drivers, open the device manager and select the smart card reader. If the PIN pad reader is not visible, click update driver and select the appropriate PIN pad reader.

  • To verify, open the Idopte middleware and select general information, where you can see the reader name and PIN pad authentication information. PIN pad authentication must be true when any PIN pad reader is connected.

Additional information

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close