The following applications are supported: Smart card login to a Windows 2000 or 2003 or 2008-Domain: ADS, Enterprise CA, Windows 2000 or 2003 or 2008 Server and as Client: Windows 2000 Professional or Windows XP Professional SSL- Authentication with smart card using Internet Explorer: Microsoft Internet Explorer 5.0, 5.5, 6.0 or 7.0, High Encryption Pack, SSL V3 with Strong User Authentication Outlook with digital signature and encryption via smart card: Outlook Express 5.0, 5.5 or 6.0 Windows Mail Outlook 2000, 2003, 2007 Lotus Notes with digital signature and encryption via smart card: Lotus Notes 6.5 or higher Windows VPN-Login with smart card: Windows 2000 Server and as Client: Windows 2000 Professional or Windows 2003 Server and as Client: Windows 2000 or XP Windows 2008 Server and as Client: Windows XP or Vista Smart card login to Novell eDirectory: Netware 5.1 SP3, eDirectory 8.6.1, Novell Client 4.83 SP1, NMAS EE 2.0 (with the included Universal Smartcard Login Method) with NICI 1.5.7 (Server and Client), NMAS 2.1 (with the included Universal Smartcard Login Method) with NICI 2.4.1 (Server and Client) or higher in each case Smart card login to Lotus Notes: Lotus Notes 6.5 or higher SSL- Authentication with smart card with Netscape: Netscape Navigator 4.72 (High Encryption), 4.73, 4.76, 6.x
Email-Security via smart cards with Netscape Messenger: Netscape Messenger 4.72 (High Encryption), 4.73, 4.76, 7.x Thunderbird 1.5 and above E-Mail-Security via PGP support (PKCS#11): PGP Personal Desktop 8.1 for Windows Compatibility/Smart card administration of the Baltimore-PKI (PKCS#11): Token Manager for Betrusted Unicert V5.2 for Windows Compatibility/Smart card administration of the Entrust-PKI (PKCS#11): Security Manager Administration 7.0 Compatibility/Smart card administration of the Ecos-PKI Appliance BB5000 (PKCS#11)
The mentioned products do not require any further client software. Please refer to the manual of your software application if it is not listed above.
Furthermore, CSSI ties in with the following preboot/ harddisk encryption environments:
CheckPoint/Pointsec Ultimaco

Mcafee PGP

Secude
3.2 Supported Smart Cards
Charismathics Smart Security Interface supports the following smart cards/tokens: ACOS A-Trust Card ActivIdentity Card CardOS V4.20 / V4.2B / V4.2C Gemalto EMV PKI JCOP 30,31 KONA NetKey PKS/2000/E4 Oberthur Cosmo V5.2 PIV plusID 60,75,90 Sm@rtCafe Expert 3.0/3.1, 3.2 StarCOS 30 ACOS EMV A03 Axalto Cyberflex Access V2c CardOS V4.30 / V4.3B GemXpresso Pro R3.2 JCOP 41 Micardo EC 2.x Oberthur Cosmopo RSA V5.x Oberthur ID-one Cosmo V7.0 Setec SetCard StarCOS SPK 2.3, 2.4 TCOS 2.x ACOS SMARTMX CardOS M4.01(a) G&D Sm@rtCafe Expett 64k JCOP 20, 21 jTOP JCX32/36 NetKey E4/2000 Oberthur CosmopolIC 64K V5.2 Oberthur Cosmo v5.4 Sm@rtCafe Expert 2.0, 2.1 StarCOS SPK 3.0 CardLogix

Following TPM chips are supported: Infineon TPM ATMEL TPM Broadcom TPM ST TPM Intel TPM

3.3 Tested Card Readers

Please make sure your PC/SC smartcard reader has been installed according to the producers specifications and is fully operational. Charismathics Smart Security Interface has been tested with the following card readers: ACS38 USB Eutron Digipass 860 Fujtsu Siemens Computer Smartcase SCR USB KOBIL KAAN advanced Omnikey Cardman 2020 USB Omnikey Cardman 3620 USB ORGA Card Mouse USB SCM SCR 3340 (Express-Card) SCM SCR333 charismathics plugncrypt Fujtsu Siemens Computer Smartcase KB SCR PRO Fujtsu Siemens Computer Smartcase SCR USB internal Omnikey Cardman 1010 serial Omnikey Cardman 3021 USB Omnikey Cardman 3621/3821 SCM SCR 331 USB SCM SCR 532 serial/USB SCM SCR335 USB Eutron cryptoidentity CCID Fujtsu Siemens Computer Smartcase KBPC CX Fujtsu Siemens Computer Smartcase Token USB Omnikey Cardman 2011 serial Omnikey Cardman 3121 USB Omnikey Cardmann CM4040 (PC-Card) SCM SCR 3310 USB SCM SCR241 PCMCIA
Additionally a great number of readers not explicitly mentioned above, but built upon compatible hardware, are supported. Note: Only PC/SC-drivers are supported. There is no support for CT-API-drivers. If RSA 2048 bit key shall be used, then the smartcard reader must support the extended APDU.
3.4 Secure Pin Entry (SPE)
A number of card readers come equipped with their own PIN-pad. This PIN-pad can be used for SPE if one of the following devices is used: Cherry Keyboard G83-6644 Omnikey 3621 USB OmniKey 3821 USB
Please make sure your windows device drivers are up to date if you want to use PC/SC 2.0 with SPE. To enable SPE, edit the registry setting at [HKEY_LOCAL_MACHINE\SOFTWARE\charismathics\smart security interface] To activate SPE, use: "USE_PINPAD"=hex:01 To deactivate SPE, use: "USE_PINPAD"=hex:00 Although CSSI supports alphanumeric PINS in general, SPE obviously only supports digits. Please make sure the PINs used for the card can be entered by using SPE if you intend to use it.
3.5 Unattended Installation
Instead of calling setup.exe, the installation can also be started in unattended mode by calling the corresponding msi file from the setup directory To install the admin edition: msiexec /i CSSI x.x - admin edition.msi /qn To install the user edition: msiexec /i CSSI x.x - user edition.msi /qn
To install the evaluation edition, use msiexec /i CSSI x.x - evaluation edition.msi /qn
4 Administration Tool: Charismathics Smart Security Interface Manager
This tool of the admin edition offers the following functions: changing your PINs, unlocking tokens, generating profiles, keys and certificates and so on.

These functions work very similar to each other. These functions are always available, and all require an authorization PIN to make a change. The changed value has to be entered twice to avoid typographic errors. All values are masked with asterisks to provide privacy. The PIN entry method can be changed the same way as in the login dialog.

TPM menu

The TPM menu is only visible if the optional TSS module has been installed. The functions of the menu require that a TPM hardware has been selected in the hierarchy view. See also chapter 4.8 TPM Management Take Ownership: This option is only available if Ownership of the TPM module has not yet been taken. Ownership is required for functions like TPM User creation to work. Taking Ownership of the TPM requires the User to enter a password. This password is only required for operations concerning the TPM itself. There is no option to give up Ownership from within the CSSI. Refer to the documentation of the TPM regarding this matter. Change Owner Password: This function asks for the current Owner Password and the new Owner Password, which has to be repeated, to change the Owner Password. Create TPM User: The CSSI admin editor permits the creation of multiple TPM User accounts. A TPM User is required to have the same name as a Windows account, otherwise the creation will fail. For any user to be able to use the TPM as a secure storage, a TPM User must have been created in advance using this function. Delete all TPM Users: This option removes all Users after asking for confirmation. Deleting individual users is possible by selecting the TPM User in the hierarchy view and selecting Delete TPM User from either the Edit menu or the right-click context menu. TPM User Login: Logging in to the TPM User allows importing key pairs from.pfx files using the Key Pair Import Key Pair from PFX-File. Login to the TPM requires the current password of the user. TPM User Logout: This function works analogous to TPM User Login. TPM User Change Password: Changing the TPM User password requires entering the current password once and the new password twice.
There are no options to unlock TPM passwords since TPM does not use password locking when a password is entered incorrectly regardless of the number of failed attempts.

Key Pair menu

It is possible to generate several key pairs with corresponding certificates on the card. Each set comprised of private key, public key (optional) and certificate (optional) is stored in a separate container. Generate Key Pair: Keys can only be created on the token if the user has logged in before. Once a key pair has been created it can be used for a number of purposes. See also chapters 4.4 Generating and Importing Keys and 4.5 Generating and Importing Certificates. Import Key Pair from PFX-File: This item opens a dialog asking for the PFX file to import.

4.1.6 Certificate menu Most items of the certificate menu are also accessible from the context menu when a certificate, public or private key, an object node, e.g. Certificates node in the hierarchy, is right-clicked.
Import Certificate: After selecting this item, pick the certificate to import from the opened dialog. If the certificate can be associated with a private/public key pair, it is automatically inserted into the correct container. Otherwise the certificate is added to the general Certificates node in the hierarchy. There is no way of manually associating a certificate with an unrelated key pair.
Show Certificate: Displays all information contained within the certificate. Select a field name in the upper half of the viewer to display the value in the lower half.
Export Certificate: Exports the certificate in either BASE64 or DER format to a file of the users choosing. The association with the key pair is recovered once the certificate is imported again via Import Certificate. Register Certificate: This option registers the certificate with windows, if not already done. Create Certificate Request: In order to receive a certificate for a private/public key pair, it is possible to prepare a certificate request. This request is stored in a BASE53 or DER encoded file. Refer to 4.5 Generating and Importing Certificates for a description of the process. Create self-signed Certificate: The requesting process is similar to the one in Create Certificate Request. However the request is not stored to a filed to be processed by a CA, but instead singed by the requesting. Info menu
Info: Displays general version information about the CSSI admin edition. Supported OS: Displays the list of smart card operating systems supported by CSSI. This list includes only the predefined associations. Additional associations can made with the CSSI Extension Tool (7 Charismathics Extension Tool). PKCS#11 Info: Displays Information on the PKCS#11 module, which ships with CSSI.
CSP Info: Information on the CSP. Manual: This manual.

4.2 Changing PINs

Usually there are 3 PINs on a token: the User PIN, the SO PIN (PIN of the system operator, i.e. system administrator) and the Card PIN. The term Card PIN is used for USB Tokens as well. Please note that not all cards and tokens support changing all PINs. The CSSI supports alphanumeric PINs and is not restricted to numeric digits in general. Refer to chapter 3.4 "Secure Pin Entry on limitations. There are different functions to use with these 3 PINs: The User PIN must be entered to write on the card (e.g. key generation, storing a certificate), delete objects or when the cryptographic functions (e.g. signing or decryption) are used. Refer to the table below regarding default User PIN and User PIN length. IMPORTANT: After three consecutive wrong inputs the User PIN will be locked.

For initializing a card with PIV profile you will need to input the triple DES Key in the TripleDES Key field with the TripleDESkeyvalueforexample:91BDFB50FEB589BFF1073D0EAA67EA7772E1282F53D9AF6B.
4.7 Preparing a Token (Initialization and Personalization)
In order that a user can employ his smart card, it must be prepared, i.e. the smart card must be initialized and personalized. In a first step you have to setup a profile on the smart card and in a second step setup the keys and certificates on the smart card. 4.7.1 First Step: Creating a Profile (Initialization) As a first step you must setup a profile on an empty smart card. You proceed as described in section 4.6 "Creating Profiles". 4.7.2 Second Step: Creating Keys and Certificates (Personalization) As a second step you must set up for a user key and certificate on the smart card. You have the possibility to either generate keys and certificates or to import them. Refer to section 4.4 "Generating and Importing Keys" and section 4.5 "Generation and Import of Certificates".

4.8 TPM Management

TPM management functions are only available if you installed the charismathics TSS module and the computer is equipped with TPM hardware. Please ask charismathics sales for details about the license of charismathics TSS module. The CSSI covers two aspects of the TPM lifecycle: Ownerless Modules and Owned Modules.
4.8.1 Operations on TPM without owner After the TPM Token has been opened using either the plus sign in front of the label within the main hierarchy view or using Manager Open Token, ownership of the TPM can be taken.
Once prompted, enter the password for the TPM Ownership. The TPM owner password is used only for TPM specific but user unrelated operations. Once ownership has been taken, it can no longer be relinquished using CSSI. Refer to the documentation of your TPM hardware (usually within the BIOS) if you want to give up the ownership. 4.8.2 Changing the current TPM Owner Password The current password can be changed later using TPM Change Owner Password At this point you will be asked to enter the old password and verify the new password by entering it twice. 4.8.3 Creating TPM User In order to make the TPM usable for a windows user a TPM User has to be created.
The TPM User has to be equal to the name of a windows user account; otherwise the TPM User creation fails. 4.8.4 Deleting TPM User TPM User can be deleted together or individually. To delete all Users at once, select TPM Delete all TPM Users and confirm the following dialog. Alternatively, it is possible to delete TPM User individually by right-clicking the User account and selecting Delete TPM User from either the context menu or the Edit. Deleting a user in this fashion requires confirmation as well.

4.8.5 Inspect TPM User private information To view the information associated with a user, use TPM Login.
Login to the TPM User requires entering the password of the selected account. TPM does not know a locking mechanism like smartcards do with PINs. Instead TPM hardware increases the delay between login attempts. 4.8.6 Changing the TPM User Password The password of the selected User can be changed via TPM TPM User Change Password.
Confirm the password change by entering the old password and entering the new password twice when asked. 4.8.7 Importing a key pair from a PFX file Instead of generating the public and private key pair on the TPM, it can also be imported from a PFX file. Select Key Pair Import Key Pair from PFX File and select the PFX file using the dialog.

4.9 Further Functions

4.9.1 Directory "Certificates" There is the directory Certificates for all certificates that are not directly corresponding to a key. These are intermediate certificates that have to be imported into this directory. For this purpose select the item Import Certificate in the menu Certificate or choose the context menu using the right mouse button.
4.9.2 Directory "Data" A smart card is the safest environment for the private key. Furthermore, the smart card is necessary for application with at least daily logins or authentication. Thus, it is often or always carried around. Therefore it makes sense to store sensitive or necessary data on this medium, e.g. a text file with your PINS. To create data highlight Data and select the item Create Data in the menu Edit. Then, a further window is displayed for you, where you can create your data:
There you have the possibility to access the actual data only if one is logged on to the smart card. To this end tick the field content readable after login only. Your existing data can be deleted, updated or exported via the Edit menu. 4.9.3 Function "Open Token" The function "Open Token" of the menu "Manager" transfers data from the smart card to the user interface. This is recommended, if you work with different cards or card readers. 4.9.4 Function "Delete all" and "Delete Object" You can delete all objects, keys, and certificates with the function "Delete all" of the menu "Edit". The function "Delete Object" offers you the possibility to remove objects, keys, and certificates. You obtain this second function over the context menu as well: highlight the object that you want to delete, right-click and there chose the item "Delete Object". 4.9.5 Function "Set Default Container" The function "Set Default Container" of the menu "Edit" is relevant to you only if you use a smart card for login to a Windows-2000 domain via CSP. If you do not choose a container as Default Container, Windows will take the first key from the list for the login to a Windows-2000 domain via CSP. If you have chosen a Container as Default Container, it will show in bold face in the interface of the administration tool

5 User Tool: Charismathics Smart Security Interface Utility
This tool exposes all relevant functions if you acquired Charismathics Smart Security Interface in the user edition. Changing your pin and the registration of your key/certificates of the smart card are available as well as TPM management functions. Insert your smart card in the reader and open Charismathics Smart Security Interface Utility by following the path: "Programs"->"charismathics "->"smart security interface" ->"smart security interface utility".

5.1 Change PIN

To change your PIN, insert the old PIN followed by the new PIN which must be entered a second time as confirmation. The minimum length of the User PIN is four characters and the maximal length is ten characters. Click on the button "Change PIN", and you receive a window with the confirmation. IMPORTANT: After three consecutive wrong inputs the User PIN will be locked. Please choose a PIN, which you can remember well, but which cannot be easily guessed. Avoid birthdays or simple sequences of numbers like 1234 or 1111.

5.2 Unlock PIN

To unlock your PIN, enter the SO PIN followed by the new PIN, which must be entered a second time as confirmation. The minimal length of the User PIN is four characters and the maximal length is ten characters. Click on the button "Unlock PIN" and a confirmation window opens.

5.3 Change Token SO PIN

To change the Token SO PIN, enter the SO PIN followed by the new SO PIN, which must be entered a second time as confirmation. The minimum and maximum length of the SO PIN is dependent on the card OS. Click on the button "Change SO PIN" and a confirmation window opens.

5.4 Registration

Your smart card may contain multiple certificates and keys. These certificates must be registered once, so that applications can use these. Particularly if it concerns the registration of the certificate/keys with the Microsoft Windows certificate database. IMPORTANT: THE REGISTRATION NEEDS TO BE DONE ONLY ONCE FOR EACH CARD.
5.5 Create TPM User (Optional)
All TPM operations have a number of prerequisites: TPM hardware has to be present TSS module has to be installed TPM Ownership must have been taken, e.g. with CSSI admin edition

Creating a TPM User only works on systems where a TPM User for the current user does not yet exist A TPM User can only be created for the currently logged in windows user.
5.6 Change TPM Password (Optional)
Changing a TPM User only works on systems where a TPM User for the current user has been created. Changing the TPM Password requires entering the old password once and the new password twice in the according fields.

6 Register Tool

To make certificates accessible for Windows applications like Internet Explorer or Outlook Express, you can automatically register the certificates from your smart card in the certificate store of Windows. The settings for this registration are configured in this Register Tool. The default functionality is as follows: as soon as a smart card is inserted into the card reader, the certificates are automatically registered, as long as the Register Tool is active. On smart card removal, the certificates are not automatically unregistered. If this is desired, you can adjust this using the "Settings". You can call the Register Tool of Charismathics Smart Security Interface either over the Start menu or over the tray icon:
Then you get the possibilities of starting the Charismathics Smart Security Interface Manager or the Charismathics Smart Security Interface Utility to pause the Register Tool, to configure Settings, to read information or to terminate the Register Tool, which is now explained.
6.1 Start CSSI Manager and Start CSSI Utility
The context menu of the system tray icon offers the choice of starting either the user edition (Charismathics Smart Security Interface Utility) and the admin edition (Charismathics Smart Security Interface Manager). Refer to chapters 4 and 5 regarding these tools.
6.2 PKCS11 register/ unregister
For the smartcard to be usable in the Netscape/Mozilla family of products a PKCS#11 module has to be registered with the products. This dialog offers a convenient way of installing the module. If the checkbox in front of the product name is not checked, the product is not configured to use the Charismathics PKSC#11 module. A marked checkbox signifies a PKCS#11 enabled product. Use the register/unregister button to apply the changes made. A few things to keep in mind when using this feature: Firefox and Thunderbird share the same configuration files. Installing the module in Firefox enables it in Thunderbird as well. Most applications have to be closed at the time register/unregister is selected, otherwise the operation fails. It is possible that the Register Tool considers the PKSC#11 module registered, while it actually is not, or vice versa. This may be due to failed installation/un-installation attempts or manual changes to the configuration. In this case, repeat the register/unregister process (remember to close all confirmation windows), until the desired effect sets in. This should take no more than 3 iterations. To avoid these problems, it is advisable to use only the Register Tool to change the configuration while all applications being changed have been closed.

6.3 Pause/ Continue

If automatic registration of the certificates on the token is not desired, you can pause the Register Tool. Select Pause from the context menu of the system tray icon to temporarily stop automatic registration. Once paused, you can select Continue from the same menu.
In addition to adding the certificates to the user store, they can also be added to the machine store. Set the registry value at: [HKEY_LOCAL_MACHINE\SOFTWARE\charismathics\smart security interface] To store certificates in the machine store, set "CSP_RegisterMachineStore"=hex:01. Revert the value to hex:00 to disable storing the certificates in the machine store.

6.4 Settings

The default functionality of the Register Tool is to register certificates automatically as soon as a token is inserted. Once the token is removed the certificates can be unregistered automatically. If this is desired, you can configure this using "Settings.
An alternate way of accessing this option is modifying the registry entry in [HKEY_LOCAL_MACHINE\SOFTWARE\charismathics\smart security interface] To deactivate automatic unregistering, use: "CSP_DeactivateUnregister"=hex:00. To activate automatic unregistering, use: "CSP_DeactivateUnregister"=hex:01.

6.5 About

For information about the version of the Register Tools and the manufacturer charismathics gmbh, select "About" in the menu of the tray icons:

6.6 Exit

With Exit in the menu of the tray icon you can end the Register Tool.
7 Charismathics Extension Tool
The Charismathics Extension Tool can be used to associate smart card operating systems with new ATRs. Without a valid association, correct operation of the smart card can not be guaranteed.
Follow these steps to make a new ATR/Card OS association: 1. Insert the smart card into the reader. The card ATR is displayed in the upper field. a. If an OS is associated with the ATR, the OS field is locked and can not be changed while the card is in the reader. b. If no OS is associated with the ATR, select the correct OS or a close as possible match. 2. Press Save to store the information. If the actual Operating System on the card is either unknown or not available, select one that matches the OS most closely, e.g. select the generic JCOP OS entry if the exact JCOP xx version number is not known.
Note: On Windows Vista, you must run this tool as administrator.
8 CSP of Charismathics Smart Security Interface
The Windows operating system supports cryptographic functionalities like encryption and digital signature by the so-called Crypto-API. Furthermore, CSPs (Cryptographic Service Providers) enable programs to support smart cards. During the installation of Charismathics Smart Security Interface the Charismathics Smart Security Interface-CSP (in short cmCSP) has been added. Using cmCSP enables a number of programs and functions that come with a Windows Operating System, like Outlook Express, Internet Explorer, network login and VPN-login to use smart-cards, USB tokens and TPM. They will be explained in the following. Charismathics Smart Security Interface includes also a minidriver for any CardOS V4.x smart card. The minidriver corresponds to the BaseCSP specification V6. For more information regarding the description of the minidriver requirements, please visit Microsoft website http://www.microsoft.com/whdc/device/input/smartcard/sc-minidriver.mspx. Smart card vendors can write card minidrivers to present a consistent interface to their smart card type to the Microsoft Smart Card Base Cryptographic Service Provider (CSP) or Crypto Next Generation (CNG) Key Storage Provider (KSP) and to the Smart Card Management Interface. These card minidrivers plug in to Windows operating system code.

8.3 SSL- Authentication with Smart Card over the Internet Explorer
To use certificates stored on hardware tokens for SSL connections, the certificate must have been registered with the Windows Certificate Store. This can be done using either the admin or user edition of CSSI and the Register Tool (refer to chapter 6 Register Tool or in section 4.8 "Register Certificate").
8.4 Outlook Express with Electronic Signature and Encryption via Smart Card
Electronic signing and encryption requires the certificates to be registered the same as for SSL connections. Once this is done, the desired certificate for signing and encryption can be chosen from "Tools Accounts E-Mail Preferences Security". Normally, there are pull-down menus in the email windows that you may click encryption and/or signing an email in order to use the security functionalities. The verification of incoming signed emails for instance uses the red "signet" symbol in the right corner of the email window In order for Outlook Express to automatically recognize the right key and corresponding certificate, the certificate should lie in the address book, i.e. the certificate should be imported into the "Digital IDs". Highlight the name in the address book and choose the tab "Digital IDs" over the context menu. On this tab you can import the certificate for the chosen contact.
8.5 Windows VPN-Login with Smart Card
You should generate keys and certificates with the Microsoft Enterprise-CA. Furthermore the certificate must be registered with the administration tool of Charismathics Smart Security Interface (refer to chapter 6 Register Tool and 4.9.9 Function "Register Certificate"").
9 PKCS#11-Module of Charismathics Smart Security Interface
The use of software that supports PKCS#11 is enabled by the Charismathics Smart Security InterfacePKCS#11 (abbreviated cmP11). The matter of applications and functionalities with tokens like network login, SSL, email security with Netscape and other producers are explained briefly. NOTE: There are no description on how to configure each environment to use cmP11. If your application is not covered here, please consult the corresponding documentation that comes with the application. IMPORTANT: The PKCS#11 module is a DLL by the name cmP11.dll and is installed in the system directory. Usually this is C:\Windows\system32. Remark: Despite strict measures for the quality of PKCS#11 modules by the different manufacturers, charismathics gmbh can not guarantee the compatibility with each PKCS#11 Module of a third party manufacturer.

Digest (Hashfunctions SHA1, MD2, MD5): Description: A hash value is calculated from the data. Order: C_DigestInit, C_DigestUpdate, C_DigestFinal or C_DigestInit, C_Digest C_Digest works as if C_DigestUpdate and then C_DigestFinal were called. C_DigestUpdate processes the data immediately.
Appendix B: Non-Standard Functions in PKCS#11 DLL
Two non-standard functions for the token initialization are added to the PKCS#11 library cmP11.

CK_RV EraseProfile

slotID pCardPIN ulCardPINLen
CK_SLOT_ID /* ID of the token's slot */ CK_BYTE_PTR /* CardPIN value */ CK_ULONG /* length of CardPIN value */
Erase the existed profile on a token. In order to erase the profile, the CardPIN must be verified.

CK_RV CreateProfile

slotID pProfile pSerNum ulSerNumLen pCardPin ulCardPINLen pSOPIN ulSOPINLen, pUserPIN ulUserPINLen pLabel ulUserPINRetry
CK_SLOT_ID /* ID of the token's slot */ CK_UTF8CHAR_PTR /* profile name, null terminated */ CK_BYTE_PTR /* serial number */ CK_ULONG /* length of serial number */ CK_BYTE_PTR /* CardPIN value */ CK_ULONG /* length of CardPIN value */ CK_BYTE_PTR /* SO PIN value */ CK_ULONG /* length of SO PIN value */ CK_BYTE_PTR /* UserPIN value */ CK_ULONG /* length of UserPIN value */ CK_UTF8CHAR_PTR /* 32-byte token label (blank padded) */ CK_ULONG /* retry counter of UserPIN */
Create a profile. The possible profile names are CORPORATE, PKCS15, CNS and FINEID. Usually, the token must be empty or the old profile must be erased before the new profile is written to the token. Not all profiles are supported by all smartcards. CardOS V4.x supports: CORPORATE, PKCS15, CNS CardOS M4.0(a) supports: CORPORATE JavaCards support: CORPORATE, PKCS15, FINEID ACOS supports: CORPORATE.

Remark:

Appendix C: Log Information
Logging information may serve to find and correct errors but impacts performance. In general, logging should be disabled. The logger should only be used by experienced users or when asked to. The log-file format is as follows: Each entry contains the function name, the parameter before and after the function call and the result of the function. Private information is hidden by a static string [------------------------------------], so only the length is readable.

Convenience Files

To enable logging with the default settings.reg files can be found in the installation directory. <program files>\Charismathics\smart security interface x.zz\ CSSI_Param.reg contains logging parameters for PKCS#11 and the CSP.

Registry Settings

Logging is controlled by registry entries stored in [HKEY_LOCAL_MACHINE\SOFTWARE\charismathics\smart security interface] "LogFile_mode"=dword:00000001 Use 1 to enable logging, 0 to disable logging.
"PKCS11_LogFile_name"="c:\\temp\\cmP11.log" "CSP_LogFile_name"="c:\\temp\\cmCSP.log" "TSP_LogFile_name"="c:\\temp\\cmTSP.log" "TCS_LogFile_name"="c:\\temp\\cmTCS.log" Select a logging file and directory. Use only absolute paths names. Remember to maintain backslash \ doubling.
Appendix D: Certificate Attributes (Key Usage)
A short explanation of the options follows: 1. Digital Signature: The certificate can be used for authentication and digital signature. 2. Admitted for Documents: The certificate verify signatures that check the liability and bindingness of documents (except signatures of certificates and CRLs of CA). 3. Key encryption: Encryption of keys for the purpose of their transmission. 4. Data encryption: Encryption of data for the purpose of transmission but not of keys. 5. Key exchange: Employment of the key to agree on other keys, e.g. a Diffie-Hellman key. 6. Only encrypting: This option is mutually exclusive with all other options. 7. Only decrypting: This option is mutually exclusive with all other options.

Smart card login to Windows Domains or Novell eDirectory SSL- Authentication by smart card (Internet Explorer, Mozilla Firefox, ) Email security with cards (PGP, Netscape Messenger, Outlook, Mozilla Thunderbird, Outlook Express, ) VPN with smart cards (Microsoft, Cisco, ) 5
This manual is meant for system administrators. Application developers, who develop their own applications that access software modules of Charismathics Smart Security Interface, e.g. PKCS#11, will find additional information in the appendices.
Charismathics Smart Security Interface-BaseCSP enables you to enhance applications and services in a Microsoft environment and their use with a smart card.

2 About this Manual

The Charismathics Smart Security Interface Security token configurator tool is described in chapter 4: Administration Tool: Charismathics Security Token Configurator. It contains information on how to manage keys and certificates, changing PINs, unlocking, initializing and personalizing smart cards. The Charismathics Smart Security Interface user edition is described in chapter 5: User Tool: Charismathics Smart Security Interface Utility. It contains information on how to change PINs and register your smart card.
Furthermore, you will find additional information regarding the Register Tool, CSSI Extension Tool, CSP and PKSC#11 and which applications may be upgraded by hardware tokens. Application developers can find further information on how to access modules (e.g. accessing PKCS#11) of Charismathics Smart Security Interface in the appendices, if they intend to develop a proprietary application. Certificate Attributes (Key Usage) is a concise description of the certificate attributes, i.e. information about key employment. However, an explanation on how to configure environments of Microsoft or other producers exceeds the scope of this manual. In these cases, please consult the documentation of the corresponding supplier.
NOTE: To understand this manual you need basic knowledge in IT-security. Especially, you should be familiar with the following notions: certificate, private and public key, secret key, digital signature, PKI, etc. Please consult the glossary on IT security on the Charismathics homepage (http://charismathics.com/application_areas/IT_security_glossary.php) if you want to consolidate your knowledge.

3 Installation

Before you can install Charismathics Smart Security Interface, the card reader you intend to use must be installed according to the manufacturers guidelines and be fully operational. The installation of Charismathics Smart Security Interface is run from the program CD. Please execute the file SETUP.EXE as a user with administrator rights. Follow the installation instructions.

CheckPoint or Pointsec Utimaco McAfee

PGP Secude

3.2 Supported Smart Cards and TPM Chips
Charismathics Smart Security Interface supports the following smart cards/tokens:
ACOS A-Trust Card ACOS EMV A03 ACOS A04 ACOS A05 ACOS SMARTMX ActivIdentity Card Axalto Cyberflex Access V2c CardLogix Java 2.2.1 Feitian FIPCS COS Siemens CardOS M4.01(a) Siemens CardOS V4.20 Siemens CardOS V4.2B Siemens CardOS V4.2c Siemens CardOS 4.2C DI Siemens CardOS V4.30 Siemens CardOS V4.3B Siemens CardOS V4.4

Gemalto EMV PKI Gemalto TPC DM 72K PIV Gemalto TOP IM GX4 GemXpresso Pro R3.2 GoldKey PIV token JCOP 20 JCOP 21 JCOP 30 JCOP 31 JCOP 41 JCOP J2 JCOP J3 JCOP J4 jTOP JCX32/36 KONA 10 KONA 132 KONA 25 KONA 26 Micardo EC 2.x 9

Morpho Orga YPS-ID2 Morpho YPS-ID3 IAS ECC NetKey E4/2000 NetKey PKS/2000/E4 Oberthur Cosmo V5.2 PIV Oberthur Cosmo v5.4 Oberthur Cosmopo RSA V5.x Oberthur CosmopolIC 64K V5.2 Oberthur Cosmo ID-One V5.2 PIV Oberthur ID-One Cosmo V7.0 Oberthur ID-One Cosmo V7.0 DI Oberthur ID-One Cosmo V7.0 n Oberthur ID-One Cosmo V7.0 - a Oberthur ID-One v7 IAS ECC
PAV Card ABACOS Privaris PlusID 60,75,90 Setec SetCard Sm@rtCafe Expert 2.0 Sm@rtCafe Expert 2.1 Sm@rtCafe Expert 3.0
Sm@rtCafe Expert 3.1 Sm@rtCafe Expert 3.2 Sm@rtCafe Expert 64k StarCOS 3.0 StarCOS SPK 2.3 StarCOS SPK 2.4
StarCOS SPK 3.0 TCOS 2.x Wibu Code Meter Dongle Watchdata TimeCOSPK
Charismathics Smart Security Interface supports the following TPM chips:

Atmel TPM Broadcom TPM

Infineon TPM Intel TPM

ST TPM Nuvoton TPM

3.3 Tested Card Readers
Please make sure your PC/SC smartcard reader has been installed according to the producers specifications and is fully operational. Charismathics Smart Security Interface has been tested with the following card readers:

ACS38 USB charismathics plugncrypt Eutron cryptoidentity CCID Eutron Digipass 860 Fujtsu Siemens Computer Smartcase KB SCR PRO Fujtsu Siemens Computer Smartcase KBPC CX Fujtsu Siemens Computer Smartcase SCR USB Fujtsu Siemens Computer Smartcase SCR USB internal Fujtsu Siemens Computer Smartcase Token USB KOBIL KAAN advanced Omnikey Cardman 1010 serial Omnikey Cardman 2011 serial

Omnikey Cardman 2020 USB Omnikey Cardman 3021 USB Omnikey Cardman 3121 USB Omnikey Cardman 3620 USB Omnikey Cardman 3621 Omnikey Cardman 3821 Omnikey Cardmann CM4040 (PC-Card) ORGA Card Mouse USB SCM SCR 331 USB SCM SCR 3310 USB SCM SCR 3340 (Express-Card) SCM SCR 532 serial/USB SCM SCR241 PCMCIA SCM SCR333 SCM SCR335 USB
Additionally a great number of readers not explicitly mentioned above, but built upon compatible hardware, are supported. Note:
Only PC/SC-drivers are supported. There is no support for CT-API-drivers. If RSA 2048 bit key shall be used, then the smartcard reader must support the extended APDU.
3.4 Secure Pin Entry (SPE)
A number of card readers come equipped with their own PIN-pad. This PIN-pad can be used for SPE if one of the following devices is used:
Cherry Keyboard G83-6644 Omnikey 3621 USB OmniKey 3821 USB
Please make sure your windows device drivers are up to date if you want to use PC/SC 2.0 with SPE. To enable SPE, edit the registry setting at [HKEY_LOCAL_MACHINE\SOFTWARE\charismathics\smart security interface] To activate SPE, use: "USE_PINPAD"=hex:01 To deactivate SPE, use: "USE_PINPAD"=hex:00 Although CSSI supports alphanumeric PINS in general, SPE obviously only supports digits. Please make sure the PINs used for the card can be entered by using SPE if you intend to use it.
3.5 Unattended Installation
Instead of calling setup.exe, the installation can also be started in unattended mode by calling the corresponding msi file from the setup directory To install the admin edition: msiexec /i CSSIx.x.msi /qn To install the user edition: msiexec /i CSSIx.x.msi /qn To install the evaluation edition, use msiexec /i CSSIx.x.msi /qn
4 Administration Tool: Charismathics Security Token Configurator
This tool of the admin edition offers the following functions: changing your PINs, unlocking tokens, generating profiles, keys and certificates and so on.

4.1 User Interface

After opening the administration tool of Charismathics Smart Security Interface you will see the following interface. The TPM Menu item is only visible if the optional TSS module has been installed and TPM hardware is present

Logout: This item works analogous to the Login option. Change User PIN/ Change SO PIN/ Unlock User PIN
These functions work very similar to each other. These functions are always available, and all require an authorization PIN to make a change. The changed value has to be entered twice to avoid typographic errors. All values are masked with asterisks to provide privacy. The PIN entry method can be changed the same way as in the login dialog. 4.1.4 TPM menu
The TPM menu is only visible if the optional TSS module has been installed. The functions of the menu require that TPM hardware has been selected in the hierarchy view. See also chapter 4.8 TPM Management
Take Ownership: This option is only available if Ownership of the TPM module has not yet been taken. Ownership is required for functions like TPM User creation to work. Taking Ownership of the TPM requires the User to enter a password. This password is only required for operations concerning the TPM itself. There is no option to give up Ownership from within the CSSI. Refer to the documentation of the TPM regarding this matter. Change Owner Password: This function asks for the current Owner Password and the new Owner Password, which has to be repeated, to change the Owner Password. Create TPM User: The CSSI admin editor permits the creation of multiple TPM User accounts. A TPM User is required to have the same name as a Windows account, otherwise the creation will fail. For any user to be able to use the TPM as a secure storage, a TPM User must have been created in advance using this function. Delete all TPM Users: This option removes all Users after asking for confirmation. Deleting individual users is possible by selecting the TPM User in the hierarchy view and selecting Delete TPM User from either the Edit menu or the right-click context menu. TPM User Login: Logging in to the TPM User allows importing key pairs from.pfx files using the Key Pair Import Key Pair from PFX-File. Login to the TPM requires the current password of the user. TPM User Logout: This function works analogous to TPM User Login. TPM User Change Password: Changing the TPM User password requires entering the current password once and the new password twice.

Info: Displays general version information about the CSSI admin edition. Supported OS: Displays the list of smart card operating systems supported by CSSI. This list includes only the predefined associations. Additional associations can made with the CSSI Extension Tool (7 Charismathics Extension Tool). PKCS#11 Info: Displays Information on the PKCS#11 module, which ships with CSSI. CSP Info: Information on the CSP. Manual: This manual.

4.2 Changing PINs

Usually there are 3 PINs on a token: the User PIN, the SO PIN (PIN of the system operator, i.e. system administrator) and the Card PIN. The term Card PIN is used for USB Tokens as well. Please note that not all cards and tokens support changing all PINs. The CSSI supports alphanumeric PINs and is not restricted to numeric digits in general. Refer to Chapter 3.4 "Secure Pin Entry on limitations. There are different functions to use with these 3 PINs:
The User PIN must be entered to write on the card (e.g. key generation, storing a certificate), delete objects or when the cryptographic functions (e.g. signing or decryption) are used. Refer to the table below regarding default User PIN and User PIN length. 17
IMPORTANT: After three consecutive wrong inputs the User PIN will be locked.
A locked User PIN can be unlocked by the SO PIN, which is also known as the PUK. Refer to the table below regarding default SO PIN and SO PIN length. The SO PIN is used exclusively for unlocking the User PIN. There are no other functions associated with the SO-PIN. IMPORTANT: After number of consecutive wrong inputs the SO PIN will be locked. Number of retry depends on the card profile.
With the Card PIN it is possible to delete an existing profile on a card and set up a new profile. The Card PIN will be determined during the initialization and can only be changed afterwards by creating a new profile. The length of the Card PIN is exactly ten characters. IMPORTANT: After ten consecutive wrong inputs the PIN is locked and the card cannot be deleted anymore, i.e. if the Card PIN, the SO PIN and the User PIN are locked, the token is useless.
PIN (default) User PIN (11111111) SO PIN (1111111111) Card PIN (0987654321)
Charismathics Profile 4- 8 8- 10 10
PKCS#15 Profile 4- 8 8- 10 10

CNS Profile 4- 8 4- 8 10

You find all functions concerning User and SO PIN in the menu "Token", as shown in the following figure:

4.3 Unlocking Tokens

As a security measure a token will be locked if a user enters a wrong PIN three times in a row. This provides security since an unauthorized person could otherwise check all possible PINs by trial and error if you lost your smart card or USB token, or it has been stolen. But it might happen that you have entered the wrong PIN three times even as a legitimate owner of the smart card. In this case the smart card will be locked as well. Therefore, you can unlock the smart card with Charismathics Smart Security Interface, if you know the SO PIN. You need the SO PIN to unlock a User PIN. "Unlock User PIN" is available from the "Token" menu, as shown in the following figure:

4.5 Generating and Importing Certificates
In order to use the smart card for digital signatures or encryption you need a key pair comprised of a private key and a public key. The public key has to be accessible to communication partners via a certificate. These certificates can be generated and managed by the Charismathics Security token configurator tool. These options to create a certificate from within the administration tool are: 1. You can sign the certificate corresponding to a public key by you or make a certificate request, such that another instance e.g. a trust center will authenticate the public key. 2. You already have a key and/or certificates. Then, you can import certificates if needed together with the corresponding key. 4.5.1 Generating Self-Signed Certificates and Certificate Requests You can generate the certificate belonging to a public key by signing it yourself or make a certificate request such that another instance, e.g. a trust center, authenticates the public key. To this end you highlight the Private Key and select one of the Create entries from the Certificates menu.
In order to generate the certificate request you enter the data into the corresponding fields. In case of a certificate request, you create a file to send it to the authority that should sign the certificate (e.g. trust center). Therefore, you store the request as a p10 file in a directory and follow the instructions of the corresponding authority intended to sign the certificate. Once the certificate has been returned by the issuer, you have to import the certificate using the menu item "Import Certificate". 20
Note: There is an explanation of the certificate attributes and how to employ the keys in the appendix B of this manual. 4.5.2 Importing Certificates In case you already own certificates that you intend to employ, you can import them with the menu "Certificate" under the item "Import Certificate". Certificates which belong to key pairs are directly assigned to the associated "container" after the importation. Certificates without keys - as for example CA certificates - are assigned to the file "Certificates".

4.6 Creating Profiles

If you want to use a smart card, there must be a profile on this smart card. In a first step you have to setup the corporate profile on this smart card. Click the menu "Manager""Create Token Profile".
4.6.1 Smart Card with Profile If there is already a profile on the card and you want to create a new one, the existing one will be deleted as a first step. To this end enter the Card PIN. If you have created the profile yourself, you have to enter the Card PIN you have assigned to the card. The default Card PIN is "0987654321". The further proceedings are the same as in the following section ".in the case of an empty smart card". Please follow the instructions which are described below. 4.6.2 Empty Smart Card If the profile is set up (Initialization) on an empty smart card, the "Card PIN", the "SO PIN", the User PIN and a Serial Number must be defined. Additionally a Label for the token can be assigned. If multiple profiles are available you can choose one now. Using CSSI tool you can initialize the cards with five profiles (Corporate, PKCS#15, CNS, FineID and PIV) depending upon the smartcards used. For AET profile, you can not initialize the cards with this profile but CSSI middleware is backward compatible with cards that have 21

6.2 Pause/ Continue

If automatic registration of the certificates on the token is not desired, you can pause the Register Tool. Select Pause from the context menu of the system tray icon to temporarily stop automatic registration. Once paused, you can select Continue from the same menu.
In addition to adding the certificates to the user store, they can also be added to the machine store. Set the registry value at: [HKEY_LOCAL_MACHINE\SOFTWARE\charismathics\smart security interface] To store certificates in the machine store, set "CSP_RegisterMachineStore"=hex:01. 33
Revert the value to hex:00 to disable storing the certificates in the machine store.

6.3 Settings

The default functionality of the Register Tool is to register certificates automatically as soon as a token is inserted. Once the token is removed the certificates can be unregistered automatically. If this is desired, you can configure this using "Settings.
An alternate way of accessing this option is modifying the registry entry in [HKEY_LOCAL_MACHINE\SOFTWARE\charismathics\smart security interface] To deactivate automatic unregistering, use: "CSP_DeactivateUnregister"=hex:00. To activate automatic unregistering, use: "CSP_DeactivateUnregister"=hex:01.

6.4 About

For information about the version of the Register Tools and the manufacturer charismathics gmbh, select "About" in the menu of the tray icons:

6.5 Exit

With Exit in the menu of the tray icon you can end the Register Tool.
7 Charismathics Extension Tool
The Charismathics Extension Tool can be used to associate smart card operating systems with new ATRs. Without a valid association, correct operation of the smart card can not be guaranteed.
Follow these steps to make a new ATR/Card OS association: 1. Insert the smart card into the reader. The card ATR is displayed in the upper field. a. If an OS is associated with the ATR, the OS field is locked and can not be changed while the card is in the reader. b. If no OS is associated with the ATR, select the correct OS or a close as possible match. 2. Press Save to store the information. If the actual Operating System on the card is either unknown or not available, select one that matches the OS most closely, e.g. select the generic JCOP OS entry if the exact JCOP xx version number is not known.
Note: On Windows Vista and above, you must run this tool as administrator.
8 CSP of Charismathics Smart Security Interface

Generating a key pair and corresponding certificate directly on the smart card with the functions of standard browsers, like Internet Explorer or Netscape. Thereby the token is accessed using the modules of Charismathics Smart Security Interface, i.e. correspondingly by cmCSP or cmP11. Point your browser to http://<Servername of Enterprise-CA>/certsrv if a certificate server is available. Import of existing keys and certificates on the smart card which were generated by other CAs or trust centers. Generation of key pair and corresponding self-signed certificate directly on the smart card by the administration tool Charismathics Smart Security Interface. Please note that the use of self signed certificates makes sense only in environments without PKI or for testing. Note: If you request a certificate from a trust center, you might be requested to choose a security module, e.g. a token. In this case choose the corporate profile, the cmCSP or the cmP11. Furthermore, your smart card has to be inserted in the card reader, so that certificates can be written on it.
The programs must be configured to work with your keys and certificates. Some programs require rootcertificates to be installed in certain directories, others require registering the certificate. In the following chapters only the special features of the corresponding application will be explained.
8.2 Smart Card Login to a Windows 2000 Domain
The following is a brief outline of the steps involved in setting up smart card or USB token login.
Setup of ADS. Please ensure the correct configuration of the DNS-Server. Installation of the Enterprise CA and at least the templates "Enrollment Agent", "Smartcard Logon" and Smartcard User". Then an Enrollment-Agent-Certificate must be generated and registered on the computer where the smart cards should be personalized. After that, the smart cards for users may be issued over the Enrollment Station.
8.3 SSL- Authentication with Smart Card over the Internet Explorer
To use certificates stored on hardware tokens for SSL connections, the certificate must have been registered with the Windows Certificate Store. This can be done using either the admin or user edition of CSSI and the Register Tool (refer to chapter 6 Register Tool or in section 4.8 "Register Certificate").

8.4 Outlook Express with Electronic Signature and Encryption via Smart Card
Electronic signing and encryption requires the certificates to be registered the same as for SSL connections. Once this is done, the desired certificate for signing and encryption can be chosen from "Tools Accounts E-Mail Preferences Security". Normally, there are pull-down menus in the email windows that you may click encryption and/or signing an email in order to use the security functionalities. The verification of incoming signed emails for instance uses the red "signet" symbol in the right corner of the email window In order for Outlook Express to automatically recognize the right key and corresponding certificate, the certificate should lie in the address book, i.e. the certificate should be imported into the "Digital IDs". Highlight the name in the address book and choose the tab "Digital IDs" over the context menu. On this tab you can import the certificate for the chosen contact.
8.5 Windows VPN-Login with Smart Card
You should generate keys and certificates with the Microsoft Enterprise-CA. Furthermore the certificate must be registered with the administration tool of Charismathics Smart Security Interface (refer to chapter 6 Register Tool and 4.9.9 Function "Register Certificate"").
9 PKCS#11-Module of Charismathics Smart Security Interface
The use of software that supports PKCS#11 is enabled by the Charismathics Smart Security InterfacePKCS#11 (abbreviated cmP11). The matter of applications and functionalities with tokens like network login, SSL, email security with Netscape and other producers are explained briefly. NOTE: There are no description on how to configure each environment to use cmP11. If your application is not covered here, please consult the corresponding documentation that comes with the application. IMPORTANT: The PKCS#11 module is a DLL by the name cmP11.dll and is installed in the system directory. Usually this is C:\Windows\system32. Remark: Despite strict measures for the quality of PKCS#11 modules by the different manufacturers, charismathics gmbh can not guarantee the compatibility with each PKCS#11 Module of a third party manufacturer.

9.1 Smart Card Login to a Novell eDirectory (formerly NDS)
This requires a very good understanding of the administration of Novell servers. To enable smart card or USB token login to an eDirectory you explicitly need the product NMAS and the corresponding Universal Smartcard Login Method.
9.2 SSL-Authenticatin with Smart Card Over Mozilla Firefox
Launch Firefox - Go to Tools Options Advanced Encryption Security Devices Load.
Click on Browse and locate cmP11.dll (cmP1164.dll for 64bit) and click on Open. Click on OK.
9.3 SSL- Authentication with Smart Card over Netscape
The notes for the configuration of Netscape are presented by example of version 7. Example: Netscape 7.01 You can call "Manage Security Devices" in Netscape 7.01 via "Edit""Preferences""Privacy & Security""Certificates". From here you can load the cmP11, so that SSL and emails can be used with tokens.
Furthermore, you can call the Certificate Manager of Netscape from the same tab by clicking "Manage Certificates.
9.4 Email-Security by Smart Cards and Tokens with Netscapes Messenger
The notes for the employment of Netscape and screen shots to manage certificates and modules are available in the example of version 7 in the previous section. Normally, there are pull-down menus in the email windows, where you can tick whether an email should be encrypted and/or signed. Functions for verification of received signed emails and decryption are available as well.

10 References

[PKCS#5] http://www.rsasecurity.com/rsalabs/pkcs/index.html [PKCS#11] http://www.rsasecurity.com/rsalabs/pkcs/index.html
[MS_CA] HOW TO: Configure a Certificate Authority to Issue Smart Card Certificates in Windows 2000: http://support.microsoft.com/default.aspx?scid=kb;en-us;Q313274&sd=tech
Guidelines for Enabling Smart Card Logon with Third-Party Certification Authorities: http://support.microsoft.com/default.aspx?scid=kb;en-us;Q281245
[MS_SC] Windows 2000 Server Documentation, Smart card Administration: http://www.microsoft.com/windows2000/en/server/help/default.asp?url=/windows2000/en/ser ver/help/sag_SC_admin.htm

Synopsis of specific functions
C_Finalize Parameter: Description:

pReserved

(CK_VOID_PTR)
Sessions will be closed. Slots will be closed. Reserved Memory will be freed. pReserved will be ignored. C_Finalize will be called automatically on Finish. If C_Initialize is called n times in succession (without C_Finalize in between), C_Finalize will only be carried out after the n time.

Deviation:

C_GetObjectSize Parameter:

hSession hObject pulSize

CK_SESSION_HANDLE CK_OBJECT_HANDLE CK_ULONG_PTR

Description: Deviation:

The size of an object will be returned The returned size is the minimum size of an object, which means it does not contain the size for extra attributes like label, or id. The size of private objects is the default value.

C_GetSlotList Parameter:

tokenPresent pSlotList pulCount
CK_BBOOL CK_SLOT_ID_PTR CK_ULONG_PTR

Description:

Returns a list of identified Slots. It might occur that installed but not connected Slots will be in the list. The number of Slots may be obtained by passing pSlotList a Null-Pointer. If you want only the Slots with an inserted card set tokenPresent to true.
C_GetTokenInfo Parameter: Description: Special Feature:

slotID pInfo

CK_SLOT_ID CK_TOKEN_INFO_PTR
Returns whether a card is inserted in a Slot. If the card is not inserted, CKR_TOKEN_REMOVED will be returned. Inserting or removing a card from a Slot is an Event (see C_WaitForSlotEvent). If C_GetTokenInfo will be called the Event will be finished, even if the card was removed and C_GetTokenInfo CKR_TOKEN_NOT_PRESENT has been returned.
C_Initialize Parameter: Description:
CinitArg Library will be initialized. Slots will be created. Inserted cards are read.

CK_VOID_PTR_PTR

CinitArg is expected in the format CK_C_INITIALIZE_ARGS. From these the flags are picked out, in particular CKF_LIBRARY_CANT_CREATE_OS_THREADS which decides over Multi threading. The rest is ignored. If C_Initialize is called several times, CKR_CRYPTOKI_ALREADY_INITIALIZED is returned. The number is taken in account (see C_Finalize).

C_InitToken Parameter:

slotID pPin ulPinLen pLabel
CK_SLOT_ID CK_UTF8CHAR_PTR CK_ULONG CK_UTF8CHAR_PTR
Description: Special Feature:
Token will be initialized. SO pin is given by the parameter pPin, User pin will be reset to default 11111111. The maximal length of SO pin is 10 digits. In Case Init (The token is empty): Card pin will be set to the same value as SO pin. After the token initialization, Card pin cannot be changed by PKCS#11, but SO pin can be changed using the function C_SetPIN. In Case Re-Init (The token is already initialized): The given SO PIN will be verified firstly. Then the User PIN will be reset to default 11111111, and all objects on token will be deleted. The SO PIN and Card PIN are unchanged.

C_OpenSession Parameter:

slotID flags pApplication Notify phSession
CK_SLOT_ID CK_FLAGS CK_VOID_PTR CK_NOTIFY CK_SESSION_HANDLE_PTR
Description: Deviation: Special Feature:
Opens a new session on the Slot. Notify and pApplication are ignored and should be set to NULL_PTR. Sessions can only be opened, if a card is inserted. If a session is opened and then the card will be removed, all sessions on the Slot will return CKR_DEVICE_REMOVED. If there is an error with CKR_ DEVICE_REMOVED, CKR_TOKEN_NOT_RECOGNIZED or CKR_TOKEN_NOT_PRESENT a pause is automatically produced on this Slot for all sessions. If a paused session is used again, this session will be reopened automatically. If a card is inserted into or removed from a Slot, then this is an Event (see C_WaitForSlotEvent). If C_OpenSession is called, the Event will be finished, even if the card has been removed and C_OpenSession returned CKR_TOKEN_NOT_PRESENT.
C_WaitForSlotEvent Parameter:

flags pSlot pReserved 46

CK_FLAGS CK_SLOT_ID_PTR CK_VOID_PTR (= NULL_PTR)
flag = 0; The method waits until a Slot reports an Event. Then it returns the Slot with the Event in pSlot. flag = CKF_DONT_BLOCK The method displays the Slot with Event in pSlot. If there is no Event, CKR_NO_EVENT will be returned.

Special Feature:

If more Slots have an Event, they will be returned interchangeably. An Event persists until an access to the card occurs (e.g. by C_OpenSession or C_GetToken_Info), even if an error will be returned to the card.

Objects

All objects will be stored on the card (CKA_TOKEN = true). Session- or other software-objects will not be supported. The ID (CKA_ID) indicates which objects belong together. CKO_CERTIFICATE (CKC_X_509) Certificate in X.509 format Attribute Value CKA_CLASS CKO_CERTIFICATE CKA_LABEL <alias> CKA_VALUE <certificate> X509Format (DER) CKA_ID <number> CKA_CERTIFICATE_TYPE CKC_X_509 CKA_TOKEN TRUE CKA_PRIVATE FALSE CKA_SUBJECT <alias> CKA_ISSUER <alias> CKA_SERIAL_NUMBER <number> CKA_MODIFIABLE TRUE/FALSE (**) Returns no error on trying to write. Access Read only Read/write read/write read/write read only read only read only(**) read only read only read only read only(**)

CKO_PRIVATE_KEY (CKK_RSA) Attribute CKA_CLASS CKA_LABEL CKA_ID CKA_KEY_TYPE CKA_TOKEN CKA_PRIVATE CKA_SUBJECT CKA_SENSITIVE CKA_DECRYPT CKA_SIGN CKA_SIGN_RECOVER CKA_UNWRAP CKA_MODULUS CKA_PUBLIC_EXPONENT CKA_PRIVATE_EXPONENT CKA_PRIME_1 Value CKO_PRIVATE_KEY <alias> <number> CKK_RSA TRUE TRUE <alias> FALSE TRUE TRUE FALSE FALSE Pkcs12 Format Pkcs12 Format Pkcs12 Format Pkcs12 Format 47 Access read only read/write read/write read only read only read only read only(*) read only read only(**) read only(**) read only(**) read only(**) read only read only not readable not readable
CKA_PRIME_2 Pkcs12 Format CKA_EXPONENT_1 Pkcs12 Format CKA_EXPONENT_2 Pkcs12 Format CKA_COEFICIENT Pkcs12 Format CKA_MODIFIABLE TRUE CKA_LOCAL TRUE CKA_START <empty> CKA_STOP <empty> 8 CKA_EXTRACTABLE FALSE 2 CKA_NEVER_EXTRACTABLE TRUE (*) Can only be read if a corresponding certificate exists. (**) Returns no error on trying to write. (***) Is not supported.
not readable not readable not readable not readable read only(**) (**)(***) (***) (***) read only(**) read only(**)
CKO_PUBLIC_KEY (CKK_RSA) Attribute Value Access read only read/write read/write read only read only read only read only(*) read only(**) read only(**) read only(**) read only(**) read only read only read only(**) (**)(***) (***) (***)
CKA_CLASS CKO_PUBLIC_KEY CKA_LABEL <alias> CKA_ID <number> CKA_KEY_TYPE CKK_RSA CKA_TOKEN TRUE CKA_PRIVATE FALSE CKA_SUBJECT <alias> CKA_ENCRYPT TRUE CKA_VERIFY TRUE CKA_VERIFY_RECOVER TRUE CKA_WRAP FALSE CKA_MODULUS pkcs12 Format CKA_PUBLIC_EXPONENT pkcs12 Format CKA_MODIFIABLE FALSE CKA_LOCAL TRUE CKA_START <empty> CKA_STOP <empty> (*) Can only be read, if a corresponding certificate exists (**) Returns no error on trying to write (***) Is not supported
CKO_DATA General Data Attribute Value Access read only read/write read/write read only read only(**) read/write read only(**)
CKA_CLASS CKO_DATA CKA_LABEL <alias> CKA_VALUE <data> CKA_TOKEN TRUE CKA_PRIVATE FALSE CKA_APPLICATION <alias> CKA_ MODIFIABLE TRUE (**) Returns no error on trying to write.

Mechanism

Sign (RSA): Description: Order:
Signs data C_SignInit, C_SignUpdate, C_SignFinal or C_SignInit, C_Sign C_Sign works as if C_SignUpdate and then C_SignFinal were called. C_SignUpdate processes the data immediately. Order C_SignInit, C_Sign(C_SignUpdate, C_SignFinal), C_Sign (C_SignUpdate, C_SignFinal) where on the first C_Sign (resp. C_SignFinal) NULL_PTR will be passed for the signature and only the length of the signature will be returned. The signature will be returned on the second C_Sign (resp. C_SignFinal). If C_SignUpdate is called for the second time, the data must match with the data of the first time. A third call is not possible. For another signature C_SignInit must be called first.