CardOS API - Release Notes

Download as pdf or txt
Download as pdf or txt
You are on page 1of 43

© Atos Information Technology GmbH, 2004 - 2018 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 Atos Information
D-81739 Munich Technology GmbH sales representative for the most current
Germany information.

Contact: Subject to change without notice


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

Germany

http://www.atos.net/cardos

-2- CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Introduction

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

CardOS API V5.4 for Windows - Release Notes -3-


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Introduction

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.

1.1 Target Group


The CardOS API - Release Notes are intended for system integrators and system administrators.

1.2 Third-Party Copyrights


The Cryptographic Token Interface Standard “RSA Security Inc. Public Key Cryptography Standard (PKCS)”
is copyright by RSA Security Inc. (https://www.emc.com/emc-plus/rsa-labs/standards-initiatives/pkcs-11-
cryptographic-token-interface-standard.htm).

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.

-4- CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Subject of this Release

2 Subject of this Release


2.1 Version: Release Version
These release notes are for:
CardOS API V5.4 for Windows (Build 13)
Release version August 2018
CD-Name: CardOSAPIV5.4W13

2.2 Licensed Software


CardOS API is a licensed product. The number of installed clients is limited to the number of licenses you
own. The terms and conditions of the end user license agreement are displayed, while software is installed.

2.3 Supported Cryptographic Interfaces


CardOS API V5.4 for Windows supports both the Microsoft Smart Card Minidriver for Windows Smart Card
Base Cryptographic Provider V7.07 (Windows Base CSP) used to access the smart card from applications
using Microsoft CAPI and the PKCS#11 Cryptographic Token Interface Standard v2.11.

Cryptographic Application #1 Cryptographic Application #2


using Microsoft CAPI using PKCS#11 Cryptoki
(e.g. Secure E-Mail) (e.g. Client Authentication)

Microsoft CAPI PKCS#11 Cryptoki

Microsoft Smart Card


CardOS API PKCS#11
Base CSP

CardOS API Minidriver

PC/SC Smart Card Interface

2.3.1 Microsoft Smart Card Minidriver V7 for Windows Base


CSP
CardOS API V5.4 for Windows supports the Microsoft Smart Card Minidriver V7 as specified in "Microsoft
Smart Card Minidriver for Windows Base CSP V7.07”. The Microsoft Smart Card Minidriver V7 interface
includes downwards compatibility towards the Microsoft Smart Card Minidriver interfaces V5 and V6. The
Microsoft Smart Card Minidriver specifications can be downloaded from Microsoft at
https://msdn.microsoft.com/library/windows/hardware/dn631754. The Microsoft download site also provides
information about which Minidriver interface version applies to which version of Microsoft Windows. Older
versions of Microsoft Windows may not be able to use features of the Smart Card Minidriver introduced with
later versions of Microsoft Windows.

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 - Release Notes -5-


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Subject of this Release

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.

2.3.2 PKCS#11 Cryptographic Token Interface Standard


v2.11
CardOS API V5.4 for Windows supports the PKCS#11 Cryptographic Token Interface Standard v2.11. The
PKCS#11 specification is available from the RSA web server at: https://www.emc.com/emc-plus/rsa-
labs/standards-initiatives/pkcs-11-cryptographic-token-interface-standard.htm.

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 object types:

Object Type Description On Card Storage


1
CKO_CERTIFICATE X.509 certificates yes
CKO_DATA Plain data objects yes
2
CKO_PRIVATE_KEY RSA/EC private keys yes
2
RSA/EC public keys .
Calculations using these types
CKO_PUBLIC_KEY yes
of objects are always done in
software.
CKO_SECRET_KEY Secret session keys no

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

-6- CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Subject of this Release

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.

2.4 Card File System


2.4.1 CardOS API PKCS#15 Profile
The default card file system used by CardOS API V5.4 for Windows is based on the PKCS#15 Cryptographic
Token Interface Standard v1.1. The PKCS#15 specification is available from the RSA web server at:
ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-15/pkcs-15v1_1.pdf.

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.

2.4.1.1 Issuer PIN


4
Since HiPath SIcurity Card API 3.0 the file system is protected with a default Issuer PIN that should be
changed for custom projects.

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.

CardOS API V5.4 for Windows - Release Notes -7-


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Subject of this Release

2.4.1.2 PKCS#11 SO-PIN (PUK)


The SO-PIN (also known as PUK) is initialized with the value passed to C_InitToken(). Starting from
HiPath SIcurity Card API 3.1 this value is also used to initialize the Issuer PIN (2.4.1.1).

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

2.4.1.4 Minidriver Session PINs


The card file system of CardOS V4.2 C, CardOS DI V4.2 C, CardOS V4.4, and CardOS V5 cards initialized
with CardOS API starting from CardOS API V5.1 provides enhanced support for session PINs introduced
with Minidriver V6.

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.

2.4.1.5 Extra PINs/Secondary Authentication PINs


