End-User Documentation

CardOS API
V5.4 for Windows
User Manual Edition 11/2017

Your business technologists. Powering progress

© Atos Information Technology GmbH, 2004 - 2017 Disclaimer of Liability
All Rights Reserved
We have checked the contents of this manual for agreement with
The reproduction, transmission or use of this document or its the hardware and software described. Since deviations cannot
contents is not permitted without express written authority. be precluded entirely, we cannot guarantee full agreement.
Offenders will be liable for damages. All rights, including rights However, the data in this manual is reviewed regularly and any
created by patent grant or registration of a utility model or design, necessary corrections are included in subsequent editions.
are reserved. Suggestions for improvement are welcome.

Atos Information Technology GmbH Some of the specifications described herein may not be currently
Otto-Hahn-Ring 6 available in all countries. Please contact your local Atos
D-81739 Munich Information Technology GmbH sales representative for the most
Germany current information.

Contact: Subject to change without notice

Atos Information Technology GmbH © Atos Information Technology GmbH, 2004 - 2017
Smartcard Solutions
Otto-Hahn-Ring 6 CardOS is a registered trademark of
D-81739 Munich Atos Information Technology GmbH.

Germany

http://www.atos.net/cardos

-2- CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
Contents

1 .................. ABOUT THIS MANUAL................................................................................................................. 4

1.1 Target Group .................................................................................................................................. 4
1.2 Screenshots ................................................................................................................................... 4
1.3 Documentation ............................................................................................................................... 4
2 .................. OVERVIEW OF CARDOS API ...................................................................................................... 5
3 .................. PIN PAD READERS WITH SECURE PIN ENTRY ....................................................................... 6
4 .................. START CARDOS API.................................................................................................................... 7
5 .................. CHANGE PIN ................................................................................................................................. 9
6 .................. UNBLOCK PIN ............................................................................................................................ 12
7 .................. CHANGE PUK ............................................................................................................................. 15
8 .................. CHANGE SEC AUTH PIN ........................................................................................................... 18
9 .................. UNBLOCK SEC AUTH PIN ......................................................................................................... 22
10 ................ABOUT CARDOS API ................................................................................................................. 26
11 ................RESTART .................................................................................................................................... 27
12 ................EXIT ............................................................................................................................................. 28
13 ................CERTIFICATE PROPAGATION ................................................................................................. 29
13.1 Automatic Certificate Propagation ............................................................................................... 30
13.2 Manual Certificate Propagation .................................................................................................... 31
13.3 Interactive Certificate Propagation ............................................................................................... 32
14 ................TROUBLESHOOTING................................................................................................................. 35
15 ................GLOSSARY ................................................................................................................................. 37

CardOS API V5.4 for Windows - User Manual -3-

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
1 About this Manual

1 About this Manual

This document contains a detailed description about the functions of CardOS API.
This section comprises useful references using this user manual.

1.1 Target Group

It is assumed that the reader of this document is familiar with the technology of the smart cards and the
Public Key Infrastructure (PKI).

1.2 Screenshots
All examples and screenshots shown in this is manual were taken from a Microsoft Windows XP system.
If you are using a different operating system or a different version of CardOS API, the windows shown on
your screen may differ slightly.

Icons used in screenshots mean:

Note Indicates a successful operation or an important message for the user.

Question User interaction is required to complete the operation successfully.

Indicates an event that is not immediately significant, but might cause future
Warning
problems if you ignore it.

Error Indicates an unsuccessful operation.

1.3 Documentation
Refer to the following documentation for detailed information about CardOS API:

 CardOS API - Release Notes

This document describes system requirements for Windows. As well, it provides information about
supported applications, new features, and known issues.

 CardOS API - Installation Manual

This manual contains step-by-step guides to install, modify, repair, and remove of CardOS API V5.4
for Windows as well as detailed configuration information in a Windows environment.

 CardOS API - Viewer - User Manual

This document provides detailed information on how to use the add-on program called Viewer in a
Windows environment.

-4- CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 2 Overview of CardOS API

2 Overview of CardOS API

This manual describes on how to use CardOS API in your daily work in a Microsoft Windows environment.

CardOS API provides you with the following functionality:

 PIN Management
The PINs are protecting confidential information store in the card. You are able to change the User
PIN, the PUK, and the Sec Auth PIN as well as to unblock the User PIN and the Sec Auth PIN.

 Smart Card Access via PKCS#11 Cryptoki

