A newer version of this documentation is available.

View Latest

SmartCard

[SmartCard]
AtrAllow=
AtrDeny=
:AutoUpdateKeyId=1
:BlockRawAlgorithm=0
:CalculateUsedTime=0
CheckExpire=60
:CommandChaining=0
:CreateUpdateCounter=1
:DefaultProfile=
DiskCache=0
:IgnoreEFDIR=0
:KeySizeECC=
:KeySizeRSA=
:LabelFromEDIR=0
:LoginTimeout=0
:MaxProfiles=3
:MayCreateWithSecondaryPIN=
:NoWriteMapping=
ObjectSortMode=2
PinExpire=0
PinMaxLen=
PinMinLen=
PinType=
:ProfileOrder=
TemporaryModel=
TemporaryValidity=30
:UseChallengeResponse=
UseInternalUpdate=1
:UseLastUpdate=1
:ValidateUpdateCounter=0

AtrAllow, AtrDeny

Net iD Client tries to use all smart cards with known ATRs (answer to reset). But there are situations when other clients should handle specific smart cards, so you can add a whitelist or blacklist of supported ATRs.

[SmartCard]
AtrAllow=
AtrDeny=3BD996FF8131FE454352455343454E444FFF;3BD996FF8131FE454352455343454E444FFE

AutoUpdateKeyId

The AutoUpdateKeyId parameter updates all connecting objects when CKA_ID is updated for an object. CKA_ID is used to connect private-key, public-key, and certificate. When this parameter is activated, an update of a private-key will also update the public-key and certificate.

BlockRawAlgorithm

Net iD Client uses any algorithm supported by the smart card. Some smart cards can configure support of the raw RSA algorithm so that the smart cards look identical. They will sometimes support raw RSA and sometimes not. To tell that raw RSA is supported when it is not can result in applications failing to use the smart card. This parameter disables raw RSA support even when the smart card implementation supports it.

This setting does not have any effects on smart cards without raw RSA support.
[SmartCard]
BlockRawAlgorithm=1

Values

0

Allow rsa-raw

1

Block rsa-raw

CalculateUsedTime

The CalculateUsedTime adds an internal counter that tracks the execution time and records that to the trace file.

[SmartCard]
CalculateUsedTime=0

CheckExpire

CheckExpire checks the validity period on the certificate. CheckExpire returns a value of the remaining time in seconds when less than or equal to the set value. If the remaining time is greater than the set value, it returns -1.

[SmartCard]
CheckExpire=<time>

Values

time

The time in days.

CommandChaining

Command chaining is a method of sending data to the smart card that exceed 256 bytes. Normally this is handled by the smart card implementation, so never change this value.

[SmartCard]
CommandChaining=0

CreateUpdateCounter

The update counter is needed to track updates of objects or PIN on the smart cards. Some smart cards have a built-in update counter, and other allows the creation of a custom data object that will store this information. This parameter controls the creation and will only create if enabled.

[SmartCard]
CreateUpdateCounter=1

DiskCache

The smart card cache stores all public data from the smart card to avoid reading the same data many times since the reading can be slow. The cache uses the cache service if it is available. It can also store the data on disk to keep the data even if the computer is rebooted.

[SmartCard]
DiskCache=0

DefaultProfile

Default profile is used when it is not possible to identify the smart card profile. It is used to investigate the smart card but should never be used for production environments.

Acceptable values are:

  • PKCS#15

  • ISO7816-15

  • GemSAFE v1

  • GemSAFE v2

  • GemSAFE

[SmartCard]
DefaultProfile=PKCS#15

IgnoreEFDIR

Most smart cards have an EFDIR file that can contain information about the smart card profile. Use the IgnoreEFDIR parameter to disable the reading of EFDIR.

Values

0

off

1

on

KeySizeRSA

The minimum and maximum sizes of RSA are specified in the smart card implementation. But it is possible to change those values for some smart cards. The upper WORD contains the minimum size, and the lower WORD contains the maximum size.

[SmartCard]
KeySizeRSA=0x04000800