The CardOS API default file system shipped with CardOS API V5.4 for Windows installs two additional PIN
objects. Using CardSetContainerProperty(CCP_PIN_IDENTIFIER) these PIN objects can be
assigned to dedicated credentials for example. CardOS API PKCS#11 recognizes these PINs as secondary
authentication PINs.
5
Hash Alg: SHA1; Key Type: 3Key Triple DES (24 Bytes); ID Byte: 1; One iteration; Salt is set to the empty string; For CardOS V4 cards
DES key parity is adjusted in a non-standard way using the MSB (according to the standard it should be adjusted using the LSB). For
CardOS V5 cards parity adjustment is done standard conformant using the LSB. It is possible to configure standard parity adjustment
for CardOS V4 cards (cf. CardOS API – Intallation Manual; 8.2 PKCS#11-Options). The example vector for non-standard parity is:
94346175 163e3d19 a4dfc1ae d55ee36b 942f3d15 3df46794

-8- CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Subject of this Release

PIN Object Name Length Default Value


Extra PIN #0 4..16 “87654321”
Extra PIN #1 4..16 “12345678”

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.

2.4.2 CardOS Digital Signature Application


CardOS API can be used to access keys located inside the CardOS Digital Signature Application (CardOS
V4.3B, V4.4, V5.0). The structure of the application is described in the trustcenter information of the
respective CardOS version (for CardOS V5.0 refer to “CardOS V5.0 with Application for QES”, V1.0, Rev.
1.10, Edition 03/2013). The option to have multiple independent PINs protect the signature key (2nd set of
eyes schema) is not yet supported by CardOS API.

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.

2.4.3 GDOv1 Legacy File System


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.

CardOS API V5.4 for Windows - Release Notes -9-


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Subject of this Release

2.5 Released Objects


The tables below provide an overview of the documents, card initialization scripts, and binaries for Windows
contained in a CardOS API distribution (n/a = not applicable).

Documents Edition Description


This document describes system requirements for Windows.
CardOS API -
08/2018 As well, it provides information about supported applications,
Release Notes.pdf
new features, and known issues.
Contains step-by-step guides to install, modify, repair, and
CardOS API - remove of CardOS API V5.4 for Windows as well as detailed
08/2018
Installation Manual.pdf configuration information in a Windows environment.
This document is intended for system administrators.
Describes the use of CardOS API in your daily work.
CardOS API -
11/2017 This document is intended for users working with CardOS
User Manual.pdf
API.
Describes the use of the Viewer. This document is intended
CardOS API - Viewer -
11/2017 for system administrators and integrators as well as for users
User Manual.pdf
needing to manage the objects stored on their smart card.

Card Initialization Scripts Version Description


InitTokenC804.cpd n/a Initialization script for CardOS/M4.01a cards
InitTokenC804.sig n/a Signature file for InitTokenC804.cpd
InitTokenC808.cpd n/a Initialization script for CardOS V4.3 B cards
InitTokenC808.sig n/a Signature file for InitTokenC808.cpd
InitTokenC809.cpd n/a Initialization script for CardOS V4.2 B cards
InitTokenC809.sig n/a Signature file for InitTokenC809.cpd
InitTokenC80A.cpd n/a Initialization script for CardOS DI V4.2 B cards
InitTokenC80A.sig n/a Signature file for InitTokenC80A.cpd
InitTokenC80B.cpd n/a Initialization script for CardOS V4.2 C cards
InitTokenC80B.sig n/a Signature file for InitTokenC80B.cpd
6
InitTokenC80C.cpd n/a Initialization script for CardOS DI V4.2 C cards
InitTokenC80C.sig n/a Signature file for InitTokenC80C.cpd
InitTokenC80D.cpd n/a Initialization script for CardOS V4.4 cards
InitTokenC80D.sig n/a Signature file for InitTokenC80D.cpd
InitTokenC901.cpd n/a Initialization script for CardOS V5.0 cards
InitTokenC901.sig n/a Signature file for InitTokenC901.cpd
InitTokenC902.cpd n/a Initialization script for CardOS DI V5.3 cards
InitTokenC902.sig n/a Signature file for InitTokenC902.cpd
InitTokenC903.cpd n/a Initialization script for CardOS V5.3 cards
InitTokenC903.sig n/a Signature file for InitTokenC903.cpd
InitTokenC901_pf2.cpd Initialization script for CardOS V5.0 cards with PINs in format 2
n/a
as described in ISO 9564-1
InitTokenC901_pf2.sig n/a Signature file for InitTokenC901_pf2.cpd
InitTokenC902_pf2.cpd Initialization script for CardOS DI V5.3 cards with PINs in
n/a
format 2 as described in ISO 9564-1
InitTokenC902_pf2.sig n/a Signature file for InitTokenC902_pf2.cpd
InitTokenC903_pf2.cpd Initialization script for CardOS V5.3 cards with PINs in format 2
n/a
as described in ISO 9564-1
InitTokenC903_pf2.sig n/a Signature file for InitTokenC903_pf2.cpd

Windows x86 Edition


Version Description
Platform Binaries

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.

- 10 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Subject of this Release

cardview.exe 1.9.4.6 CardOS API - Viewer


chkscreg.exe 1.4.1.5 Smart Card registry conflict checking utility
7
cardoscr.exe 5.1.0.18 Minidriver challenge response calculation utility
gmp4_2_1.dll 4.2.1 GNU Multiple Precision Arithmetic Library
cardoscl.dll 2.6.1.0 Software implementation of cryptographic algorithms
cardoscm.dll 5.4.0.4 CardOS API Minidriver
cardoscm.inf 5.4.013 CardOS API device driver information file
cardossc.dll 5.4.0.7 CardOS API Smart Card Access Module
cardoscp.exe 1.15.1.5 CardOS API automatic certificate propagation tool
cardosui.dll 5.2.1.5 Common smart card dialogs library
cardos11.dll 2.21.2.4 Cryptoki (PKCS#11) library for CardOS smart cards
cardos15.dll 5.4.0.4 ISO7816-15/PKCS#15 library
cardospn.exe 1.10.1.5 CardOS API PKCS#11 PIN handling tool
cardosxg.dll 1.3.0.11 CardOS API GDOv1 library
Compression routines from the zlib project
(http://www.gzip.org/zlib). The zlib compression library is
zlib.dll 1.1.4.1 copyright by Jean-loup Gailly and Mark Adler.
zlib.dll may be linked to CardOS API statically. In this case
no separate zlib.dll is included in the distribution.

Windows x64 Edition


Version Description
Platform Binaries
cardview.exe 1.9.4.6 CardOS API - Viewer
chkscreg64.exe 1.4.1.5 Smart Card registry conflict checking utility
gmp4_2_1_64.dll 4.2.1 GNU Multiple Precision Arithmetic Library
cardoscl64.dll 2.6.1.0 Software implementation of cryptographic algorithms
cardoscm64.dll 5.4.0.4 CardOS API Minidriver
cardoscm64.inf 5.4.013 CardOS API device driver information file
cardossc64.dll 5.4.0.7 CardOS API Smart Card Access Module
cardoscp.exe 1.15.1.5 CardOS API automatic certificate propagation tool
cardosui64.dll 5.2.1.5 Common smart card dialogs library
cardos11_64.dll 2.21.2.4 Cryptoki (PKCS#11) library for CardOS smart cards
cardos15_64.dll 5.4.0.4 ISO7816-15/PKCS#15 library
cardospn.exe 1.10.1.5 CardOS API PKCS#11 PIN handling tool
cardosxg64.dll 1.3.0.11 CardOS API GDOv1 library
Compression routines from the zlib project
(http://www.gzip.org/zlib). The zlib compression library is
zlib.dll 1.1.4.1 copyright by Jean-loup Gailly and Mark Adler.
zlib.dll may be linked to CardOS API statically. In this case
no separate zlib.dll is included in the distribution.

2.5.1 CardOS API Setup Routines


The CardOS API distribution provides following setup routines:

2.5.1.1 SPE Compliant Setup Routine

 CardOS_API_SPE_Compliant_Setup.msi for 32-bit operating system


 CardOS_API_SPE_Compliant_Setup_x64.msi for 64-bit operating system

This is the recommended CardOS API setup routine.

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.

CardOS API V5.4 for Windows - Release Notes - 11 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Subject of this Release

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.

2.5.1.2 Standard Setup Routine

 CardOS_API_Setup.msi for 32-bit operating system


 CardOS_API_Setup_x64.msi for 64-bit operating system

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.

- 12 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
System Requirements

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.

3.1 Supported Smart Cards


CardOS API V5.4 for Windows supports the following smart cards of the CardOS family:

Smart Card OS ATR Required Packages


CardOS cards to be used with CardOS API PKCS#15 Profile (cf. 2.4.1)
Latest service package,
CardOS/M4.01a 3b f2 98 00 ff c1 10 31 fe 55 c8 04 12 Generate Key Pair
package
Latest service package,
CardOS V4.3 B 3b f2 18 00 02 c1 0a 31 fe 58 c8 08 74 8
Verify RC package
CardOS V4.2 B 3b f2 18 00 02 c1 0a 31 fe 58 c8 09 75 Latest service package
9
CardOS DI V4.2 B 3b f2 18 00 02 c1 0a 31 fe 58 c8 0a 76 Latest service package
CardOS V4.2 C 3b f2 18 00 02 c1 0a 31 fe 58 c8 0b 77 Latest service package

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

CardOS API V5.4 for Windows - Release Notes - 13 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
System Requirements

3.2 Microsoft Windows


Assure that your computer meets the minimum conditions of the operating system given by Microsoft and
has at least 40 MB free disk space before starting the installation.

3.2.1 Platform Prerequisites


CardOS API V5.4 for Windows runs on 32-bit x86 and 64-bit x64 Edition versions of Windows. CardOS API
has been designed and tested for the compatibility to the interfaces of the following Microsoft Windows
operating systems:

Operating System Platform


14,15,16
Windows Server 2008 R2 Enterprise x64 Edition (SP1)
Windows Server 2008 (SP2)
16
Windows 7 (SP1)
16
Windows 7 x64 Edition (SP1)
Windows 8
Windows 8 x64
Windows 8.1
Windows 8.1 x64
Windows 10
Windows 10 x64
Windows Server 2012 Standard Edition
Windows Server 2012 R2 Standard Edition
Windows Server 2016 Essentials

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.

- 14 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
System Requirements

3.2.2 Supported Smart Card Readers


3.2.2.1 PC/SC Readers
CardOS API V5.4 for Windows has been tested with a variety of PC/SC compliant
(www.pcscworkgroup.com) smart card readers on Microsoft Windows platforms. Appropriate drivers for the
readers are provided by the respective reader vendor. Depending of the security requirements of you
application you can use smart card readers with and without a PIN pad.

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.

3.2.2.2 Secure PIN Entry


CardOS API V5.4 for Windows supports PIN pad readers with Secure PIN Entry (SPE) using PC/SC V2.01
Part 10. It is recommended to use PINs in format 2 as described in ISO 9564-1 for using PIN pad readers

The following PIN pad readers have been tested for using ASCII numeric PINs with variable lengths:

Manufacturer Model Driver


OMNIKEY CardMan 3621
HID Global 1.2.24.27
OMNIKEY CardMan 3821

The following PIN pad readers have been tested for using ASCII numeric PINs with fixed lengths on smart
card:

Manufacturer Model Driver


OMNIKEY CardMan 3621
HID Global 1.2.24.27
OMNIKEY CardMan 3821
ReinerSCT cyberJack RFID komfort bc_7_3_5.exe

The following PIN pad readers have been tested for using PINs in format 2 as described in ISO 9564-1:

Manufacturer Model Driver


OMNIKEY CardMan 3621
HID Global 1.2.24.27
OMNIKEY CardMan 3821
ReinerSCT cyberJack RFID komfort bc_7_3_5.exe
acs APG8201-C1ZETE Sipiro_driver_win_2020

Please also notice section 9 Known Issues.

3.2.3 Supported Applications


CardOS API V5.4 for Windows works with Windows applications using either the interfaces Microsoft CAPI
or PKCS#11 Cryptoki to access the smart card. A limitation of the functionality may occur, if the application is
not completely compliant to the interface specification or uses undocumented proprietary functions of other
API vendors.

CardOS API V5.4 for Windows - Release Notes - 15 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Changes Compared to Previous Releases

4 Changes Compared to Previous Releases


4.1 New Features
CardOS API V5.4
 Support of elliptic curve cryptography with CardOS V5.x

 Support of pin block type 2 format with PIN pad reader

 Support of Local Security Authority (LSA) Authentication

 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 CardOS DI V5.3

 Support of CardOS V5.3

 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

 Support for RSA PSS signature scheme


CardOS API V5.1

17
Support of the Microsoft Minidriver V6 and Microsoft Minidriver V7 specification


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

 Support of Microsoft Server 2008 R2

 Support Forefront Identity Manager 2010

CardOS API V5.0 B


 Added support for CardOS DI V4.2C. CardOS DI V4.2C can be used in both contactless and contact
based operation scenarios.

 Supports Citrix XenApp V5 and Citrix XenDesktop V4

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.

- 16 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Changes Compared to Previous Releases

CardOS API V5.0


 The CardOS API Minidriver included with CardOS API V5.4 for Windows plus the Microsoft Base
Smart Card Crypto Provider (Base CSP) functionally replaces the former CardOS API V3.x CSP.

 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

 Supports 32-bit as well as 64-bit Microsoft Windows operating systems

 Added support for CardOS V4.2 B smart card operating system

 Added support for CardOS V4.4

 Extended Multilanguage user interface including English, German, French, Spanish, Italian,
Portuguese, Slovak and Bulgarian.

 Supports Windows Server 2008

 Supports Microsoft Certificate Lifecycle Manager (CLM) and Identity Lifecycle Manager (ILM)

 New MSI based installers instead of InstallShield Script.

CardOS API V5.4 for Windows - Release Notes - 17 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Changes Compared to Previous Releases

4.2 Fixed Bugs and Implemented Change Requests


CardOS API V5.4.13:

 Fixed incorrect handling of private key template parameter (CKA_EC_PARAMS) in


C_GenerateKeyPair (SCS890)

 Fixed security issues in setup and CardOS API binaries. See CardOS API - Installation Manual
(SCS889)

 Fixed usage of SPE dialogs in interactive mode (SCS851)

 Correction of reading CN label from certificate (SCS845)

CardOS API V5.4.11:

 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 setting of access condition EveryoneReadUserWriteAc using CardOS API Minidriver


(SCS316)

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

 Enhancement of the SKI functionality and bug fixes in SKI (SCS700)

 Customizable mouse over text on CardOS API certificate propagation (SCS768)

 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.0 service package (v3.0)

 Includes latest CardOS V5.3 and CardOS DI V5.3 service package (v2.0)

 Fixed incompatibility with Microsoft Edge browser (SCS795)

 Support random number generation on card via PKCS#11 interface (SCS798)

 Adjust communication in contactless mode with CardOS DI V5.3 to CardOS DI V5.3 service package
v1.0 (SCS799)

- 18 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Changes Compared to Previous Releases

 Includes latest ECC Package(v5) for CardOS V5.0

 improved interoperability between PKCS#11 and Microsoft CSP (SCS808)

 Added switch for disabling SPE dialogs (SCS811)

CardOS API V5.3:

 Includes latest CardOS V5.0 service package (v2).

 Fixed functionality of CardOS API Minidriver configuration CMFlags = 0x00000002 (creation of


distinct public key objects during RSA key generation or import) (NYPKX3)

 Fixed interoperability with RSA public key exponents exceeding 3 bytes length (MWQO8Z,
NFFM3D)

 Improved interoperability with Citrix VDI clients (NARJWG, MK4MTV)


rd
Improved interoperability with unsupported 3 party smart cards (MLNQG0)

 Fixed RSA PSS signatures with CardOS API Minidriver (NZ2OO0)

 Added RSA OAEP encryption for CardOS API Minidriver (N0VN5G)

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

 Added individual signature on each CardOS API binary (N40MU2)

 Support for container names using non-ASCII UNICODE characters (NUEQ7K)

 Fixed decryption failure for CardOS V4 encryption only keys (algorithm RSA/RSA2) (NSLQX3)

 Provide full interoperability with systems running EMET 4.0 (N8FPTG)

CardOS API V5.2 B:

 Improved performance of certificate propagation; optimized CardGetContainerInfo().


(M6KSHX)

CardOS API V5.2:

 Fixed documentation for Admin Key derivation used by C_InitToken() (MY4JZN).

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

 Reject zero length PINs passed to CardAuthenticatePIN() (LNSO1N).

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

CardOS API V5.4 for Windows - Release Notes - 19 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Changes Compared to Previous Releases

 Fixed data returned for reading cardid file from GDOv1 cards (MQPPUU).

 Improved interoperability of GDOv1 cards with Outlook 2007/2010 (MOIO63)

CardOS API V5.1:

 Changed manufacturer information due to changeover to Atos IT Solutions and Services

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

 Documentation updates (HQKRIY, KC0MG3, KGHOLR, GPKPZH, HQHPPF)

 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 computation of combined PKCS#11 digest/signature mechanisms (e.g.


CKM_SHA1_RSA_PKCS) (JXPPXB).

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

 Allow specification of attribute CKA_OBJECT_ID with C_CreateObject(CKO_DATA) (KBMLVG).

 Fixed support of certificate propagation flag CERTSTORE_FLAG_REMOVE_ON_TERMINATION


(J9JNKR, KOYNPS).

 Fixed memory violation in PKCS#11 logging (JNSM3J).

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

- 20 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Changes Compared to Previous Releases

 Additional command line option (CARDOSCP.EXE /s) to gracefully stop a running CARDOSCP
instance (KYWJRM).

 Fixed synchronization of C_GetTokenInfo() with concurrent PKCS#11 calls (K1MOVL).

 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 Migration from Previously Released Versions


CardOS API V5.4 for Windows is an update release for CardOS API V5.3 for Windows. Please note the
following items when migrating to the current version.

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.

4.3.2 Library Names


Due to the transfer of the CardOS product line to Atos IT Solutions and Services and to avoid conflicts with
previous versions the CardOS API top-level DLLs have been renamed starting with CardOS API V5.1:
 Compared to CardOS API 2.2.0 the PKCS#11 library has been renamed from
CardOS_PKCS11.DLL to CARDOS11.DLL.

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

For a complete list of binary names see section 2.5.

4.3.3 Card File System


CardOS API V5.4 for Windows (as CardOS API V3.x) uses a PKCS#15-based file system (see section
2.4.1).
 All versions of CardOS API above V3.0 support the full functionality of previous V3.x releases with
cards initialized using these previous versions respectively. However, features introduced with later
releases than the release, which was used to initialize the card, may not be fully supported (please
refer to section 4.1 New Features on page 16 for more details).

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

CardOS API V5.4 for Windows - Release Notes - 21 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Ensuring Interoperability between PKCS#11 and Microsoft CSP

5 Ensuring Interoperability between PKCS#11 and


Microsoft CSP
CardOS API has been designed to access the same smart card and objects stored on the smart card with
both PKCS#11 and Microsoft CSP applications. Since the approach for the PKCS#11 architecture is quite
different from that used by the Microsoft CSP architecture the points listed below should be considered to
ensure proper interoperability.

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.

Please contact your system integrator for further details.

5.1 PKCS#11 Object Identification and Microsoft CSP


Container Names
 In PKCS#11 the attributes CKA_ID and CKA_SUBJECT are used to uniquely identify an object. This
allows a PKCS#11 application to e.g. identify keys and corresponding certificates.

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

5.2 RSA Public Exponent Length


The data structure used by the Microsoft CSP framework to represent RSA keys does not allow the public
exponent to exceed the length of 32 bits. In case you plan to generate RSA key pairs via the PKCS#11
interface and these keys should be accessible via the Microsoft CSP interface the public exponent passed as
CKA_PUBLIC_EXPONENT to C_GenerateKeyPair() should therefore not exceed the length of 32 bits (4
bytes).

5.3 Unblock User PIN


Depending on the initialization of the card the User PIN can either be unblocked using the Admin Key via
the Microsoft Minidriver interface (e.g. by Microsoft Identity Lifecycle Manager) or by using the SO-PIN (PUK)
via PKCS#11 (e.g. CardOS API - Viewer, PKCS#11 PIN Tool). Refer to section 2.4.1.3 for details.

- 22 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Ensuring Interoperability between PKCS#11 and Microsoft CSP

5.4 PIN/PUK Values


PKCS#11 and Microsoft CSP use different PIN encoding formats. To be able to use Pins with PKCS#11 and
Microsoft CSP it is recommended to use only the following characters in the Pins:
!"#$%&'()*+,-./0123456789:;<=>?
@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^
_`abcdefghijklmnopqrstuvwxyz{|}~

CardOS API V5.4 for Windows - Release Notes - 23 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Setup Information for Microsoft Windows

6 Setup Information for Microsoft Windows


This section provides information for the CardOS API setup. This information may be used to create an own
customized setup script, e.g. for automated software distribution.

The following placeholders are used:

%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

6.1 Shortcuts Created by CardOS API Setup


The following shortcuts are created in the Windows Start menu during the CardOS API setup independent of
32-bit or 64-bit setup.

Shortcut Target Note


Start  Programs  CardOS API 
“%CARDOSDIR%\bin\cardospn.exe“ optional
Change PIN
Start  Programs  CardOS API 
“%CARDOSDIR%\bin\cardospn.exe “ /s optional
Change PUK
Start  Programs  CardOS API 
“%CARDOSDIR%\bin\cardospn.exe“ /x optional
Change Sec Auth PIN
Start  Programs  CardOS API 
“%CARDOSDIR%\bin\cardospn.exe“ /u optional
Unblock PIN
Start  Programs  CardOS API 
“%CARDOSDIR%\bin\cardospn.exe“ /y optional
Unblock Sec Auth PIN
Start  Programs  CardOS API 
“%CARDOSDIR%\bin\cardview.exe“ optional
Viewer
Start  Programs  CardOS API 
“%CARDOSDIR%\doc\English\
Documentation  optional
CardOS API – Installation Manual.pdf“
CardOS API – Installation Manual
Start  Programs  CardOS API 
“%CARDOSDIR%\doc\English\
Documentation  optional
CardOS API – Release Notes.pdf“
CardOS API – Release Notes
Start  Programs  CardOS API 
“%CARDOSDIR%\doc\English\
Documentation  optional
CardOS API – User Manual.pdf“
CardOS API – User Manual
Start  Programs  CardOS API 
“%CARDOSDIR%\doc\
Documentation  optional
License_Agreement_Smartcard_Products.pdf“
License Agreement
Start  Programs  CardOS API 
“%CARDOSDIR%\doc\English\
Documentation  CardOS API - optional
CardOS API – Viewer – User Manual.pdf“
Viewer – User Manual

- 24 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Setup Information for Microsoft Windows

6.2 Objects Copied by CardOS API Setup


Objects that can be removed from the setup without causing any functional limitations are marked as
‘optional’. Objects that can be removed but will result in functional limitations are described in detail.

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

6.2.1 CardOS API Documentation


Object Destination Folder Note
License_Agreement_Smartcard_Products.pdf %CARDOSDIR%\doc optional
CardOS API – Release Notes.pdf %CARDOSDIR%\doc\English optional
CardOS API – Installation Manual.pdf %CARDOSDIR%\doc\English optional
CardOS API – User Manual.pdf %CARDOSDIR%\doc\English optional
CardOS API – Viewer – User Manual.pdf %CARDOSDIR%\doc\English optional
CardOS API – Freigabehinweise.pdf %CARDOSDIR%\doc\German optional
CardOS API – Installationshandbuch.pdf %CARDOSDIR%\doc\German optional
CardOS API – Bedienungsanleitung.pdf %CARDOSDIR%\doc\German optional
CardOS API – Viewer – Bedienungsanleitung.pdf %CARDOSDIR%\doc\German optional

6.2.2 CardOS API Minidriver Files


The following table lists the files that need to be installed in order to use the CardOS API Minidriver:

Object Destination Folder Note


x86/x64 x64
chkscreg.exe chkscreg64.exe %CARDOSDIR%\bin optional
cardoscp.exe %CARDOSDIR%\bin required
Application to change or unblock PIN,
PUK, and Extra PINs. The component
might be removed in case this
cardospn.exe %CARDOSDIR%\bin functionality is not required. In that case
the items “Change PIN…” and “Unblock
PIN…” are not available from the context
menu of the CardOS API task bar.

InitTokenC80A.cpd %CARDOSDIR%\scripts Initialization script for CardOS DI V4.2 B


tokens. Might be removed in case this
InitTokenC80A.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC80B.cpd %CARDOSDIR%\scripts Initialization script for CardOS V4.2 C
tokens. Might be removed in case this
InitTokenC80B.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC80C.cpd %CARDOSDIR%\scripts Initialization script for CardOS DI V4.2 C
tokens. Might be removed in case this
InitTokenC80C.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC80D.cpd %CARDOSDIR%\scripts Initialization script for CardOS V4.4
tokens. Might be removed in case this
InitTokenC80D.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC804.cpd %CARDOSDIR%\scripts Initialization script for CardOS M4.01a

CardOS API V5.4 for Windows - Release Notes - 25 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Setup Information for Microsoft Windows

Object Destination Folder Note


tokens. Might be removed in case this
InitTokenC804.sig %CARDOSDIR%\scripts
functionality is not required.
InitTokenC808.cpd %CARDOSDIR%\scripts Initialization script for CardOS V4.3 B
tokens. Might be removed in case this
InitTokenC808.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC809.cpd %CARDOSDIR%\scripts Initialization script for CardOS V4.2 B
tokens. Might be removed in case this
InitTokenC809.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC901.cpd %CARDOSDIR%\scripts Initialization script for CardOS V5.0
tokens. Might be removed in case this
InitTokenC901.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC902.cpd %CARDOSDIR%\scripts Initialization script for CardOS DI V5.3
tokens. Might be removed in case this
InitTokenC902.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC903.cpd %CARDOSDIR%\scripts Initialization script for CardOS V5.3
tokens. Might be removed in case this
InitTokenC903.sig %CARDOSDIR%\scripts functionality is not required.
x86 x64
cardoscl.dll cardoscl64.dll %WINDIR% required
cardoscm.dll cardoscm64.dll %WINDIR% required
cardossc.dll cardossc64.dll %WINDIR% required
cardosui.dll cardosui64.dll %WINDIR% required
cardos11.dll cardos11_64.dll %WINDIR% required
cardos15.dll cardos15_64.dll %WINDIR% required
cardosxg.dll cardosxg64.dll %WINDIR% required for cards with GDOv1 file system
x64
cardoscl.dll %WOW64% required
cardoscm.dll %WOW64% required
cardossc.dll %WOW64% required
cardosui.dll %WOW64% required
cardos11.dll %WOW64% required
cardos15.dll %WOW64% required
cardosxg.dll %WOW64% required for cards with GDOv1 file system

6.2.3 CardOS API PKCS#11 Files


The following table lists the files that need to be installed in order to use the CardOS API PKCS#11 Interface:

Object Destination Folder Note


Might be removed in case CardOS API –
cardview.exe %CARDOSDIR%\bin
Viewer is not required.
Application to change or unblock PIN,
PUK, and Extra PINs. The component
might be removed in case this
cardospn.exe %CARDOSDIR%\bin functionality is not required. In that case
the items “Change PIN…” and “Unblock
PIN…” are not available from the context
menu of the CardOS API task bar.

InitTokenC80A.cpd %CARDOSDIR%\scripts Initialization script for CardOS DI V4.2 B


tokens. Might be removed in case this
InitTokenC80A.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC80B.cpd %CARDOSDIR%\scripts Initialization script for CardOS V4.2 C
tokens. Might be removed in case this
InitTokenC80B.sig %CARDOSDIR%\scripts functionality is not required.

- 26 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Setup Information for Microsoft Windows

Object Destination Folder Note


InitTokenC80C.cpd %CARDOSDIR%\scripts Initialization script for CardOS DI V4.2 C
tokens. Might be removed in case this
InitTokenC80C.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC80D.cpd %CARDOSDIR%\scripts Initialization script for CardOS V4.4
tokens. Might be removed in case this
InitTokenC80D.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC804.cpd %CARDOSDIR%\scripts Initialization script for CardOS M4.01a
tokens. Might be removed in case this
InitTokenC804.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC808.cpd %CARDOSDIR%\scripts Initialization script for CardOS V4.3 B
tokens. Might be removed in case this
InitTokenC808.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC809.cpd %CARDOSDIR%\scripts Initialization script for CardOS V4.2 B
tokens. Might be removed in case this
InitTokenC809.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC901.cpd %CARDOSDIR%\scripts Initialization script for CardOS V5.0
tokens. Might be removed in case this
InitTokenC901.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC902.cpd %CARDOSDIR%\scripts Initialization script for CardOS V DI 5.3
tokens. Might be removed in case this
InitTokenC902.sig %CARDOSDIR%\scripts functionality is not required.
InitTokenC903.cpd %CARDOSDIR%\scripts Initialization script for CardOS V 5.3
tokens. Might be removed in case this
InitTokenC903.sig %CARDOSDIR%\scripts functionality is not required.
x86 x64
cardoscl.dll cardoscl64.dll %WINDIR% required
cardossc.dll cardossc64.dll %WINDIR% required
cardosui.dll cardosui64.dll %WINDIR% required
cardos11.dll cardos11_64.dll %WINDIR% required
cardos15.dll cardos15_64.dll %WINDIR% required
cardosxg.dll cardosxg64.dll %WINDIR% required for cards with GDOv1 file system
x64
cardoscl.dll %WOW64% required
cardossc.dll %WOW64% required
cardosui.dll %WOW64% required
cardos11.dll %WOW64% required
cardos15.dll %WOW64% required
cardosxg.dll %WOW64% required for cards with GDOv1 file system

CardOS API V5.4 for Windows - Release Notes - 27 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Setup Information for Microsoft Windows

6.3 Registry Settings Required by CardOS API


This section describes the default registry settings written during setup. Please refer to the CardOS API –
Installation Manual for additional registry settings.

6.3.1 Registry Settings for Windows Base CSP


After the CardOS API files have been copied (6.2) some registry settings have to be applied.

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.

Key Name Type Value


80000001 REG_SZ cardoscm[64].dll18
3b d2 18 00 81 31 fe
ATR REG_BINARY
58 c9 03 16
ff ff ff ff ff ff ff
ATRMask REG_BINARY
CardOS V5.3 ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ Key Storage Provider
Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b d2 18 00 81 31 fe
ATR REG_BINARY
58 c9 02 17
ff ff ff ff ff ff ff
ATRMask REG_BINARY
CardOS DI V5.3 ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
ATR REG_BINARY 3b 82 80 01 c9 02 c8
ATRMask REG_BINARY ff ff ff ff ff ff ff
CardOS DI V5.3 CL Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b d2 18 00 81 31 fe
ATR REG_BINARY 58 c9 01 14
ff ff ff ff ff ff ff
ATRMask REG_BINARY ff ff ff ff
CardOS V5.0
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
CardOS V4.4 3b d2 18 02 c1 0a 31
ATR REG_BINARY
fe 58 c8 0d 51

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.

- 28 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Setup Information for Microsoft Windows

Key Name Type Value


ff ff ff ff ff ff ff
ATRMask REG_BINARY
ff ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b f2 18 00 02 c1 0a
ATR REG_BINARY
31 fe 58 c8 09 75
ff ff ff ff ff ff ff
ATRMask REG_BINARY
CardOS V4.2 B ff ff ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b f2 18 00 02 c1 0a
ATR REG_BINARY
31 fe 58 c8 0a 76
ff ff ff ff ff ff ff
ATRMask REG_BINARY
CardOS DI V4.2 B ff ff ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b f2 18 00 02 c1 0a
ATR REG_BINARY
31 fe 58 c8 0b 77
ff ff ff ff ff ff ff
ATRMask REG_BINARY
CardOS V4.2 C ff ff ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b d2 18 02 c1 0a 31
ATR REG_BINARY
fe 58 c8 0c 50
ff ff ff ff ff ff ff
ATRMask REG_BINARY
CardOS DI V4.2 C ff ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b 88 80 01 00 00 C8
ATR REG_BINARY
0C 77 83 A1 00 98
ff ff ff ff ff ff ff
ATRMask REG_BINARY
CardOS DI V4.2 C CL ff ff ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b f2 18 00 02 c1 0a
ATR REG_BINARY
CardOS V4.3 B 31 fe 58 c8 08 74
ff ff ff ff ff ff ff
ATRMask REG_BINARY
ff ff ff ff ff ff

CardOS API V5.4 for Windows - Release Notes - 29 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Setup Information for Microsoft Windows

Key Name Type Value


Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider
18
80000001 REG_SZ cardoscm[64].dll
3b f2 98 00 ff c1 10
ATR REG_BINARY
31 fe 55 c8 04 12
ff ff ff ff ff ff ff
ATRMask REG_BINARY
CardOS/M4.01a ff ff ff ff ff ff
Microsoft Base Smart
Crypto Provider REG_SZ
Card Crypto Provider
Smart Card Key Microsoft Smart Card
REG_SZ
Storage Provider Key Storage Provider

6.3.2 Certificate Propagation


In order to automatically start the CardOS API certificate propagation the following registry setting needs to
be configured at [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run].

Name Type Data


CardOS API REG_SZ “%CARDOSDIR%\bin\cardoscp.exe“

- 30 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Setup Information for Microsoft Windows

6.3.3 PKCS#15 Module Registry Settings


To use CardOS API PKCS#15 requires the following registry settings need to be configured at
[HKEY_LOCAL_MACHINE\SOFTWARE\CardOS API].

Name Type Data


P15ScriptDir REG_SZ %CARDOSDIR%\scripts

6.4 Device Driver Information File for Windows 7,


Windows 8 and Windows 10
Windows 7, Windows 8 and Windows 10 require installing a dedicated device driver for smart cards in
addition to the CardOS API Minidriver. In case this device driver is not installed the Windows device
manager does not properly recognize CardOS smart cards and displays a warning concerning an
unrecognized smart card. This warning does neither affect the functionality of CardOS nor of CardOS API on
your Windows 7, Windows 8 or Windows 10 system.

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.

6.5 Software Publisher Certificates


To protect the integrity of the CardOS API Setup the setup components have been signed by Atos
Information Technology GmbH.

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.

For further information refer to the CardOS API Installation Manual.

CardOS API V5.4 for Windows - Release Notes - 31 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Secure Key Injection

7 Secure Key Injection


The CardOS API V5.4 Minidriver supports Secure Key Injection based on the function set defined in the
Microsoft Smart Card Minidriver Specification V7.06; July 1, 2009; section 4.8. This functionality is currently
supported for CardOS V5.3 and CardOS DI V5.3.

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

7.1 Establishing a Trust Anchor


The process described below must run in a trusted environment during card individualization.

TRUSTED CLIENT MD Card

1. CardAcquireContext(...)

pCardData

2. CardReadFile(cardid)

cardid

3. CardGetSharedKeyHandle(pCardData, NULL, 0, pcbOutput, ppbOutput, pcbOutput, phKey)

hKey, pbOutput

4. CardGetKeyProperty(pCardData, hKey, CKP_KEYX_THUMB_PRINT, pbData, cbData, pdwDataLen, 0)

pbData

5. pfnCspFree(pbOutput)

6. CardDestroyKey(pCardData, hKey)

7. CardDeleteContext(pCardData)

8. Store(cardid, CKP_KEYX_THUMB_PRINT)

1. Acquire card context.

2. Read card identifier.

3. The client application calls CardGetSharedKeyHandle() to get a handle hKey for a shared secret
key. The output of the call can be ignored.

4. The client application calls CardGetKeyProperty(CKP_KEYX_THUMB_PRINT) to retrieve a unique


identifier of the shared secret key for the current card. This unique identifier is used as trust anchor in the
future. It has to be used by the trust center server to identify the smart card it is about to exchange a key
with.

CKP_KEYX_THUMB_PRINT is an additional key property defined by CardOS API:

#define CKP_KEYX_THUMB_PRINT L"KeyExchangeThumbPrint"

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

- 32 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Secure Key Injection

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.

5. Free output buffer allocated by the card minidriver.

6. Release resources relating to the shared key.

7. Delete card context.

8. Store tuple (cardid, CKP_KEYX_THUMB_PRINT) for future reference.

CardOS API V5.4 for Windows - Release Notes - 33 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Secure Key Injection

7.2 Importing an User’s RSA Key

MD(NO_CARD_MODE) SERVER CLIENT MD Card

1. CardAcquireContext(pCardData, 0)

pCardData

2. CardReadFile(cardid)

cardid

3. CardReadFile(cmapfile)

cmapfile

Determine bContainerIndex

4. CardGetSharedKeyHandle()

5. Request RSA User Key(cardid, bContainerIndex, pbOutput) hKey, pbOutput

6. CardAcquireContext(pCardData, CARD_SECURE_KEY_INJECTION_NO_CARD_MODE)

pCardData

7. CardGetSharedKeyHandle(pbInput ::= pbOutput)

hKey

8. CardGetKeyProperty(hKey, CKP_KEYX_THUMB_PRINT)

pbData

Lookup (cardid)

CKP_KEYX_THUMB_PRINT

9. Check shared key integrity

10. RSAPrivateKeyBLOB ::= Generate RSA user key

11. MDEncryptData(hKey, RSAPrivateKeyBLOB)

pbEncryptedData 12. pbEncryptedData

13. CardDestroyKey(hKey) 15. CardAuthenticateEx(ROLE_USER)

14. CardDeleteContext(pCardData) ok

16. CardWriteFile(cardcf)

ok

17. CardProcessEncryptedData(hKey, EncryptedData)

ok

18. CardDestroyKey(hKey)

19. CardDeleteContext(pCardData)

1 Acquire client side card context.

2 Read card identifier (cardid).

3 Read container map file (cmapfile) to select target container index for target key (bContainerIndex),
Following 3 use cases are possible:

3.1 Use Case Key Update:

- 34 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Secure Key Injection

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

 continue with step 4

3.2 Use Case: Replace Container

If the target container is an existing one, the following additional steps needs to be performed

 Delete certificate file from container e.g. "kxc00"

 Update card cache file

 Delete container for target container index.

 Update card cache file

 Write empty entry to container map file data (cmap file) for target container index, all other
existing cmap file data has to be unchanged.

 Update card cache file

 Read container map file to reflect changes on card

 Continue with 3.3 Use Case: Add Container

3.3 Use Case: Add Container

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.

 Update card cache file

 Write new container map file (cmap file)

 Update card cache file

 Create dummy container with CardCreateContainer for target container index.

 Update card cache file

 Read container map file to reflect changes on card

 continue with step 4

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

6 Acquire server side card context in CARD_SECURE_KEY_INJECTION_NO_CARD_MODE.

7 Get server side handle for shared secret key.

8 Get CKP_KEYX_THUMB_PRINT property of the shared key.

CardOS API V5.4 for Windows - Release Notes - 35 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Secure Key Injection

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.

10 Generate the new RSA key pair for the user.

11 Have the new RSA key encrypted by the minidriver.

12 Return the encrypted RSA key BLOB to the client.

13 Destroy server side shared secret key handle.

14 Delete server side card context.

15 Authenticate with ROLE_USER for key import.

16 Update card cache file.

17 Send encrypted RSA key BLOB to the minidriver.

18 Destroy client side shared secret key handle.

19 Delete client side card context.

After successful completion of the key import the X.509 certificate belonging to the key may be stored on the
card.

- 36 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Security Considerations

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

CardOS API V5.4 for Windows - Release Notes - 37 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Known Issues

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

10. The Preview Pane of Outlook Express should be deactivated.

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.

13. Details of PIN pad readers supporting the PC/SC interface:

a. If a timeout occurs while entering a PIN, it might be treated as a Cancel.

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.

d. Not all readers support timer configurations.

- 38 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Known Issues

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.

21. Certificate size shall not exceed 4096 bytes.

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.

CardOS API V5.4 for Windows - Release Notes - 39 -


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Known Issues

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.

- 40 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
Reporting Bugs

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.

CardOS API V5.4 for Windows - Release Notes - 41 -


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

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.

- 42 - CardOS API V5.4 for Windows - Release Notes


© Atos Information Technology GmbH, 2004 - 2018 All Rights Reserved
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

CardOS API V5.4 for Windows - Release Notes - 43 -


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

You might also like