Cryptographic applications (e.g. Firefox) can work with CardOS smart cards using the PKCS#11
Cryptographic Token Interface. This allows applications, which rely upon PKCS#11 Cryptoki, to use
certificates and keys stored on your CardOS smart card.

 Smart Card Access via Microsoft CAPI/CNG

Cryptographic applications can work with CardOS smart cards using the Microsoft Cryptographic API
(CAPI) or Cryptographic API Next Generation (CNG). Many Microsoft applications (e.g. Internet
Explorer, Outlook, etc.) and third party applications for Microsoft platforms use this interface for
cryptographic operations.

 Certificate Propagation for Microsoft CAPI/CNG

CardOS API automatically propagates all certificates stored on your CardOS smart card into the
Microsoft Certificate Store. Thus, all applications that search the Microsoft certificate store for your
personal certificates are able to use the certificates and keys stored on the inserted CardOS smart
card.

The user interface differs dependent on the application used:

 User PIN handling for applications using Microsoft CAPI (for example Outlook):
Whenever a cryptographic operation takes place the Microsoft Base CSP - or the CardOS API
Minidriver in case a secure PIN entry (SPE) device is used – has to authenticate the user to the
smart card. Whether successive operations require distinct PIN prompts depends on whether the
PIN can be cached by the Microsoft Base CSP or not. Microsoft Base CSP and CardOS API
Minidriver can be configured by the system administrator to use different modes for PIN caching.

 User PIN handling for applications using PKCS#11 Cryptoki (for example Firefox):
The application controls the User PIN prompting process completely. Therefore, if you initiate a
cryptographic operation, it depends on the used application whether you obtain a request for the
User PIN once or every time.

CardOS API V5.4 for Windows - User Manual -5-

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
3 PIN Pad Readers with Secure PIN Entry

3 PIN Pad Readers with Secure PIN Entry

In order to provide special protection for the PIN value you can use dedicated card reader devices for secure
PIN entry (SPE). These devices provide special physical and cryptographic protection to avoid
eavesdropping of the PIN while it is entered. The PIN is directly handed to the smart card inside the secure
PIN entry device and cannot be attacked by malicious software (Trojan) installed on the client.

Depending on the security requirements of your application scenario, you can use a smart card reader that is
compliant to one of the four classes explained below.

 Class 1 Reader
A class 1 reader simply connects the workstation with the smart card. Those readers do not provide
any functionality to comply with special security requirements.

 Class 2 Reader
A class 2 reader consists of a card reader with an own PIN pad. While a PIN is entered via the PIN
pad, it is not possible to eavesdrop that PIN.

 Class 3 Reader
A class 3 reader consists of a card reader with an own PIN pad and an integrated display for user
guidance. While a PIN is entered via the PIN pad, it is not possible to eavesdrop that PIN and it is
not possible to manipulate the user guidance.

 Class 4 Reader
In addition to the features of a class 3 reader this reader has a built-in security module that
authenticates the reader towards the application. This assures that only certified readers can
communicate with the corresponding application.

If your workstation is connected with a PIN pad reader (Class 2 or higher) CardOS API asks you to enter the
PIN via the PIN pad of the card reader.

Note
▪ Depending on the reader you use, the displayed windows and the respective workflow might
be different, but the number and type of the entries are the same.

▪ Depending on the reader you use, the PIN entries, exceeding the configured max. PIN
length, are treated as wrong input or are truncated to the maximum length without a warning
message.

▪ Whether available devices for secure PIN entry shall be used by CardOS API can be
configured by the system administrator.

-6- CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 4 Start CardOS API

4 Start CardOS API

CardOS API is started automatically while logging on to Windows. In case you need to start it manually you
can find it in the Start menu of your operating system:

Start  Programs  CardOS API  CardOS API

The CardOS API operates in the background. When the CardOS API is running an icon is displayed at the
far right of the taskbar of Windows. The area is also known as the system tray.
This icon displays the status of the card that has been inserted last.

If you hold the mouse pointer over the CardOS API icon the tool tip
with version-info and – if applicable – an error message and an
error-code are displayed.

Figure 1

Following CardOS API icons may appear in the system tray:

A gray icon indicates that CardOS API is waiting for a smart card. It remains gray as long as
no smart card has been inserted into the smart card reader.
Figure 2

