JCOP 3 cards with Idopte middleware

This article includes updates for Smart ID 23.04.9 and 23.10.3.

This article contains details specific to the use of JCOP 3 cards with the Idopte Middleware.

Only cards with one specific custom profile are supported.

Signature slot support

Define signature slot location

The current card profile supports up to two signature certificates, protected by a dedicated signature PIN. Two authentication certificates and two confidentiality certificates can be written onto the card, protected by the normal PIN.

To select the slot, you need to specify the location. Valid location values are (case insensitive) Signature and Confidentiality. If omitted or set to any other value, the authentication container will be used. Key archival or recovery is only possible with the Confidentiality location.

• Define the signature slot location in the encoding description. 

  Example: Signature slot location

  CODE

  [Application_X]
  location=#Signature
  ...

Keyset configuration

Configure keysets

Some operations require one or more keysets to be defined to enable external authentication and secure channel establishment. Each keyset configuration consists of a key label in an HSM (for example connected to the Inside Server), and in most cases a key path indicating a matching key on the card.

The following values are used in the example below:

Do the following:

• Define the keyset configuration. 

  Example: Keyset configuration

  CODE

  [Description]
  ...
  KeysetAD=#theKeyLabel1:theKeyPath1
  KeysetADMIN=#theKeyLabel2:theKeyPath2
  KeysetPUK=#theKeyLabel3:theKeyPath3
  KeysetFileMgmt=#theKeyLabel4:theKeyPath4
  KeysetPinAD=#theKeyLabel5

  You can also use mapped fields:

  Example: Keyset configuration - mapped field

  CODE

  [Fields]
  KEYSET_AD=
   
  [Description]
  ...
  KeysetAD=KEYSET_AD

Configuration overview

Overview of which keyset parameters to configure, depending on the use-case:

Card initialization

Card initialization steps for explanation only (not executed by the user)

• External authentication with an AD keyset.

• Mutual authentication with an ADMIN keyset. This is potentially done multiple times during initialization.

• Login with transport PIN (parameter "IdopteTransportPin=..."). For information about decrypting the transport PIN, see section "Credentials: Decrypt fields using Inside Server" in Credentials - Standard service tasks in Identity Manager. 

• Initialization of global PIN (parameter "PIN=...") and signature PIN (parameter "SignPIN=...").

• Unblocking the single-use PUKs for global/signature PINs as these are already present on the card (to match existing cards using the same profile).

• Unblocking AD PIN, it is already present on the card.

• Blocking the transport PIN.

Keyset parameters required: KeysetAD and KeysetADMIN.

Each of the three PINs (transport/global/signature) must come from a mapped field, or be typed on a PIN pad. Using a PIN dialog is not supported for card initialization.

The step below be run only once , attempting to initialize an already initialized ("activated") card will result in an error.

• Define the initialization of the card in the encoding description (executed by the user).

Example

Example: Card initialization (PIN pad reader only)

[Fields]
TRANSPORT_PIN=
 
[Description]
...
InitToken=true
KeysetAD=...
KeysetADMIN=...
 
# technically you can also get PIN and SignPIN from a process variable by using a field ref. instead
PIN=!FROM_PROTECTED_AUTHENTICATION_PATH
SignPIN=!FROM_PROTECTED_AUTHENTICATION_PATH
 
# Note: if you want the user to enter the transport pin directly,
# you can remove the TRANSPORT_PIN field and use !FROM_PROTECTED_AUTHENTICATION_PATH instead of the field ref.
# (KeysetADMIN is not needed either, if you take all pins from the PIN pad)
IdopteTransportPin=TRANSPORT_PIN

Both the global PIN and the signature PIN each have three single-use PUKs assigned to them, which can be used for PIN unblocking.
Identity Manager does not support these PUKs, the PUK keyset is used instead to enable unblocking.

Change and unblock PIN

Change signature/global PIN

You can change the global and/or signature PIN with the user entering the old and new PIN(s) in a dialog or through a PIN pad reader.

No keyset parameters are required. Do not set KeysetPUK.

• Change the signature/global PIN in the encoding description. 

Example

Example: Signature PIN change (via PIN pad reader or dialog, auto-detected)

[Description]
...
SetPin=true
SignPIN=!FROM_USER_DIALOG_3_FIELD_AUTO

Unblock signature/global PIN

You can unblock the global and/or signature PIN, with the user entering the new PIN(s) in a dialog.

Required keyset parameters: KeysetPUK, KeysetPINAD, and KeysetADMIN (PIN pad readers only).

• Unblock the global/signature PIN in the encoding description. 

Example

Example: Signature PIN unblocking (via normal reader)

[Description]
...
SetPin=true
SignPin=!FROM_USER_DIALOG_2_FIELD
# KeysetADMIN is not needed if this encoding is purely for normal readers
KeysetPUK=...
KeysetPINAD=...

Example: Global PIN unblocking (via PIN pad reader or dialog, auto-detected)

[Description]
...
SetPin=true
Pin=!FROM_USER_DIALOG_2_FIELD_AUTO
KeysetPUK=...
KeysetPINAD=...
# as we use auto-detect and thus a pinpad reader may be used, we need to set KeysetADMIN as well
KeysetADMIN=...

Delete certificates and keys

Delete certificates and RSA keys from card

You can bulk-delete all existing certificates and RSA keys from the card. Selective deletion of individual certificates and keys is not supported.

Required keyset parameters: KeysetAD and KeysetADMIN.

• Delete all existing certificates and RSA keys from the card in the encoding description. 

Example

Example: Delete all keys and certificates (from card)

[Description]
...
KeysetAD=...
KeysetADMIN=...
ApplicationList=X
 
[Application_X]
DeleteAllObjects=true

Certificate requests

