Installing CardOS API

The CardOS API distribution provides a universal (x86/64) setup package for Mac OS X on Intel-based Macs.
For details on system requirements refer to the CardOS API - Release Notes for Mac OS X.

Before installing the current version of CardOS API make sure any previous versions of CardOS API have been removed from your system.

Open the CardOS API installation package in the Mac OS X Finder to start the installation.
If the Finder does not open you can find the package on the CD at /Packages.

This will install the following files on your system:

Path File Version Description
/private/etc cardos_api.conf n/a CardOS API configuration file
(see Configuring CardOS API)
/usr/local/bin cardospn n/a CardOS API PIN Utility
/usr/local/lib libcardossc.dylib n/a CardOS API Card Interface Library
libcardosui.dylib n/a CardOS API GUI Library
libcardos11.dylib n/a CardOS API PKCS#11 Library
libcardos15.dylib n/a CardOS API PKCS#15 Library
libcardosxc.dylib n/a CNS file system support library
libcardosxg.dylib n/a GDOv1 file system support library
libcardostkn.dylib n/a CardOS API Token Library
libiplasn1.dylib ipl3 IPL ASN.1 Library
libiplcsp.dylib ipl3 IPL Crypto Algorithm Library
libiplutils.dylib ipl3 IPL Utility Library
libgmp.dylib n/a Symbolic link to libgmp.3.5.2.dylib
libgmp.3.dylib n/a Symbolic link to libgmp.3.5.2.dylib
libgmp.3.5.2.dylib 4.3.2 GNU Multiple Precision Arithmetic Library
libcardoscl.dylib n/a Symbolic link to libcardoscl.1.dylib
libcardoscl.1.1.6.dylib n/a Symbolic link to libcardoscl.1.dylib
libcardoscl.1.dylib 2.6.1 Software implementation of cryptographic algorithms.
CardOSAPIPKCS11.bundle n/a CardOS API PKCS#11 Module (Mac OS X bundle)
/System/Library/Security/tokend CardOS.tokend n/a CardOS API Tokend
/Applications/Utilities/CardOS API Change PIN.app n/a CardOS API Change PIN Application
Change PUK.app n/a CardOS API Change PUK Application
Unblock PIN.app n/a CardOS API Unblock PIN Application
/usr/local/cardos_api/icns cardos.icns n/a CardOS API icons
question.icns n/a
/usr/local/cardos_api/scripts InitToken????.cpd n/a Initialization script for CardOS smart cards. ???? identifies the type of the CardOS smart card. The availability of CardOS API initialisation scripts for the individual CardOS smart card types depends on the CardOS API version.

C804 = CardOS/M4.01a
C808 = CardOS V4.3 B
C809 = CardOS V4.2 B
C80A = CardOS DI V4.2 B
C80B = CardOS V4.2 C
C80C = CardOS DI V4.2 C
C80D = CardOS V4.4
C901 = CardOS V5.0

InitToken????.sig n/a Signature file for the respective InitToken????.cpd file.

In case you want to install to a different location you may extract the archive to a temporary folder and copy the libraries to a different location.

Configuring CardOS API

Configuration information is retrieved from the file /private/etc/cardos_api.conf.

The configuration settings are given as attribute name and value pairs:

Attribute=Value

A detailed description for the available attributes is given below. Follow this link for an example configuration file.

Enable Logging for CardOS API

Warning Warning
For security reasons the CardOS API logging should be disabled during normal use of the API. However, log files may help you during testing and to track down errors.
Info Note
It is recommended to use absolute path names for your log files. Otherwise the log files are created relative to the location of the calling application and may be hard to find. Grant sufficient write access rights for all users that shall be able to create log files.

PKCS#11 Logging

CardOS API PKCS#11 logging is controlled by the following configuration attributes:

Attribute Description
P11LogFile PKCS#11 log file location.
P11LogLevel PKCS#11 logging level
TokendLogFile CardOS Tokend log file location.
TokendLogLevel CardOS Tokend logging level