An hourglass indicates that a smart card has been inserted and CardOS API is propagating
certificates from the smart card to the Microsoft certificate store of your computer. Refer to
the section 13 Certificate Propagation on page 29 for more information on that topic.
Figure 3

A yellow icon is highlighted as soon as CardOS API has finished the certificate propagation
process. The propagated certificates and the key material, that remains always on the smart
card, can now be used by any application that uses the Microsoft CSP or the PKCS#11
interface for the computation of digital signatures and for data encryption respectively
Figure 4 decryption.

A question mark indicates that CardOS API has detected a smart card in the card reader,
but the CardOS API does not support the inserted card. Please refer to the section 14
Troubleshooting on page 35 for further details if this icon is displayed.
Figure 5

The white cross on a red ground indicates that a critical error has occurred. Please refer to
the section 14 Troubleshooting on page 35 for more information on that topic.

Figure 6

CardOS API V5.4 for Windows - User Manual -7-

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
4 Start CardOS API

Warning
If another Cryptographic Service Provider (CSP) is installed on your computer a window
analog to Figure 7 might be displayed after CardOS API has been started. In this case you
should contact your system administrator for further assistance.

Figure 7

-8- CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 5 Change PIN

5 Change PIN
If the PIN of your smart card has been compromised, it is advisable to change the PIN immediately. Another
reason for changing the PIN could be, that the security policy of your company obliges you to change the
PIN at fixed intervals.

Step 1  Click the CardOS API icon in the system tray and select: Change PIN… (See Figure 8).

Figure 8

 Alternatively select: Start  Programs  CardOS API  Change PIN

Step 2 In case several card readers with inserted smart cards each are connected to the computer, then
CardOS API prompts you to choose the smart card you want to work with (compare with Figure
9).

 Select the smart card you want to work with.

Note
Every listed entry in Figure 9 consists of the system name of the card reader
and the card label of the inserted smart card. Both items are separated by a
colon.

Figure 9

 Click OK to acknowledge your selection.

CardOS API V5.4 for Windows - User Manual -9-

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
5 Change PIN

Step 3 The Changing User PIN dialog box is displayed (compare with Figure 10).
The given information about the card label (displayed as Card) and the connected card reader
(displayed as Reader) assures you which smart card you are using.

Figure 10

Warning
For security reasons the number of consecutive incorrect PIN entries is limited.
The maximum number 1 of incorrect entries is fixed during smart card
initialization. After the maximum number of incorrect entries is reached, your PIN
is blocked.

 Enter your current PIN.

 Enter your new PIN.

 Re-enter your new PIN a second time for verification purposes.

 Click OK if you have completed your entries.

1
The default error counter is set to 3 for the PIN and 10 for the PUK and Sec. Auth. PINs. The default lengths are 4 to 16 characters
each.

- 10 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 5 Change PIN

Step 4 Depending on your entries one of the following messages is displayed:

Icon Displayed message What you can do…

The PIN has been successfully changed.

The new PINs you entered do not match.

Please try again.

Change PIN failed.

Invalid new PIN length

PIN is incorrect.

Depending on your local security policy

it might be possible to unblock the PIN.
PIN blocked. If it is not possible to unblock the PIN
contact your system administrator for
further assistance.

CardOS API V5.4 for Windows - User Manual - 11 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
6 Unblock PIN

6 Unblock PIN
In case the PIN is blocked due to too many consecutive incorrect PIN entries (3 times by default) you must
unblock your PIN using the PUK.

Step 1  Click the CardOS API icon in the system tray and select: Unblock PIN… (See Figure 11).

Figure 11
 Alternatively select: Start  Programs  CardOS API  Unblock PIN

Step 2 In case several card readers with inserted smart cards each are connected to the computer, then
CardOS API prompts you to choose the smart card you want to work with (compare with Figure
12).

 Select the smart card you want to work with.

Note
Every listed entry in Figure 12 consists of the system name of the card reader
and the card label of the inserted smart card. Both items are separated by a
colon.

Figure 12

 Click OK to complete your selection.

- 12 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 6 Unblock PIN

Step 3 The dialog box titled Unblock User PIN is displayed (compare with Figure 10).
The given information about the card label (displayed as Card) and the connected card reader
(displayed as Reader) assures you which smart card you are using.

Figure 13

Warning
For security reasons the number of consecutive incorrect PUK entries is limited.
The maximum number 2 of incorrect entries is fixed during card initialization. If
the maximum number of incorrect entries is reached, your smart card is
irreversible blocked.

 Enter your current PUK.

 Enter your new PIN.

 Re-enter your new PIN a second time for verification purposes.

 Click OK if you have completed your entries.

