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