JCOP 4.5 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 4.5 cards with the Idopte Middleware.

Only cards based on the common IN Groupe profile are supported.

Keyset and Chip auth configuration

Configure keysets and chip auth

Some operations require one or more keysets to be defined to enable external authentication. 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.

In addition, a chip auth key config needs to be defined for all use-cases that require a secure channel. It consists of a key path and a key ID.

The following values are used in the example below:

Chip auth key config:

The key SK_FILEMGMT is located within ADF Agent file instead of the master file.
Hence you need to add the file id prefix to the path, so the total path becomes FIILEID/KEYID .

Please refer to the profile documentation for the respective IDs.

Do the following:

Define the keyset configuration. 

Example: Keyset configuration

[Description]
...
KeysetSkAdmin=#theKeyLabel1:theKeyPath1
KeysetSkUnblkPin=#theKeyLabel2:theKeyPath2
KeysetSkFileMgmt=#theKeyLabel3:theKeyPath3
ChipAuthKeyConfig=#theKeyPath4:theKeyId4

You can also use mapped fields:

Example: Keyset configuration - mapped field

[Fields]
KEYSET_ADMIN=

[Description]
...
KeysetSkAdmin=KEYSET_ADMIN

Configuration overview

Overwiew of which keyset and chip auth parameters to configure, depending on the use-case:

Card initialization/activation

Initialize card

Keyset parameters required: KeysetSkAmin and ChipAuthKeyConfig.

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

A common PUK is available that can be used to unblock global PIN and signature PIN. It is configured during pre-personalization and is enabled during the InitToken step.

Example

Example: Card initialization (PIN pad reader only)

[Fields]
TRANSPORT_PIN=
 
[Description]
...
InitToken=true
KeysetSkAdmin=...
ChipAuthKeyConfig=...
 
# 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.
# Transport pin is also known as "activation pin".
IdopteTransportPin=TRANSPORT_PIN

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 KeysetSkUnblkPin!

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

Example

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

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

Unblock signature/global PIN via SkUnblkPin

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

Keyset parameter required: KeysetSkUnblkPin.

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

Example

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

[Description]
...
SetPin=true
SignPin=!FROM_USER_DIALOG_2_FIELD_AUTO
KeysetSkUnblkPin=...

Unblock signature/global PIN via PUK

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

No keyset parameters are required. Do not set KeysetSkUnblkPin!

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

Example

Example: Signature PIN unblocking (via PIN pad reader or dialogs, auto-detected)

[Description]
...
SetPin=true
InitialPUK=!FROM_USER_DIALOG_1_FIELD_AUTO
SignPin=!FROM_USER_DIALOG_2_FIELD_AUTO

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: KeysetSkAdmin and ChipAuthKeyConfig.

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

Example

Example: Delete all keys and certificates (from card)

[Description]
...
KeysetSkAdmin=...
ChipAuthKeyConfig=...
ApplicationList=X
 
[Application_X]
DeleteAllObjects=true

Certificate requests

Request certificates

The current card profile supports two "containers" in which to store certificates: sign (guarded by the signature PIN) and mpp (guarded by the global PIN).

It is mandatory that you specify the location for each certificate you want to write. Valid location values are (case insensitive) Signature and MPP. Key archival or recovery is only possible with the MPP location.

For key archival you have to configure the key size either in the CA itself or via the KeySize parameter of the IDM certificate template, depending on the CA and its configuration.
For example, in Smart ID Certificate Manager you need to use a key procedure format with kar.key.type = RSA and keylength.value = 3072 in your archival procedure.

For key recovery you cannot specify the key size, as it is already pre-defined by the key to be recovered.

For PKCS#10 requests you have to set the correct key size via the KeySize parameter in the encoding description, as shown in the encoding example further below.

Required keyset parameters: KeysetSkAdmin and ChipAuthKeyConfig.

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

 The service task "Cert: Load Key History List" must be configured to recover just one single cert, otherwise the limit of allowed certificates can 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]
KeysetSkAdmin=...
ChipAuthKeyConfig=...
...
 
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=#mpp 
 
[Application_B]
# key archival for encryption/confidentiality certificate
P12PASSWORD=P12PASSWORD_B
CertTempl=MyEncCertTemplate
KeyArchivalRequest=true
StoreUserCertOnly=true
Location=#mpp 
# keysize for archival is configured either in CA or in IDM cert template (depends on the CA config)
 
[Application_C]
# keypair generation and PKCS#10 request for signature certificate
CertTempl=MySigCertTemplate
CertKeyListReturnField=MySigCertTemplate_CREATED_CERTS
StoreUserCertOnly=true
SignP10WithDummyKey=true
Location=#signature
# keysize must be 3K for PKCS#10 request
KeySize=3072

[Application_D]
# keypair generation and PKCS#10 request for authentication certificate
CertTempl=MyAuthCertTemplate
CertKeyListReturnField=MyAuthCertTemplate_CREATED_CERTS
StoreUserCertOnly=true
SignP10WithDummyKey=true
Location=#mpp
# keysize must be 3072 for PKCS#10 request
KeySize=3072

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 parameters: none.

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
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: KeysetSkFileMgmt and ChipAuthKeyConfig

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
KeysetSkFileMgmt=...
ChipAuthKeyConfig=...
ef.id.familyName=lastname
ef.id.firstName=name

Limitations

Card firmware requirements for pinpad readers

Creating certificates and keys on JCOP 4.5 cards requires card firmware with support for chained APDUs when used with certain pinpad readers (e.g. Xiring / Ingenico Leo series).
For those readers the cards need to have version 4.1.1 of the Chipdoc applet.

Limited support for pre-release cards

Pre-release cards produced before 2023-10-12 are not supported due to a flaw in the card profile fixed in later revisions.
It would prevent proper authentication for write access to EF data containers.

Additional information