2
The default error counter is set to 3 for the PIN and 10 for the PUK and Sec. Auth. PIN. The default lengths are 4 to 16 characters
each.

CardOS API V5.4 for Windows - User Manual - 13 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
6 Unblock PIN

Step 4 Depending of your entries one of the following messages is displayed:

Icon Displayed message What you can do…

The PIN has been successfully unblocked.

The new PINs you entered do not match.

Please try again.

Unblock PIN failed.

Invalid new PIN length.

Unblock PIN failed.

PUK is incorrect.

The maximum number of consecutive

incorrect PUK entries has been
Unblock PIN failed.
reached, the card is irreversible
PUK blocked.
blocked. Contact your system
administrator for further assistance.

- 14 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 7 Change PUK

7 Change PUK
If the PUK of your smart card has been compromised, it is advisable to change the PUK immediately.

Step 1  Follow the menu items of your operating system:

Start  Programs  CardOS API  Change PUK

Step 2 In case several card readers with inserted smart cards each are connected to the computer, then
CardOS API prompts you to choose the smart card you want to work with (compare with Figure
14).

 Select the smart card you want to work with.

Note
Every listed entry in Figure 14 consists of the system name of the card reader
and the card label of the inserted smart card. Both items are separated by a
colon.

Figure 14

 Then click OK to complete your selection.

CardOS API V5.4 for Windows - User Manual - 15 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
7 Change PUK

Step 3 The dialog box titled Changing PUK is displayed (compare with Figure 15).
The given information about the card label (displayed as Card) and the connected card reader
(displayed as Reader) assures you which smart card you are using.

Figure 15

Warning
For security reasons the number of consecutive incorrect PUK entries is limited.
The maximum number 3 of incorrect entries is fixed during card initialization. If
the maximum number of incorrect entries is reached, your smart card is
irreversible blocked.

 Enter your current PUK.

 Enter your new PUK.

 Re-enter your new PUK a second time for verification purposes.

 Click OK to complete your entries.

3
The default error counter is set to 3 for the PIN and 10 for the PUK and Sec. Auth. PIN. The default lengths are 4 to 16 characters
each.

- 16 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 7 Change PUK

Step 4 Depending of you entries one of the following messages is displayed:

Icon Displayed message What you can do…

The PUK has been successfully changed.

The new PUKs you entered do not match.

Please try again.

Change PUK failed.

Invalid new PUK length.

Change PUK failed.

The entered PUK is wrong.

The maximum number of

consecutive incorrect PUK-entries
Change PUK failed. has been reached, the card is
PUK blocked. irreversible blocked. Contact your
system administrator for further
assistance.

CardOS API V5.4 for Windows - User Manual - 17 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
8 Change Sec Auth PIN

8 Change Sec Auth PIN

If the Secondary Authentication PIN (Sec Auth PIN) of your smart card has been compromised, it is
advisable to change the Sec Auth PIN immediately.

Step 1  Follow the menu items of your operating system:

Start  Programs  CardOS API  Change Sec Auth PIN

Step 2 In case several card readers with inserted smart cards each are connected to the computer, then
CardOS API prompts you to choose the smart card you want to work with (compare with Figure
16).

 Select the smart card you want to work with.

Note
Every listed entry in Figure 16 consists of the system name of the card reader
and the card label of the inserted smart card. Both items are separated by a
colon.

Figure 16

 Then click OK to continue.

Step 3 In case the selected card contains multiple secondary authentication PINs CardOS API prompts
you to choose the PIN you want to change (compare with Figure 17). In case the card contains
only a single authentication PIN proceed with Step 4.

 Select the PIN you want to change.

- 18 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 8 Change Sec Auth PIN

Figure 17
 Then click OK to continue.

CardOS API V5.4 for Windows - User Manual - 19 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
8 Change Sec Auth PIN

Step 4 The dialog box titled Changing Secondary Auth PIN is displayed (compare with Figure 18).
The given information about the card label (displayed as Card) and the connected card reader
(displayed as Reader) assures you which smart card you are using.

Figure 18

Warning
For security reasons the number of consecutive incorrect Secondary Auth PIN
entries is limited. The maximum number 4 of incorrect entries is fixed during card
initialization. If the maximum number of incorrect entries is reached, this
Secondary Auth PIN is blocked an can no longer be used.

 Enter your current Secondary Auth PIN.

 Enter your new Secondary Auth PIN.

 Re-enter your new Secondary Auth PIN a second time for verification purposes.

 Click OK to complete your entries.