Request certificates

The card profile supports storage of up to six certificates and associated 2048 bit RSA keypairs organized into three "containers".

"conf" (confidentiality) refers to encryption certificates (for example for S/MIME).

Required keyset parameters: KeysetAD and KeysetADMIN.

You must always disable certificate chain writing ("StoreUserCertOnly=true") since the card profile does not allow for storage of CA certificates.

You must enable dummy signing for any PKCS#10 requests ("SignP10WithDummyKey=true") since signing CSRs with the actual key on the card is not supported. Future versions will replace this with actual CSR signing, requiring you to enter the respective PIN (usually on a PIN pad reader, via "PIN=!FROM_PROTECTED_AUTHENTICATION_PATH" or "SignPIN=!FROM_PROTECTED_AUTHENTICATION_PATH" respectively).

Three new certificates are requested in the example below: authentication, signature, and confidentiality (using key archival for the latter).

Key archival of a historical confidentiality cert must be done. The service task "Cert: Load Key History List" must be configured to recover only a single certificate, otherwise the limit of allowed certificates will be exceeded. For more information, see section "Cert: Load Key History List" in Standard service tasks in Identity Manager.

• Define the request for multiple certificates in the encoding description.

Example

Example: Request multiple certificates

[Fields]
MySigCertTemplate_CREATED_CERTS=
MyAuthCertTemplate_CREATED_CERTS=
P12PASSWORD_A=
P12PASSWORD_B=
RecoveryCertificateData_A=
...
 
[Description]
KeysetAdmin=...
KeysetAD=...
...
 
ApplicationList=ABCD
 
[Application_A]
# key recovery for encryption/confidentiality certificate
CertTempl=Recovery
RecoveryTemplate=Recovery
KeyRecoveryRequest=true
P12PASSWORD=P12PASSWORD_A
RecoveryCertificateData=RecoveryCertificateData_A
StoreUserCertOnly=true
Location=#confidentiality
 
[Application_B]
# key archival for encryption/confidentiality certificate
P12PASSWORD=P12PASSWORD_B
CertTempl=MyEncCertTemplate
KeyArchivalRequest=true
StoreUserCertOnly=true
Location=#confidentiality
 
[Application_C]
# keypair generation and PKCS#10 request for signature certificate
CertTempl=MySigCertTemplate
CertKeyListReturnField=MySigCertTemplate_CREATED_CERTS
StoreUserCertOnly=true
SignP10WithDummyKey=true
Location=#signature
 
[Application_D]
# keypair generation and PKCS#10 request for authentication certificate
CertTempl=MyAuthCertTemplate
CertKeyListReturnField=MyAuthCertTemplate_CREATED_CERTS
StoreUserCertOnly=true
SignP10WithDummyKey=true
# auth certs use default Location

EF data containers

Read EF data objects

Smart ID Identity Manager supports reading the http://EF.Id (Card Holder Identification) and EF.Fonction (Professional information) data containers.

Required keyset parameter: KeysetFileMgmt.

Do the following in the encoding description:

1. In the [Description] section, set readDataObjects to "true".

2. In the [Description] section, provide the file management keyset.

3. In the [Fields] section, add the keys of the data you want to read.

   • The keys for the EF.Fonction container are ef.function.job, ef.function.postingPlace and ef.function.productionDate.

   • The keys for the http://EF.Id container are ef.id.familyName, ef.id.firstName, ef.id.rio, ef.id.uin, ef.id.orgName1 and ef.id.orgName2.

4. In the Encoding Fields tab, set the added fields to "Read" and map them to a process variable.

Example

Example: Reading of EF data objects

[Fields]
ef.function.job=
ef.function.postingPlace=
ef.function.productionDate=
  
ef.id.familyName=
ef.id.firstName=
ef.id.rio=
ef.id.uin=
ef.id.orgName1=
ef.id.orgName2=
  
[Description]
PKCS11Library=idopte
keysetFileMgmt=......
readDataObjects=true

Update EF data containers

Smart ID Identity Manager supports updating the http://EF.Id (Card Holder Identification) and EF.Fonction (Professional information) data containers.

Required keyset parameter: KeysetFileMgmt.

With the current profile, updating the ID data container is only possible on temporary cards.

Do the following in the encoding description:

1. In the [Description] section, provide the file management keyset.

2. In the [Description] section, set the keys of the data you want to update and map them to a field. Any keys you omit will keep their old value.

   • The keys for the EF.Fonction container are ef.function.job, ef.function.postingPlace and ef.function.productionDate.

   • The keys for the http://EF.Id container are ef.id.familyName, ef.id.firstName, ef.id.rio, ef.id.uin, ef.id.orgName1 and ef.id.orgName2.

3. In the [Fields] section, define the fields you referenced in the previous step.

4. In the Encoding Fields tab, set the value of the fields. To clear a field in a data container, map it to an empty value.

Example

Example: Update EF data objects

[Fields]
lastname=
name=
  
[Description]
PKCS11Library=idopte
keysetFileMgmt=......
ef.id.familyName=lastname
ef.id.firstName=name

Idopte middleware limitations

Serial number reading

When reading the ICCSN, the full value serial from EF_SN (without tag and length bytes) is returned.

The last digit is not displayed anywhere in the Idopte middleware.

Example

This is an example for a card which is shown in the Idopte middleware user interface as follows:
Card model: IAS ECC 9-250-03
Serial number: 2702338220012

EF_SN raw bytes (includes tag and length):                5A0A92500327023382200127
Full serial, i.e. EF_SN without tag and length bytes:         92500327023382200127  <=== this is returned
Shown in the Idopte UI:                                       9250032702338220012
Portion shown in the card model section:                      925003
Portion shown in the serial number section:                         2702338220012

Additional information