KeySizeECC

The minimum and maximum sizes of ECC are specified in the smart card implementation. But it is possible to change those values for some smart cards. The upper WORD contains the minimum size, and the lower WORD contains the maximum size.

[SmartCard]
KeySizeECC=0x01000209

LabelFromEDIR

Most smart card profiles have their own way to specify smart card label, but may also be stored in EFDIR.

Values

0

off

1

on

LoginTimeout

LoginTimeout specifies the number of seconds the login procedure can be inactive. The counter resets when the PIN is used.

Resets the counter:

  • Login

  • Login (when already logged in)

  • Key usage (sign/verify/encrypt/decrypt/etc.)

  • Card update (create/delete/etc.)

Does not reset the counter:

  • Search for object

  • Reading object

  • Login status check

#define PIN1 0x01
#define PIN2 0x02
#define PIN3 0x04

[SmartCard]
LoginTimeout=<seconds>,<pin-bit-mask>

Values

seconds

Number of seconds that the PIN is valid.

pin-bit-mask

Specifies for which PINs the LoginTimeout is used. If no value is given, all PINs use the LoginTimeout value.

MaxProfiles

The MaxProfiles parameter tells the maximum number of smart card profiles. Usually, only one profile is required, but some smart cards contain many profiles.

[SmartCard]
MaxProfiles=3

MayCreateWithSecondaryPIN

Most smart cards create objects using primary PIN, even for secondary PIN objects. But some require secondary PIN when creating secondary PIN objects.

NoWriteMapping

Multi-PIN tokens usually update the tokens using PIN1, even for objects connected to PIN2. The NoWriteMapping parameter contains a semicolon-separated list of smart card profiles that require PIN2 for the update of objects connected to PIN2.

Example 1. Show only PIN1 dialog

For AdmUtil, only the PIN1 dialog is shown when NoWriteMapping is not specified or does not include the profile name.

[SmartCard]
NoWriteMapping=
Example 2. Show both PIN1 and PIN2 dialog

For AdmUtil, both the PIN1 and PIN2 dialog are shown when NoWriteMapping has a specified value.

[SmartCard]
NoWriteMapping=PKCS#15;IDPrime SIS

ObjectSortMode

Certificates are sorted based on certificate issuing date. The complete representation of date and time of day is given by 1970-01-01 00:00:00.

Sorting can be based on date, date and time of day, or no sorting.

#define SORT_MODE_NONE   0
#define SORT_MODE_DAY    1
#define SORT_MODE_SECOND 2

[SmartCard]
ObjectSortMode=2

Values

0

No sorting means that the order is based on how the certificates are stored on the smart card.

1

Date only, 1970-01-01

2

Date and time of day, 1970-01-01 00:00:00

PinExpire

The PinExpire parameter tells the number of days until a PIN change is required. Smart cards that support update counter with timestamps for PIN change can also include an automatic PIN expire functionality. This means that the end-user is forced to change the PIN at regular intervals.

[SmartCard]
PinExpire=<time>,<card_model>;<time>,<card_model>

Values

For smart cards with no support for PinExpire, that is, no possibility to write a timestamp, PinExpire is always set to 0.
<time>

The number of days until PIN must be changed.

<card_model>

Card model for which the time rule is valid. Optional argument.

Examples

Example 3. Set PIN update time for some specified cards.
[SmartCard]
PinExpire=60,IDPrime SIS 4.0.2;90,GemXpresso

PinMaxLen

PIN policy should be stored in the smart card profile. But the configuration can add more requirements. The PinMaxLen parameter tells the maximum number of characters in the PIN.

[SmartCard]
PinMaxLen=6

PinMinLen

PIN policy should be stored in the smart card profile But the configuration can add more requirements. The PinMinLen parameter tells the minimum number of characters in the PIN.

[SmartCard]
PinMinLen=6

PinType

PIN policy should be stored in the smart card profile But the configuration can add more requirements. The PinType parameter tells that a specific PIN policy is necessary.