4
The default error counter is set to 3 for the PIN and 10 for the PUK and Sec. Auth. PIN. The default lengths are 4 to 16 characters
each.

- 20 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 8 Change Sec Auth PIN

Step 5 Depending of your entries one of the following messages is displayed:

Icon Displayed message What you can do…

The Secondary Auth PIN has been successfully
changed.

The new PINs you entered do not match.

Please try again.

Change Secondary Auth PIN failed.

Invalid new PIN length.

Change Secondary Auth PIN failed.

PIN is incorrect.

Depending on your local security

policy it might be possible to unblock
Change Secondary Auth PIN failed. the Secondary Auth PIN. If it is not
PIN blocked. possible to unblock the Secondary
Auth PIN contact your system
administrator for further assistance.

CardOS API V5.4 for Windows - User Manual - 21 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
9 Unblock Sec Auth PIN

9 Unblock Sec Auth PIN

In case the Sec Auth PIN is blocked due to too many consecutive incorrect PIN entries (3 times by default)
you must unblock your Sec Auth PIN using the PUK.

Step 1  Follow the menu items of your operating system:

Start  Programs  CardOS API  Unblock Sec Auth PIN

Step 2 In case several card readers with inserted smart cards each are connected to the computer, then
CardOS API prompts you to choose the smart card you want to work with (compare with Figure
19).

 Select the smart card you want to work with.

Note
Every listed entry in Figure 19 consists of the system name of the card reader
and the card label of the inserted smart card. Both items are separated by a
colon.

Figure 19

 Then click OK to continue.

- 22 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 9 Unblock Sec Auth PIN

Step 3 In case the selected card contains multiple secondary authentication PINs CardOS API prompts
you to choose the PIN want to unblock (compare with Figure 21). In case the card contains only a
single authentication PIN proceed with Step 4.

 Select the PIN you want to unblock.

Figure 20
 Then click OK to continue.

CardOS API V5.4 for Windows - User Manual - 23 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
9 Unblock Sec Auth PIN

Step 4 The Unblock Secondary Auth PIN dialog box is displayed (compare with Figure 21).
The given information about the card label (displayed as Card) and the connected card reader
(displayed as Reader) assures you which smart card you are using.

Figure 21

Warning
For security reasons the number of consecutive incorrect PUK entries is
limited. The maximum number 5 of incorrect entries is fixed during card
initialization. If the maximum number of incorrect entries is reached, your PUK
is irreversible blocked and can no longer be used.

 Enter your current PUK.

 Enter your new Secondary Auth PIN.

 Re-enter your new Secondary Auth PIN a second time for verification purposes.

 Click OK to complete your entries.

5
The default error counter is set to 3 for the PIN and 10 for the PUK and Sec. Auth. PIN. The default lengths are 4 to 16 characters
each.

- 24 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 9 Unblock Sec Auth PIN

Step 5 Dependent of your entries one of the following messages is displayed:

Icon Displayed message What you can do…

The Secondary Auth PIN has been successfully
unblocked.

The new PINs you entered do not match.

Please try again.

Unblock Secondary Auth PIN failed.

Invalid new PIN length.

Unblock Secondary Auth PIN failed.

PUK incorrect.

The maximum number of

consecutive incorrect PUK entries
Unblock Secondary Auth PIN failed. has been reached, the card is
PUK blocked. irreversible blocked. Contact your
system administrator for further
assistance.

CardOS API V5.4 for Windows - User Manual - 25 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
10 About CardOS API

10 About CardOS API

The About CardOS API function informs you about files, versions, copyrights, and trademarks used in
CardOS API.

Step 1  Click the CardOS API icon in system tray and select: About CardOS API

Figure 22

Step 2 Figure 23 displays the versions of CardOS API and corresponding files. This information may be
necessary for a trouble report or a change request.

Figure 23

 Press the OK button to close the window.

- 26 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 11 Restart

11 Restart
In some cases it is necessary to restart CardOS API, e.g. after you installed a new smart card reader on your
system.

 Click the CardOS API icon in the system tray and select the Restart option from the context menu as
shown in Figure 24.

Figure 24

CardOS API V5.4 for Windows - User Manual - 27 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
12 Exit