P11LogFile can contain the following wildcards:

Wildcard Description
&u Logon name of current user.
&p Process Id of the current process.

E.g. setting the log file name to /tmp/pkcs11.&u.&p.log creates a log file /tmp/pkcs11.user23.0123.log assumed that the current user is user23 and the process that created the log file has the process id 0123.

P11LogLevel can be used to set the log level to one of the values defined in the table below.

Level Meaning Description
0 No Logging No logging is written.
1 Minimal An absolute minimum of logging information is written.
2 Error Critical errors and exceptions are logged.
3 Warning Critical errors, exceptions, and warnings are logged.
4 Additional Information Critical errors, exceptions, warnings and additional information are logged.
5 Trace API external function call arguments are logged.
6 Debug Additional internal debugging information is written. This is the recommended log level that should be used if you attach log files to an error report.
7 ASN.1 ASN.1 structures read from the smart card are logged. This setting increases the size of your log files significantly. It is not recommended to use this log level unless requested by your support contact.

Smart Card Interface Logging

CardOS API smart card interface logging is controlled by the following configuration attributes:

Attribute Description
SCardLogFile Smart card interface log file location.

SCardLogFile can contain the following wildcards:

Wildcard Description
&u Logon name of current user.
&p Process Id of the current process.

PKCS11 Options

Attribute Description
P11Flags See table below for valid flags. Flags are specified as decimal values.
P15ScriptDir Location of the PKCS#15 token initialization scripts required for C_InitToken().

The value given in P11Flags represents various Boolean options. Each available option is represented by a unique integer value (each of them a power of two). To enable more than one option at a time the corresponding values need to be added.

Flag decimal Meaning Description
1 CKR_DEVICE_REMOVED on CKR_PIN_EXPIRED Return CKR_DEVICE_REMOVED instead of CKR_PIN_EXPIRED in case a PIN expired. Some applications are not able to recover from CKR_PIN_EXPIRED. Returning CKR_DEVICE_REMOVED instead of CKR_PIN_EXPIRED puts some of these applications into a safe state. This option can be configured alternatively to option 2.
2 Refresh expired PINs Automatically refresh expired PINs instead of returning CKR_PIN_EXPIRED. In case a PIN expired CardOS API will prompt the user to re-enter the PIN. This option can be configured alternatively to option 1.
4 Reserved Do not configure this option.
8 Reserved Do not configure this option.
16 Minidriver Admin Key Parity CardOS API prior to version 5.2 calculates the parity of the DES3 Minidriver admin key derived by C_InitToken() in a non-standard way (parity adjustment is done using the msb instead of the lsb). Starting with CardOS API V5.2 the parity setting for the admin key is done according to the standard for CardOS V5 smart cards. For reasons of backwards compatibility the non-standard parity setting is still used for all CardOS V4 cards by default. In case this flag is set the standard parity setting is also used for CardOS V4 cards.
32..2^31 Reserved Do not configure these options.

Registering CardOS API PKCS#11 with Third Party Applications

In order to use the CardOS API PKCS#11-module with third party applications (e.g. Firefox, Thunderbird, Adobe Reader) you need to register the new PKCS#11 module with your applications. How this is done depends on the individual application - please refer to the applications documentation.

During the registration process you will usually be prompted for the location of the PKCS#11 module. Depending on the third party application you either need to specifiy the name of the dynamic library module or a Mac OS X bundle name.

The dynamic library module name for the CardOS API PKCS#11 module is:

libcardos11.dylib

The Mac OS X bundle name for the CardOS API PKCS#11 module is:

CardOSAPIPKCS11.bundle

The default installation path for the CardOS API PKCS#11 module is /usr/local/lib.

Removing CardOS API

CardOS API for Mac OS X does not provide an automated uninstall routine. To remove CardOS API from your system delete all files copied to your system during installation. The installed files are listed in the installation manual of the respective CardOS API version.




Edition 12/2012

© Atos IT Solutions and Services GmbH 2012 Alle Rechte vorbehalten.