// Password type:
// 0 -> all chars (case sensitive)
// 1 -> all chars (case insensitive)
// 2 -> all chars (max 2 in row or normal/keyboard sequence)
// 3 -> all chars (max 2 in row or normal sequence)
// 4 -> all chars (max 2 in row)
// 5 -> only digits
//
// Normal sequence:
// a-z, z-a, 0-9, 9-0
// Keyboard sequence:
// qwertyuiop, poiuytrewq
// asdfghjkl, lkjhgfdsa,
// zxcvbnm, mnbvcxz,
// qaz, zaq, wsx, xsw, ...

[SmartCard]
PinType=5

ProfileOrder

The ProfileOrder parameter tells the search sequence in which to identify the smart card profile.

Separate the values with a comma.

[SmartCard]
ProfileOrder=PKCS#15,ISO7816-15,GemSAFE,Buypass

Values

PKCS#15

 

ISO7816-15

 

GemSAFE

 

Buypass

 

TemporaryModel

There is some special handling for temporary smart cards. The TemporaryModel parameter contains a list of semicolon-separated models that are considered to be temporary.

[SmartCard]
TemporaryModel=BeIDt

TemporaryValidity

There is some special handling for temporary smart cards. The TemporaryValidity parameter tells the validity period for models that are considered to be temporary.

[SmartCard]
TemporaryValidity=<time>

Values

<time>

The time value is an integer.
It is given in seconds if the value is greater than 365, and it is given in days if the value is less than 365.

UseChallengeResponse

Challenge-response to unlock PIN is supported on some smart cards. The UseChallengeResponse parameter tells which smart card models that can use challenge-response. Some smart cards use challenge-response for PIN1, and PUK for PIN2, so it is possible to specify different values for each PIN.

[SmartCard]
UseChallengeResponse=<timeout pin1>[:<size pin1>] <timeout pin2>[:<size pin2>] <timeout pin3>[:<size pin3>],<ATR-model>

Values

timeout pin1|pin2|pin3

Timeout in seconds.

size pin1|pin2|pin3

The size is always 8 bytes.

Examples

For all IDPrime MD cards, you must examine the trace. If only PUK or SO-KEY is given as unlock type, it will be solved automatically.

Example 4. IDPrime MD trace.

PIN1 and PIN2 are handled automatically. PIN3 requires configuration settings because PUK is the default usage.

[00003676:00005196] 11.03.05.118 ProfilePrimeMD - Credential PIN1 available (size 6-16, unlock SO-KEY) (1)
[00003676:00005196] 11.03.05.118 ProfilePrimeMD - Credential PIN2 available (size 6-16, unlock PUK) (1)
[00003676:00005196] 11.03.05.118 ProfilePrimeMD - Credential PIN3 available (size 6-16, unlock PUK/SO-KEY) (2)
1 PIN1 and PIN2 are handled automatically because only SO-KEY or PUK is given as unlock type.
2 PIN3 requires configuration settings because PUK is default usage.
Example 5. IDPrime MD 830B using PIN1/PIN3 challenge-response and PIN2 PUK.

These are the settings for the smart card IDPrime MD 830B where PIN2 uses PUK, but PIN1 and PIN3 use challenge-response.

[SmartCard]
UseChallengeResponse=180 0 180,IDPrime MD 830B
You do not need to specify the size since it is always 8 bytes.
The example configuration above is not necessary since the settings specified in the example are set automatically by Net iD Client.

UseInternalUpdate

Some smart cards have an update counter, but may not store a timestamp. Some of those smart cards allows creation of data object, which will allow creation of an internal update counter that can use a timestamp. This timestamp then allows for the PIN expire functionality.

[SmartCard]
UseInternalUpdate=1

UseLastUpdate

Some smart cards have a reference to the last update counter but did not make this counter updateable, so it must be disabled.

[SmartCard]
UseLastUpdate=0

ValidateUpdateCounter

There are situations when the smart card is updated by external management software in parallel with our updating. The ValidateUpdateCounter parameter validates the current update counter before starting the smart card update.

[SmartCard]
ValidateUpdateCounter=0