12 Exit
 To exit CardOS API click the CardOS API icon in the system tray and select the Exit function from the
context menu.

Warning
If you exit CardOS API, the personal certificates that were originally propagated by inserting
the smart card, will be removed from the certificate store 6. The applications cannot access
the propagated certificates and the key material on the smart card anymore.

Figure 25

Refer to section 4 Start CardOS API on page 7 for more information to start CardOS API again.

6
Unless configured different. Please refer to CardOS API - Installation Manual for more details.

- 28 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 13 Certificate Propagation

13 Certificate Propagation
The propagation of certificates to the Microsoft certstore allows applications, which support the Microsoft
CSP architecture, to use the certificates and key material that are stored on the smart card.

You can access the content of the Microsoft certificate store via Internet Options…  Tab: Content 
Button: Certificates….

CardOS API offers three different ways to propagate the certificates located on a smart card:

 Automatic Certificate Propagation

If a smart card is inserted all certificates are automatically copied from the smart card to the
corresponding certificate stores of the computer. The personal certificates are deleted as soon as the
7
smart card is removed from the reader .

 Manual Certificate Propagation

Only the personal certificates are copied to the certificate stores of the computer. The personal
certificates remain in the certificate store of the computer if the smart card is removed.

 Interactive Certificate Propagation

The user is able to select the certificates located on the smart card and as well as the certificate
stores of the computer. The personal certificates remain in the certificate store of the computer if the
smart card is removed.

Refer to the following sections for a detailed description of the different certificate propagations.

7
Unless configured different by the system administrator. Please refer to CardOS API - Installation Manual for more details.

CardOS API V5.4 for Windows - User Manual - 29 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
13 Certificate Propagation

13.1 Automatic Certificate Propagation

Use the automatic certificate propagation to copy all certificates from the CardOS smart card to the
appropriate Microsoft certificate store as soon as CardOS API recognizes a smart card inserted in the
reader.

Automatic certificate propagation is active as long as CardOS API is running.

Depending on the certificate type, the certificates are automatically propagated to different certificate stores.

 Root Certificates
Root Certificates are self-signed certificates of the certificate issuer (CA). As soon as you insert a
smart card that includes a root certificate, the computer displays a security warning message
prompting you whether you want to install the root certificate. Read the shown message carefully.
If you click Yes, the root certificate is copied to the following certificate store:
Console Root\Certificates - Current User\Certificates - Current User\Trusted Root Certification
Authorities\Certificates
These certificates remain in the certificate store if the smart card is removed.

 CA Certificates
If the CA bit of a certificate is set, it is called as a CA certificate. If a smart card is inserted the CA
certificates are automatically copied to the following certificate store:
Console Root\Certificates - Current User\Certificates - Current User\Intermediate Certification
Authorities\ Certificates
These certificates remain in the certificate store if the smart card is removed.

 Personal Certificates
All other certificates on the smart card are treated as personal certificates. These certificates are
automatically copied to the following certificate store:
Console Root\Certificates - Current User\Certificates - Current User\Personal\Certificates
8
Removing the smart card deletes all personal certificates .

8
Unless configured different by the system administrator. Please refer to CardOS API - Installation Manual for more details.

- 30 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 13 Certificate Propagation

13.2 Manual Certificate Propagation

The manual certificate propagation is only used in exceptional cases, e.g. if CardOS API should not run in
the background to improve system performance.
The manual certificate propagation copies only the personal certificates from the inserted smart card to the
following Microsoft certificate store:
Console Root\Certificates - Current User\Certificates - Current User\Personal\Certificates

In contrast to the automatic certificate propagation the personal certificates are not deleted if the smart card
is removed from the reader. If necessary remove them manually, e.g. by using the menu of the Internet
Explorer  Tools  Internet Options  Content tab  Certificates button  select one or several
certificates and then click the Remove button.

Note
Since the automatic certificate propagation (13.1) cannot be running at the same time CardOS
API needs to be stopped (see section 12) before you can use.

Step 1  Click Start, and then select Run.

CardOS API V5.4 for Windows - User Manual - 31 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
13 Certificate Propagation

Step 2 The Run dialog box is displayed.

 Click Browse… to select the cardoscp.exe program of the CardOS API installation
Default: C:\Program Files\CardOS API\bin\cardoscp.exe

 Append the /m option to the command line as shown in Figure 26.

