CardOS API - Release Notes
CardOS API - Release Notes
CardOS API - Release Notes
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 Atos Information
D-81739 Munich Technology GmbH sales representative for the most current
Germany information.
Germany
http://www.atos.net/cardos
Contents
1 ..................INTRODUCTION ............................................................................................................................ 4
1.1 Target Group .................................................................................................................................. 4
1.2 Third-Party Copyrights ................................................................................................................... 4
2 ..................SUBJECT OF THIS RELEASE ..................................................................................................... 5
2.1 Version: Release Version ............................................................................................................... 5
2.2 Licensed Software .......................................................................................................................... 5
2.3 Supported Cryptographic Interfaces .............................................................................................. 5
2.4 Card File System ............................................................................................................................ 7
2.5 Released Objects .........................................................................................................................10
3 ..................SYSTEM REQUIREMENTS ........................................................................................................13
3.1 Supported Smart Cards ...............................................................................................................13
3.2 Microsoft Windows .......................................................................................................................14
4 ..................CHANGES COMPARED TO PREVIOUS RELEASES ...............................................................16
4.1 New Features ...............................................................................................................................16
4.2 Fixed Bugs and Implemented Change Requests ........................................................................18
4.3 Migration from Previously Released Versions .............................................................................21
5 ..................ENSURING INTEROPERABILITY BETWEEN PKCS#11 AND MICROSOFT CSP ..................22
5.1 PKCS#11 Object Identification and Microsoft CSP Container Names ........................................22
5.2 RSA Public Exponent Length .......................................................................................................22
5.3 Unblock User PIN .........................................................................................................................22
5.4 PIN/PUK Values ...........................................................................................................................23
6 ..................SETUP INFORMATION FOR MICROSOFT WINDOWS ............................................................24
6.1 Shortcuts Created by CardOS API Setup ....................................................................................24
6.2 Objects Copied by CardOS API Setup ........................................................................................25
6.3 Registry Settings Required by CardOS API .................................................................................28
6.4 Device Driver Information File for Windows 7, Windows 8 and Windows 10 ..............................31
6.5 Software Publisher Certificates ....................................................................................................31
7 ..................SECURE KEY INJECTION ..........................................................................................................32
7.1 Establishing a Trust Anchor .........................................................................................................32
7.2 Importing an User’s RSA Key ......................................................................................................34
8 ..................SECURITY CONSIDERATIONS .................................................................................................37
9 ..................KNOWN ISSUES .........................................................................................................................38
10 ................REPORTING BUGS ....................................................................................................................41
11 ................GLOSSARY .................................................................................................................................42
1 Introduction
This document provides system requirements, as well as known issues, for installation and operation of
CardOS API for Microsoft Windows. It is recommended to review this information before installing.
CardOS API uses decompression routines from the lab project (http://www.gzip.org/zlib). The zlib software is
copyright by Jean-loup Gailly and Mark Adler.
CardOS API uses GNU Multiple Precision Arithmetic Library for bignum operations (http://gmplib.org/). The
GMP library is copyright by Free Software Foundation, Inc., and licensed under LGPL v2.1 and v3.0
CardOS API uses the GMP port for Microsoft Windows maintained by Brian Gladman
(http://gladman.plushost.co.uk/oldsite/computing/gmp4win.php).
Please refer to the Open Source Software information document distributed on the product CD for more
information on Open Source Software components used by CardOS API.
Compliance to the Microsoft Minidriver specification has been tested using "Microsoft Smart Card Minidriver
Certification Kit -- 10.0.14393.4". This Microsoft test kit is included in Microsoft Hardware Lab Kit for
Windows 10. For further information refer to "Windows Smart Card Minidriver Specification"; Version 7.07;
February 25, 2016.
CardOS API V5.4 for Windows supports all mandatory features of the Microsoft Smart Card Minidriver V7
specification. Starting with CardOS API V5.4 elliptic curves cryptography for ECDSA and ECDH keys is
supported on CardOS V5.x smart cards, initialized with the CardOS API V5.4 PKCS#15 file structure.
Concerning the Windows Smart Card Infrastructure as a whole the "Windows Vista Smart Card
Infrastructure"; Shivaram H. Mysore; Microsoft Corporation; August 2007 (https://msdn.microsoft.com/en-
us/library/bb905527.aspx) is a recommended reading.
The CardOS API implementation covers all mechanisms, algorithms, and functions as defined in section 5,
6, and 8 of the “PKCS #11: Conformance Profile Specification” (https://www.emc.com/emc-plus/rsa-
labs/standards-initiatives/pkcs-11-cryptographic-token-interface-standard.htm).
CardOS API V5.4 for Windows supports the following cryptographic mechanisms:
On Card / Software
Mechanism Mechanism Strength
Computation
3
CKM_RSA_PKCS_KEY_PAIR_GEN 512 … 4096bit on card
3
CKM_RSA_PKCS 512 … 4096bit on card
3
CKM_RSA_X_509 512 … 4096bit on card
3
CKM_MD5_RSA_PKCS 512 … 4096bit on card signing, software digest
3
CKM_SHA1_RSA_PKCS 512 … 4096bit on card signing, software digest
3
CKM_SHA224_RSA_PKCS 512 … 4096bit on card signing, software digest
3
CKM_SHA256_RSA_PKCS 512 … 4096bit on card signing, software digest
3
CKM_SHA384_RSA_PKCS 512 … 4096bit on card signing, software digest
3
CKM_SHA512_RSA_PKCS 512 … 4096bit on card signing, software digest
3
CKM_RSA_PKCS_PSS 512 … 4096bit on card
3
CKM_SHA1_RSA_PKCS_PSS 512 … 4096bit on card signing, software digest
3
CKM_SHA224_RSA_PKCS_PSS 512 … 4096bit on card signing, software digest
3
CKM_SHA256_RSA_PKCS_PSS 512 … 4096bit on card signing, software digest
3
CKM_SHA384_RSA_PKCS_PSS 1024 … 4096bit on card signing, software digest
3
CKM_SHA512_RSA_PKCS_PSS 1024 … 4096bit on card signing, software digest
CKM_MD5 128bit software
CKM_SHA1 160bit software
CKM_SHA224 224bit software
1
CKA_SUBJECT and CKA_ISSUER are read-only
2
CKA_SUBJECT is read-only
3
1024bit maximum for CardOS/M4.01a; 2048bit maximum for CardOS V4.3B, V4.2 B, DI V4.2B, V4.2C, DI V4.2C, V4.4
On Card / Software
Mechanism Mechanism Strength
Computation
CKM_SHA256 256bit software
CKM_SHA384 384bit software
CKM_SHA512 512bit software
CKM_DES_KEY_GEN 56bit software
CKM_DES_CBC 56bit software
CKM_DES3_KEY_GEN 168bit software
CKM_DES3_CBC 168bit software
CKM_RC2_KEY_GEN 40 … 128bit software
CKM_RC2_CBC 40 … 128bit software
CKM_RC4_KEY_GEN 8 … 2048bit software
CKM_RC4 8 … 2048bit software
CKM_AES_CBC software
CKM_EC_KEY_PAIR_GEN brainpoolP224r1 on card
CKM_ECDSA_KEY_PAIR_GEN brainpoolP256r1 on card
CKM_ECDSA brainpoolP320r1 on card signing
CKM_ECDSA_SHA1 brainpoolP384r1 on card signing, software digest
CKM_ECDH1_DERIVE brainpoolP512r1 on card
secp256r1,
secp384r1,
secp521r1
CardOS API does not support functions to get and set the operation state of cryptographic functions
(C_GetOperationState, C_SetOperationState). Dual-function cryptographic functions
(C_DigestEncryptUpdate, C_DecryptDigestUpdate, C_SignEncryptUpdate, and
C_DecryptVerifyUpdate) are not supported and need to be split up into separate calls.
C_GetFunctionStatus and C_CancelFunction have been deprecated and will return
CKR_FUNCTION_NOT_PARALLEL.
The file system is designed to allow the storage of 7 to 10 key pairs including the respective X.509
certificates. The actual amount of objects depends on object size (certificate size, key length) as well as the
size of the corresponding object meta-data (like object names, object identifiers, etc.). The amount of meta-
data per object is limited to 240 bytes. It is possible to customize the default memory allocation to customer
specific needs.
Starting from HiPath SIcurity Card API 3.1 this Issuer PIN is initialized with the value passed for the SO PIN
(also known as PUK) to C_InitToken(). This function is also used by Card Viewer to initialize cards.
The knowledge of the Issuer PIN is important in case you want to change the file system at a later stage.
In case the card is initialized using CardOS API V5.0 Windows Microsoft Minidriver interface the Issuer PIN
is blocked during initialization and cannot be used to modify the card after initialization.
4
To avoid confusions with the so-called Admin Key of the Microsoft Smart Card CSP, the Admin PIN used in earlier manuals has been
renamed to Issuer PIN.
In case C_InitToken() is called to initialize a card using a secure PIN entry (SPE) device the new SO PIN
(PUK) assigned to the token must have a length of 10 characters.
It is possible to set the SO-PIN to a different value than the Issuer PIN by calling C_SetPIN() to assign a
new value to the SO-PIN. This function is e.g. accessible from the Card Viewer function Change PUK. This
does not affect the value of the Issuer PIN, which remains to the value originally assigned by
C_InitToken().
2.4.1.3 Windows Base CSP Admin Key and PKCS#11 SO-PIN (PUK)
Windows Base CSP introduces an Admin Key which takes the role of the PKCS#11 SO PIN (also known as
PUK) for cards used with Microsoft Base CSP.
Since cards can either be initialized using the Microsoft Smart Card Base Cryptographic Provider or
PKCS#11 it is required to set the authentication object which is not recognized by the respective interface to
a defined value:
For cards initialized with the Windows Base CSP (e.g. using Microsoft Certificate Lifecycle Manager) the
SO PIN is not initialized and cannot be used.
For cards initialized with PKCS#11 C_InitToken() the Windows Base CSP Admin Key is initialized to
a value derived from the SO PIN passed to C_InitToken(). CardOS API uses the password based
5
encryption scheme described in PKCS#12 appendix B .
Example:
SO-PIN: "1234567890"
Admin-Key: 94b5e0f4 16bf3d98 a45e402f d55e626b 94ae3d94 3d75e615
CardOS API offers limited software based session PIN support for all other CardOS smart card versions and
cards initialized with CardOS API prior to CardOS API V5.1.
This may result in different behavior depending on the type of session PIN used esp. in case secure PIN
entry devices are used. E.g. the frequency of user prompts for the PIN may vary.
Whether and to what extent a session PIN is cached or shared between multiple applications depends on
the respective application. CardOS API V5.4 supports session PIN handling as described in Microsoft
Minidriver V7.07 date February 25, 2016 specification for CardOS v5.x cards initialized with CardOS API
V5.4.
The values of these PINs shall be set to values different from their default value before their first use.
Currently CardOS API supports usage of session PIN for extra PINs only in contact based mode.
Note that it is in the customer’s responsibility to ensure that his environment meets the requirements
stipulated in the confirmation document whenever CardOS is used to create a qualified electronic signature
(“Sichere Signaturerstellungseinheiten CardOS V5.0 with Application for QES, V1.0”;
BSI.02136.TE.07.2013”).
In order to allow CardOS API to use the files and objects located within application QES the required
PKCS#15 reference structures need to be setup in the CardOS API PKCS#15 reference system.
The actual initialization of the digital signature RSA private key object may limit the choice of cryptographic
schemes eligible to an application. An application requesting a scheme that has not been envisaged will not
be able to use this key. E.g. in case the digital signature RSA private key object has been setup to require
PKCS#1-BT1 padding using a SHA256 digest info an application will not be able to use this key with
PKCS#1 PSS SHA256.
6
The initialization script for CardOS DI V4.2 C has been optimized for stability of operation in contact less communication scenarios. For
maximum performance in contact based scenarios CardOS DI V4.2 C needs to be initialized with a customized initialization script.
The CardOS API distribution provides a Secure PIN Entry (SPE) compliant setup routine.
7
Not installed by CardOS API Setup; cardoscr.exe can be found in the \Extra directory of the distribution media.
It provides initialization scripts for initializing CardOS V5.x smart cards with PINs in format 2 as described in
ISO 9564-1. It is recommended to use these PINs with PIN pad readers with SPE using PC/SC V2.01 Part
10.
Please refer to 3.2.2.2 Secure PIN Entry for more details about SPE readers.
The CardOS API distribution provides a setup routine with initialization scripts for initializing CardOS V5.x
smart cards with binary PINs with variable pin length. PIN pad readers with SPE using PC/SC V2.01 Part 10
doesn't properly support these PINs.
Please refer to 3.2.2.2 Secure PIN Entry for more details about SPE readers.
3 System Requirements
This section lists the hard- and software requirements that are a prerequisite to run CardOS API V5.4 for
Windows. Please ensure that the following hard- and software prerequisites are fulfilled before installing
CardOS API.
10
3b d2 18 02 c1 0a 31 fe 58 c8 0c 50
CardOS DI V4.2 C 11
Latest service package
3b 88 80 01 00 00 c8 0c 77 83 a1 00 98
Verify RC package, FRN
CardOS V4.4 3b d2 18 02 c1 0a 31 fe 58 c8 0d 51
package
Latest service package,
ECC package (v5),
CardOS V5.0 3b d2 18 00 81 31 fe 58 c9 01 14
GSC package,
HMAC package
3b d2 18 00 81 31 fe 58 c9 02 17 Latest service package,
12
CardOS DI V5.3 GSC package,
3b 82 80 01 c9 02 C813 HMAC package
Latest service package,
CardOS V5.3 3b d2 18 00 81 31 fe 58 c9 03 16 GSC package,
HMAC package
CardOS cards to be used with GDOv1 Legacy File System (cf. 2.4.3)
CardOS/M4.01a 3b f2 98 00 ff c1 10 31 fe 55 c8 04 12 Service package
In case you want to use CardOS smart cards with a custom ATR you need to adjust the Windows registry
and device driver installation accordingly.
Please refer to the corresponding CardOS Packages & Release Notes for the latest appropriate service
packages and their versions.
8
The package can be installed optionally. It is not shipped as part of the CardOS API default initialization script.
9
Released only for contact based card operation with CardOS API.
10
Including CardOS DI V4.2 C CL
11
ATQB used for contact-less operation
12
Including CardOS DI V5.3 CL
13
Pseudo ATR used for contact-less operation
14
Microsoft recommends installing hot fix KB2424375 to use smart cards on Server 2008 R2.
15
To use Windows Smart Card Logon on Windows Server 2008 R2 it is recommended to enable a work around for a race-condition in
LSASS. Refer to the CardOS API – Installation Manual section 8.4 for further information.
16
It is recommended to install the Microsoft Base CSP hot fix KB2724137.
Please note that depending on the interface used (Microsoft CAPI, PKCS#11 Cryptoki) to access the card,
hot-plugging of readers is not supported. Some vendors of USB-tokens provide a dedicated hot-plug
enabling driver. In case a new reader is not detected automatically by either CardOS API or an application
using CardOS API the respective application needs to be restarted.
The following PIN pad readers have been tested for using ASCII numeric PINs with variable lengths:
The following PIN pad readers have been tested for using ASCII numeric PINs with fixed lengths on smart
card:
The following PIN pad readers have been tested for using PINs in format 2 as described in ISO 9564-1:
Provide Secure PIN Entry compliant setup and initialization scripts for CardOS V5.x smartcards
CardOS API V5.3
Support of CardOS V5.0 Signature application (see section 2.4.2)
Support of Secure Key Injection using Microsoft Minidriver V7 for CardOS V5.3 and CardOS DI V5.3
(see section 7)
Support of Microsoft Windows 8.1, Windows Server 2012, Windows Server 2012 R2 and
Windows 10
Added support to import (C_CreateObject()) DES3 token keys for on card single part encryption
and decryption to the PKCS#11 library
CardOS API V5.2
Added support for CardOS V5.0 smart card operating system
17
Support of secure PIN channel for PIN entry with Microsoft Minidriver V6
17
Support to use secure PIN entry (SPE) devices as external PIN with Microsoft Minidriver V6
Support to use secure PIN entry (SPE) devices as protected authentication path with PKCS#11
Minidriver read-only support for smart cards initialized with a GDOv1 file system
17
For information about which versions of Microsoft Windows are prepared to use this feature refer to
https://msdn.microsoft.com/library/windows/hardware/dn631754.
The CardOS API V5.4 for Windows PKCS#11 Cryptoki library is a successor of the CardOS API
V3.x PKCS#11 Cryptoki library and includes all change requests and patches up to CardOS API
V3.2 Build 42.
Supports new Microsoft smart card architecture and Windows Base CSP
Extended Multilanguage user interface including English, German, French, Spanish, Italian,
Portuguese, Slovak and Bulgarian.
Supports Microsoft Certificate Lifecycle Manager (CLM) and Identity Lifecycle Manager (ILM)
Fixed security issues in setup and CardOS API binaries. See CardOS API - Installation Manual
(SCS889)
Enhancement of support for CardOS V5.3 and CardOS DI V5.3 smart cards, including updated card
initialization scripts (SCS411, SCS457, SCS462, SCS464)
Fixed enrollment on cards, which are initialized with CardOS API V5.0 (SCS341).
Allow specification of PKCS#11 attribute CKA_SECONDARY_AUTH for private key objects with
C_GenerateKeyPair function (SCS425)
Fixed import of objects including non ASCII characters with CardOS API - Viewer (SCS567)
Fixed automatic extraction of CKA_LABEL attribute during the PKCS12 import with CardView
(SCS475)
CardOS API PKCS#11 can be configured to deny destroying of token objects using PKCS#11
interface (SCS334)
Includes CardOS V5.x Get Session Challenge package and enhanced session pin handling to
support of the Microsoft Minidriver V7.07 specification, date February 25, 2016 specification
(SCS295)
Support usage of QES key with Minidriver and pin pad reader (SCS626)
New default PKCS#15 file structure, changes especially regarding to ECC functionality, session pin
handling
Includes latest CardOS V5.3 and CardOS DI V5.3 service package (v2.0)
Adjust communication in contactless mode with CardOS DI V5.3 to CardOS DI V5.3 service package
v1.0 (SCS799)
Fixed interoperability with RSA public key exponents exceeding 3 bytes length (MWQO8Z,
NFFM3D)
rd
Improved interoperability with unsupported 3 party smart cards (MLNQG0)
Improved interoperability for card initialization with Microsoft Forefront Identity Manager 2010
(NDXKD0)
Improved mapping of CardOS API PKCS#15 file system into the Microsoft Base CSP environment
(NFDPFA)
Fixed decryption failure for CardOS V4 encryption only keys (algorithm RSA/RSA2) (NSLQX3)
Fixed concurrent use of CardOS API PKCS#11 and CardOS API Minidriver within the same
application (MOMNHK, M0VP6I).
Fixed use of smart cards initialized with a CardOS V5.0 file system with Internet Explorer in running
in protected mode (MDMKZI).
Time-stamped CardOS API Setup to allow installation after expiration of Atos IT-Solutions and
Services code signing certificate (M1TKNX).
CardOS API PKCS#11 can be configured to ignore SPE reader devices (MEIOU1).
CardOS API device driver information file installs scripts required to initialize new cards (L9HQKI).
Fixed data returned for reading cardid file from GDOv1 cards (MQPPUU).
Renamed binaries (esp. siecap11.dll has been renamed to cardos11.dll for x86 and cardos11_64.dll
for x64; See section 2.5 for a full list of binaries)
Improved support for certificate propagation (CARDOSCP /c[+|-]) in concurrent Citrix terminal
server sessions (KTFP2Z).
Improved support for CardOS VerifyRC package with CardOS V4.4, CardOS V4.2 C, and CardOS
DI V4.2 C by CardOS API Minidriver (KIISH4).
Improved display of certificate details in CardOS API - Viewer (HEXK4S, HGJO8B, H4KILU,
HGLPQK).
rd
Avoid propagation of certificates stored on smart cards managed by 3 party APIs (KKMMUM).
Fixed certificate propagation process failure after revert from system sleep mode (LQLI34).
Improved interoperability with smart cards not supported by CardOS API (LYVPJX).
Updated CardOS API default file system initialization with regard to “CardOS Packages and Release
Notes”, Copyright Atos IT Solutions and Services GmbH for CardOS V4.2 C (PRN Edition
11/2011), CardOS DI V4.2 C (PRN Edition 07/2011), and CardOS V4.4 (PRN Edition 07/2011)
CardOS API V5.0 B:
Improved CardOS API startup behavior during Windows system logon (JLBJJO, JKZMDM).
Fixed use of signature keys specifying an on card DSI object by the CardOS API Minidriver
(KM1NFJ).
Fixed enrollment of new certificates on CardOS smart cards initialized with the CardOS API V3 file
structure (KZCM5L, JW4L9G).
Fixed use of AT_KEYEXCHANGE keys personalized with PKCS#15 signRecover key usage by 3rd
party CAs (KNTMWU).
Updated CardOS API - User Manual and CardOS API - Installation Manual (J5ULSW, KODS25,
JICOJF).
Added configuration setting to CMFlags to enable CardOS API Minidriver build-in PIN prompt user
interface (KCXKDA). Please note that this setting now needs to be enabled explicitly in order to get
the same behavior as with previous versions of CardOS API V5.
Additional command line option (CARDOSCP.EXE /s) to gracefully stop a running CARDOSCP
instance (KYWJRM).
Fixed recognition of updated credentials on CardOS API V3 file systems (e.g. after re-keying)
(J9HOYE).
Provides CardOS API Minidriver support for objects with an empty (length = 0) PKCS#15 object
label (CommonObjectAttributes.label) (K2MQRK).
4.3.1 Update
CardOS API V5.3 can be updated to CardOS API V5.4 for Windows using the CardOS API Setup.
If any other previous CardOS API release (V3 or V5) is installed on your system, you have to remove this
version before installing CardOS API V5.4 for Windows.
Compared to previous versions of CardOS API V5 the PKCS#11 library has been renamed from
SIECAP11.DLL to CARDOS11.DLL for x86 and CARDOS11_64.DLL for x64.
Compared to previous versions of CardOS API V5 the Minidriver library has been renamed from
SIECACM.DLL to CARDOSCM.DLL for x86 and CARDOSCM_64.DLL for x64.
CardOS API V5.4 for Windows supports all CardOS smart cards that have been initialized by
previous CardOS API versions. Smart cards initialized and/or personalized by CardOS API V5.4 for
Windows are not supported by previous versions of CardOS API.
For CardOS cards initialized with CardOS middleware prior CardOS API V3.0 there is only a limited
compatibility:
Cards initialized with the GDOv1 file system are supported in read-only mode by CardOS API V5.4
for Windows MiniDriver and PKCS#11 interface.
Cards initialized with the GDOv2 file system (introduced with Card API V2.2.0) are not supported by
CardOS API V3.0 and above.
The following items apply independent of the actual CardOS API target operating system platform. Especially
you should consider the following in case you introduce your smart cards in a PKCS#11 environment and
plan to use the same smart cards with Microsoft CSP applications in the future.
Microsoft CSP uses so called containers to store keys and corresponding certificates. The
containers are uniquely identified by container names.
The PKCS#11 applications (e.g. Firefox) usually display the value of CKA_LABEL for key and
certificate objects. The CSP applications (e.g. Internet Explorer) usually display the container name
for the key and certificate objects. CardOS API maps the container name from the PKCS#11
attribute CKA_LABEL. This allows users to uniquely identify keys and certificates independent of the
used application.
Microsoft Windows Base CSP limits the length of container names to 39 characters.
The chosen approach results in the following consequences:
Each container can only hold a single asymmetric key pair and a corresponding certificate. This does
not impose any limitation on your PKI design, since all known CAs (and CA products) are able to
create a new container for each key pair.
PKCS#11 objects (a Certificate, a Public and a Private Key object) with an identical CKA_LABEL are
pooled to one container. The containers itself are distinguished using different CKA_LABELs. In
case two objects of the same type (e.g. two certificates) share the same CKA_LABEL it is not
possible to use these PKCS#11 objects via the Microsoft CSP interface.
This affects you if on one hand the PKI enrolls the key material via the PKCS#11 interface and, on the
other, the applications access the key material via Microsoft CSP.
%WINDIR%
Refers to the Microsoft Windows system directory containing all 32-bit objects on 32-bit operating systems or
all 64-bit objects on x64 Edition Windows operating systems:
Default: C:\WINDOWS\system32
%WOW64%
Refers to the Microsoft Windows system directory containing all 32-bit objects on 64-bit operating systems:
Default: C:\WINDOWS\SysWOW64
Objects belonging into this destination directory are only installed by the 64-bit setup
(CardOS_API_Setup_x64.msi). These objects are required to use CardOS API with 32-bit applications
running on a 64-bit host.
%CARDOSDIR%
Refers to the CardOS API installation directory:
Default: C:\Program Files\CardOS API
Depending on your platform either 32-bit or 64-bit binaries are installed into the %CARDOSDIR%\bin and
%WINDIR% directory. Objects belonging into the %WOW64% destination directory are only installed by the
64-bit setup (CardOS_API_Setup_x64.msi).
For 32- and 64-bit Windows operating systems the registry settings for CardOS smart cards are located at
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards].
For 64-bit Windows operating systems these registry settings need to be installed at
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Cryptography\Calais\SmartCards] in
addition. These settings are required to use CardOS API with 32-bit applications running on a 64-bit host.
18
cardoscm64.dll for [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards] on x64 systems.
cardoscm.dll for [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards] on x86 systems and the
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Cryptography\Calais\SmartCards] branch of x64 systems.
To resolve the device manager warning you need to update the device driver using the setup information file
included in the \Binaries directory of the CardOS API installation media. Select either
x86\cardoscm.inf or x64\cardoscm64.inf depending on your system (32-bit x86 or 64-bit x64
respectively).
In addition to the generic smart card device driver installation the provided device driver information file
includes the installation of the required files (6.2.2) and registry settings (6.3.1, 6.3.2; 6.3.3) required for the
CardOS API Minidriver.
Make sure to have your list of trusted root certificates updated before installing CardOS API. A list of trusted
root certificates accredited by Microsoft can be obtained as Microsoft Update KB931125
(http://support.microsoft.com/kb/931125).
The remaining certificates required for creating a trust chain for Atos Information Technology GmbH and to
establish Atos Information Technology GmbH as a trusted software publisher are included in the
\Certificates directory on the CardOS API installation media.
CardOS API uses an ECDH key agreement scheme to derive a symmetric session key shared between
client and server. This shared symmetric key is then used to encrypt the user’s asymmetric RSA key pair for
import.
The integrity of the ECDH key agreement protocol relies on a shared trust anchor that needs to be
established between client and server beforehand during card individualization (7.1).
The trust anchor needs to be kept in a trusted location for reference during a later key import (7.2).
1. CardAcquireContext(...)
pCardData
2. CardReadFile(cardid)
cardid
hKey, pbOutput
pbData
5. pfnCspFree(pbOutput)
6. CardDestroyKey(pCardData, hKey)
7. CardDeleteContext(pCardData)
8. Store(cardid, CKP_KEYX_THUMB_PRINT)
3. The client application calls CardGetSharedKeyHandle() to get a handle hKey for a shared secret
key. The output of the call can be ignored.
This trust anchor is a compulsory prerequisite for the security of the secure key import taking place later
on. In case this trust relationship is broken a user key may be decryptable on a wrong card (the card of
another user) or even outside a smart card (man-in-the-middle attacker pretending to be a smart card).
The actual value of the trust anchor is not secret; however, it must be properly protected against
modification and fraud. The trust anchor may for example be protected using a digital signature that
could either be stored centrally at the trust center or decentralized as a data file on the respective card.
1. CardAcquireContext(pCardData, 0)
pCardData
2. CardReadFile(cardid)
cardid
3. CardReadFile(cmapfile)
cmapfile
Determine bContainerIndex
4. CardGetSharedKeyHandle()
6. CardAcquireContext(pCardData, CARD_SECURE_KEY_INJECTION_NO_CARD_MODE)
pCardData
hKey
8. CardGetKeyProperty(hKey, CKP_KEYX_THUMB_PRINT)
pbData
Lookup (cardid)
CKP_KEYX_THUMB_PRINT
14. CardDeleteContext(pCardData) ok
16. CardWriteFile(cardcf)
ok
ok
18. CardDestroyKey(hKey)
19. CardDeleteContext(pCardData)
3 Read container map file (cmapfile) to select target container index for target key (bContainerIndex),
Following 3 use cases are possible:
In this case you just update the key data, not the key type or the container map entry.
Following additional steps needs to be performed:
Delete certificate file from container e.g. "kxc00", because it will not match with the updated key
after secure key import
If the target container is an existing one, the following additional steps needs to be performed
Write empty entry to container map file data (cmap file) for target container index, all other
existing cmap file data has to be unchanged.
If the target container is a new one, the following additional steps needs to be performed:
Modify/Extend container map file data (cmap file) for target container index, all other existing
cmap file data has to be unchanged.
4 Get client side handle for shared secret key. The output of this call needs to be forwarded to the server
side.
5 Client sends request for new RSA user key to server. The request includes the cardid (2) the selected
bContainerIndex (3) and the output returned from CardGetSharedKeyHandle() (4).
9 Verify that the data returned for CKP_KEYX_THUMB_PRINT is equal to the trust anchor which has been
retrieved and kept securely from the card initialization (7.1 3). This test ensures the integrity of the
shared key. In case this test fails the server cannot be sure that shared key belongs to the target card
and must abort the key import.
After successful completion of the key import the X.509 certificate belonging to the key may be stored on the
card.
8 Security Considerations
Since CardOS API is likely to be used in environments that deal with sensitive data the following items
should be considered before using CardOS API:
The MF of the file system which is created by CardOS API with the included default initialization
scripts (via the PKCS#11-function C_InitToken() that is used as well by the CardOS API - Viewer
to initialize cards) is protected by an Issuer PIN (see section: 2.4.1.1 Issuer PIN on page 7).
This provides the initial protection of our CardOS PKCS#15 cards. The knowledge of the Issuer PIN
allows changing the file structure, e.g. for changing access conditions or for creating additional
objects like DFs and EFs. In case of an extended security demand the default access conditions of
all card objects should be reviewed and if deemed necessary adjusted to the projects individual
requirements.
CardOS API uses the standard PC/SC stack of your workstation to communicate with the smart
card. This communication might be intercepted to spy out sensitive information (e.g. PINs, results
from decryption operations) or to pretend wrong results (e.g. successful verification of an invalid
signature).
It is strongly recommended to take effective measures to protect the overall system security to keep
Trojan Horses and other malicious software out of your system.
In case you intend to use CardOS API in networking scenarios (Remote Desktop, Terminal Server)
proper action need to be taken to secure your network communication.
We strongly recommend using card individual values for the Admin Key. In case you use the same
Admin Key value for multiple cards you need to ensure by organizational means that the card is
actually under the sole control of its legitimate user at the time the Admin Key is used (e.g. during
card unblock).
In case a CardOS dual interface card is used with CardOS API via its contact-less interface (ISO-
14443) there is an increased risk for forging and eavesdropping.
For CardOS DI V4.2C CardOS API does not provide any type of communication security on top of
the ISO-14443 standard.
Starting with CardOS DI V5.3 the CardOS API uses basic message authentication and encryption at
an APDU level (secure messaging). The measures implemented by CardOS API are designed to
defend against passive attacks (e.g. eavesdropping). Active attackers are not yet addressed by
CardOS API.
Note that this security feature is disabled in combination with secure PIN pad readers as PC/SC Part
10 does not support ISO7816 secure messaging for PIN entry.
Note that it is in the customer’s responsibility to ensure that his environment meets the requirements
stipulated in the confirmation document whenever CardOS is used to create a qualified electronic
signature
9 Known Issues
The following items describe known limitations and interoperability issues of the current version of CardOS
API. The list includes all known issues independent of the actual CardOS API target operating system
platform. It has been numbered for easier reference. The assigned numbers do not reflect any severity or
priority assigned to the issue.
1. The PKCS#11 Cryptographic Token Interface Standard does not support hot-plugging of card readers or
USB-Tokens. All applications using the CardOS API must be closed and restarted, if a new reader has
been installed or has been removed from the system.
2. Some smart card readers are not able to access CardOS smart cards with the highest baud rate
suggested by the CardOS ATR. The affected readers do not negotiate a connection at a slower baud
rate and communication with the smart card does not work. The CardOS ATR can be configured to
suggest a fixed baud rate (e.g. 9600 bit/s and up) to avoid those problems at the cost of system
performance. Refer to the CardOS User’s Manual for more information.
3. The IFD handlers of some smart card readers do not implement proper support for the ISO time wait
(WTX) command. These readers fail if executing time consuming commands such as GENERATE KEY
PAIR.
4. Terminal service roaming users between systems with different peripherals (card readers) may require
restarting the applications using CardOS API after reconnecting to the server.
5. Depending on the Citrix ICA protocol version used the Citrix ICA protocol does not support the use of
more than one USB reader on a Citrix ICA Client.
6. It may be required to restart CardOS API automated certificate propagation after reconnecting a Citrix
remote session.
7. The Initialize Card function (C_InitToken()) may not terminate correctly on Mac OS X, Linux, or when
running in a Citrix remote session.
8. The use of Secondary Authentication PINs is currently not supported by Mac OS X Tokend.
9. Private keys protected by a Secondary Authentication PIN should neither be used for Windows Smart
Card Logon, the function Run as…, nor for EFS (Encrypted File System).
11. The Preview Pane of Windows Mail for Windows Vista should be deactivated.
12. The Unblock Sec Auth PIN function cannot be supported for Cherry ST-2000 reader with the firmware
releases lower than 05.11. In order to use this functionality, the firmware of the reader must be updated
to release 05.11 or later.
b. Depending on the reader you use, the displayed windows and the respective workflow might
be different, but the number and type of the PIN entries are the same.
c. 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.
i. If using ACSII numeric PINs with fixed PIN Length, ReinerSCT reader exceeds the
configured max PIN length. It is recommend to use fixed PIN Length less or equal to
15.
14. The readers Omnikey CardMan 3621 and the Fujitsu Keyboard Reader KBPC CX D do not work
properly with Vista.
15. On Windows Vista some scenarios do not allow to grant sufficient access privileges to CardOS API to
create log files.
16. Visual C++ 2015 Redistributable Package must be installed. The libraries for x86 platforms are available
from Microsoft as vc_redist.x86.exe and the libraries for x64 platforms are available from Microsoft as
vc_redist.x64.exe and vc_redist.x86.exe (https://www.microsoft.com/en-
us/download/details.aspx?id=53587).
17. The default CCID IFD handler shipped with Microsoft Windows does not properly support extended
APDUs. This means that 2048bit keys cannot be used. In case you are affected by this limitation you
should install the IFD handler provided by your card reader vendor.
18. CardOS API Installer sets its display language depending on the Language for non-Unicode programs. A
setting for Regional and Language Options. This may result in a display language different from your
native Windows system.
19. Keys generated with the "Strong Key Protection" flag using the CardOS API V5 Minidriver are not
protected with a special Secondary Authentication PIN. Microsoft Base CSP does not provide the
required information to the Minidriver (CRYPT_USER_PROTECTED).
20. Some PKCS#11 Applications (e.g. Firefox) are not able to handle multiple cards with the same token
label. Keep that in mind when initializing your cards.
22. When creating new objects (keys, certificates) from concurrent processes the other process may only
recognize these changes after a re-insertion of the smart card.
23. CardOS API - Viewer is not able to handle more than one secondary authentication PIN. In case you
want to manage more than one secondary authentication PIN use the CardOS API PKCS#11 PIN Utility.
24. Removing the smart card during modification of a PIN with CardOS API - Viewer using a secure PIN
entry (SPE) device may result in undefined behavior of CardOS API - Viewer.
25. In case C_InitToken() is called to initialize a card using a secure PIN entry (SPE) device the new SO
PIN (PUK) assigned to the token must have a length of 10 characters.
26. Thunderbird automatically tries to update opened encrypted mails as soon as a smart card is inserted.
This results in asynchronous PIN prompts initiated by the Thunderbird process. This behavior can be
moderated if the message pane is disabled and Thunderbird is configured to open new messages in
tabs instead of separate windows.
27. When your system is put to sleep/hibernate mode all active PKCS#11 sessions are closed for security
reasons. Operations running in these sessions terminate with an error.
28. If Acrobat Reader is used with PKCS#11, Acrobat Reader does not properly recognize the certificate
stored on a card after removing and re-inserting the card. We recommend to use Acrobat Reader using
the Microsoft CSP interface where possible.
29. Note that Apple has deprecated the Tokend interface since Mac OS X 10.7
(http://smartcardservices.macosforge.org/post/apple-deprecates-smart-card-services-in-os-x-lion-v107/).
30. Starting with Mac OS X 10.6 it is no longer possible to change the PIN using the Change Password
feature of the Keychain Access application (Apple Bug Reporter Problem ID 7720698).
31. rfu In case you install a Tokend on Mac OS X 10.5 it is recommended to remove all smart cards during
system startup. If a smart card is connected to the system during startup you may not be able to log-on
to your system. To use your smart card for system logon, insert your smart card when the logon dialog is
displayed.
32. In order to have Microsoft Base CSP for Windows XP recognize new key material and certificates on
smart cards initialized with CardOS API prior to 3.2.042 a system reboot might be required.
33. Entering an invalid secondary authentication PIN or canceling secondary authentication PIN entry with
Icedove or Thunderbird may crash the application.
34. PIN Pad readers are not supported by Smart Card Logon on Windows OS prior to Windows 7
35. Key protection with Secondary Authentication PIN during key pair generation using CardOS API
PKCS#11 library is supported for CardOS versions CardOS V5.x
36. Setting key attribute CKA_MODIFIABLE to FALSE during key pair generation using CardOS API
PKCS#11 library isn't supported for CardOS versions CardOS V4.x.
37. Certificates, based on elliptic curves which are not supported by certain applications, are possibly shown
incorrectly by these applications. E.g. Microsoft certificate view, Thunderbird.
38. Some applications e.g Microsoft Word doesn't support properly ECC functionality.
39. At the time of the release of CardOS API V5.4 macOS mail program wasn't able to decrypt encrypted
mails.
Please also refer to the list of Known Issues contained on the installation media that may provide additional
last minute information and change notes.
10 Reporting Bugs
Please use the accompanying Ticket Registration form (located at the CD-ROM in PDF format) for a trouble
report or change request. Send this filled out form to who is listed in the service contract (or partner contract).
In case you have no service contract please contact your local Sales Agent.
You should have the following information to hand before you start filling in the Ticket Registration form:
Contact Information
Company, Country, Name, E-mail, and customer reference ticket.
Maintenance Contract Number
Number identifying your maintenance contract with your Sales Representative or Atos Information
Technology GmbH.
Description
Product Name, Version number, Build number, and description of the problem.
System Information
OS Platform, OS Version, Processor Type, Smart Card Type, and Smart Card Reader.
Environment Information
Description of the architecture (e.g. Client/Server, Workflow, etc.).
Attached Files
Card Log or the Local Log file as explained in the Installation Manual.
11 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.
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