Note
In case you enter the path manually you need to quote the path and the
executable file name if the installation path contains any blank characters.
Example: "C:\Program Files\CardOS API\bin\cardoscp.exe" /m
If you start cardoscp.exe without any parameter the automatic certificate
propagation is started.

Figure 26

 Press OK to start the Manual Certificate Propagation.

13.3 Interactive Certificate Propagation

The interactive certificate propagation allows you to interactively select the certificate stores where your
certificates are copied. The copied certificates are not deleted if the smart card is removed from the card
reader.

Note
CardOS API automatic certificate propagation (13.1) must be stopped before the interactive
certificate propagation can be started.

Step 1  Click Start, and then select Run.

- 32 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 13 Certificate Propagation

Step 2 The Run dialog box is displayed.

 Click Browse… to select the cardoscp.exe program of the CardOS API installation
Default: C:\Program Files\CardOS API\bin\cardoscp.exe

 Append the /m and /i option to the command line as shown in Figure 27.

Note
In case you enter the path manually you need to quote the path and the
executable file name if the installation path contains any blank characters.
Example: "C:\Program Files\CardOS API\bin\cardoscp.exe" /m /i
If you start cardoscp.exe without any parameter the automatic certificate
propagation is started.

Figure 27

 Click OK to continue.

CardOS API V5.4 for Windows - User Manual - 33 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
13 Certificate Propagation

Step 3 For each personal certificate stored on your smart card, the Microsoft certificate import dialog box
pops up (compare with Figure 28).

Figure 28

 If you want to install the currently displayed certificate, then press the Install Certificate
button. The Microsoft Certificate Import Wizard guides you through the remaining steps
needed to install the certificate, whereas you can select the certificate store.

 Just press OK to proceed to the next available certificate without installing the currently
displayed certificate.

- 34 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 14 Troubleshooting

14 Troubleshooting
Check the following scenarios before you contact your system administrator.

CardOS API cannot not recognize the inserted smart card:

1. The operating system of your smart card is not supported. Please refer to the CardOS
API - Release Notes for a list of supported cards.
Figure 29
2. The smart cards operating system is supported, but the CardOS API does not
recognize the smart card’s file system.

CardOS API has detected a critical error. In this case the error code is displayed in the
icons tool tip. Possible reasons may be:
Figure 30
1. Assure that your smart card reader and corresponding driver have been installed
properly on your system. Most card readers come along with a small program that
allows retrieving some basic information from the card (e.g. the answer to reset
(ATR)). This may help you to ensure that everything has been properly installed.

2. Make sure that the Microsoft smart card subsystem service is started.
Windows Task Manager  Processes  scardsvr.exe

3. Restart CardOS API.

If the error condition persists contact your system administrator.

Application XYZ does not use the smart card keys and certificates

1. In case you are using a Microsoft CSP application make sure that your certificates are
propagated to the Microsoft certificate stores (refer to the section 13 Certificate
Propagation on page 29 for more information).

2. Ensure that the respective application runs using the certificates and keys stored in a
PSE. If the function runs properly try again using your smart card.

Smart Card Logon fails with ‘0x80090006 – Invalid Signature.’ or ‘0x8009001D – Provider
DLL failed to initialize correctly.’ (Event log).
Enrollment on Behalf does not recognize the smart card and prompts for the user’s
smart card again and again.

Make sure that CardOS API has been installed properly. All the folders below the registry entry
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards must
contain an ATR parameter set to a value of the CardOS card you are using.
The Crypto Provider parameter must be set to Microsoft Base Smart Card Crypto Provider and
the parameter 80000001 must be set to cardoscm.dll on x86 systems or cardoscm64.dll on
x64 systems.

CardOS API V5.4 for Windows - User Manual - 35 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
14 Troubleshooting

Internet Explorer: “The page cannot be displayed”

1. Check whether the personal certificate is stored in the certificate store of Microsoft. For
more information see section 13 Certificate Propagation on page 29.

2. Restart the Internet Explorer if the personal certificate is available.

- 36 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
 15 Glossary

15 Glossary
The following terms and abbreviations are used in the documents of the CardOS API software distribution:

API Application Programming Interface (API) is an interface that can be used by programs
either to control hardware devices or functions of the operating system.
Base CSP Smart Card Base Cryptographic Service Provider
CA A certification authority, or CA, issues certificates and binds the identity of it to a person or
computer.
CAPI Microsoft Cryptographic API; also called Crypto API
CardOS Operating System for smart cards being developed by Atos IT Solutions and Services.
Certificate A digital certificate is a file that includes the name of the certificate holder, dates of
validity, a Public Key, and the name of the certificate issuer.
CL Contactless; Part of the version identifier of CardOS contactless smart cards.
Cryptoki  PKCS#11
CSP Cryptographic Service Provider (CSP). A CSP is responsible for the creation of keys and
their use for different tasks. Several different CSPs can be installed on one PC, which
differ for example in key length, algorithms for encryption, or the inclusion of smart cards.
Data Object A Data Object is a file that can be imported or exported from the smart card.
DF A DF (dedicated file) is a directory in the file system of a Smart Card.
Digital A Digital Signature Application consists of appropriate file-structures and objects on a
Signature smart card, that enables the computation of digital signatures.
Application
DIN NI 17-4 Specification of the interface to smart cards with Digital Signature Application compliant to
SigG and SigV.
FRN Fast Random Number
ICC Integrated Circuit Card. ISO compliant description for a Smart Card.
ICCSP An Integrated Circuit Card Service Provider (ICCSP) is responsible for the allocation of
the functionality of a smart card, independent of the smart (ICC) card operating system.
MF A MF (master file) is the root directory in the file system of a smart card.
Minidriver Minidriver presents a consistent interface to smart cards to the Microsoft Smart Card
Base Cryptographic Service Provider.
OID An object identifier is a registered number sequence to uniquely identify an object type.
PC/SC Interoperability Specification for ICCs and Personal Computer Systems.
PIN The Personal Identification Number (PIN) is used to authenticate you as the owner of the
card. Once a correct PIN is entered, the error counter is reset.
PIN pad Especially on security relevant applications (e.g. money transactions) the entry of a PIN is
subject to regulations for keyboards. Those specific keyboards are called PIN pad. They
are mechanical and cryptographic protected, so the PIN can’t be eavesdropped during
entering. Smart card readers with a built-in PIN pad are called PIN pad readers.
PKCS#11 The Public-Key Cryptography Standards (PKCS) are specifications that were developed
by RSA Security in conjunction with system developers worldwide. PKCS#11 defines a
technology independent programming interface for cryptographic devices such as smart
cards.

CardOS API V5.4 for Windows - User Manual - 37 -

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved
15 Glossary

PSE Personal Security Environment - Security relevant information is stored in a PSE. Among
other things it contains the certificate and the private key of the card holder and it might
contain one or several CA-certificates. The PSE can take the form of an encrypted file or
a smart card and is protected by a password.
PUK The Personal Unblocking Key (PUK), also known as a Super-PIN or SO PIN (see
PKCS#11 standard), is used to change or to unblock the PIN.
QES Qualified Electronic Signature
RC Release Candidate
Secondary The intent of secondary authentication is to provide a means for a smart card to produce
Authentication digital signatures for non-repudiation with reasonable certainty that only the authorized
PIN user could have produced that signature. A Secondary Authentication PIN must be
presented each time a particular signing key is used to perform its digital signature
operation. Depending on the security requirements of the application a Secondary
Authentication PIN has to be entered via e.g. a PIN Pad reader that bypasses the
workstation.
SigG Germany's Electronic Signature Act, which went into effect in May 2001, defines the
framework conditions for electronic signatures.
SigV Germany's Signature Ordinance. Supplement to the SigG with regard to the procedures of
the certification authorities and products to be used for certificate issuance and signature
creation; effective from November 2001.
SO PIN Security Officer PIN. This definition is used in the PKCS#11 standard  PUK.
SPE Secure PIN Entry (SPE) can be achieved by using of a PIN pad reader.
Super-PIN  PUK
TCK Checksum byte of a smart card ATR according to ISO7816-3:1997(E); Section 6.2.
Token A token is an object containing the security information for a cryptographic session. A
smart card can be such a cryptographic token.
Transport PIN The Transport PIN is usually provided by a Trust Center over a trustworthy channel (e.g.
a PIN letter). Before using a Digital Signature Application the owner of the smart card has
to initialize a personal Digital Signature PIN to the card. For this initialization a so-called
Transport PIN has to be entered to assign a personal Digital Signature PIN and Digital
Signature PUK to the card.
VBS Visual Basic Script
WinSCard API Windows Smart Card client API

- 38 - CardOS API V5.4 for Windows - User Manual

© Atos Information Technology GmbH, 2004 - 2017 All Rights Reserved