Humboldt-Universität zu Berlin - Computer- und Medienservice

Installation Mac OS X

HiPath Slcurity Card API V3.1 - PKCS#11 for Mac OS X


System Prerequisites
Supported Applications
Installation
Configuration
Registering Card API PKCS#11 with Third Party Applications
Starting the PC/SC Service during Mac OS X System Startup

System Prerequisites

The HiPath SIcurity Card API PKCS#11 Library for Mac OS X has been tested on the following system configuration:

Mac OS X 10.3 (Panther)

System

  • Apple Power Mac G4 with Mac OS X 10.3 (all patches applied)
  • Java Runtime Environment 1.2 or above (Java Environment 1.4 as currently shipped with Mac OS X 10.3 fits this prerequisite)
  • PC/SC Lite v1.1.2 (As shipped with Mac OS X 10.3 )
    The PC/SC service is usually not started automatically during Mac OS X system startup. Please refer below on how to include the PC/SC service into the Mac OS X start up scripts.

Smart Card Readers

Mac OS X 10.4 (Tiger)

System

  • Apple Power Mac G4 with Mac OS X 10.4 (all patches applied)
  • Java Runtime Environment 1.2 or above (Java Environment 1.4 as currently shipped with Mac OS X 10.3 fits this prerequisite)
  • PC/SC Lite v1.1.2 (As shipped with Mac OS X 10.4; supports extended APDU)
    Make sure that the PC/SC Lite deamon is running. Otherwise refer to Starting the PC/SC Service during Mac OS X System Startup.

Smart Card Readers

  • OMNIKEY CardMan 2020 USB Driver v1.0.0.5 for Mac OS X
  • OMNIKEY CardMan 3121 CCIDClassDriver v5.0 shipped with Mac OS X 10.4.
    It is recommended to use the preinstalled driver and not needed to install the OMNIKEY USB (CCID) Driver.


warning.gif You should not use the USB connector of your Apple keyboard to connect a smart card reader. This USB port has not been designed to supply sufficient power to a smart card reader. This may either prevent the smart card reader from working at all or lead to malfunctions of the smart card readers. Instead the smart card reader should be connected directly to the system or connected via an additional USB hub.
Make sure that the PCSC Lite deamon is running on your system. For more information refer to the documentation of your distribution.

Supported Applications on Mac OS X

To ensure maximum interoperability the HiPath SIcurity Card API PKCS#11 Library for Mac OS X has been tested with the following PKCS#11 applications available for Mac OS X platforms:

Application Version Use Cases
Mozilla 1.7.7 SSL Client Authentication, Secure eMail (Signature & Encryption)
Netscape 7.2 SSL Client Authentication, Secure eMail (Signature & Encryption)
FireFox 1.0 SSL Client Authentication
Thunderbird 1.0 Secure eMail (Signature & Encryption)

Installation on Mac OS X

Open the HiPath SIcurity Card API installation package in the Mac OS X Finder to start the installation. In case the Finder is not opened automatically you can find the package on the CD at /Mac_OS_X/HiPath_SIcurity_Card_API_<version>_MacOSX.pgk.

The following files will be installed on your system:

Path File Version Description
/Applications/HiPathSIcurityCardAPI ChangePIN.app N/a Shortcut to Change PIN application

ChangePUK.app N/a Shortcut to Change PUK application

UnblockPIN.app N/a Shortcut to Unblock PIN application
/private/etc sieca.conf N/a HiPath SIcurity Card API configuration file
(see Configuration on Mac OS X)
/usr/local/bin siecapin N/a HiPath SIcurity Card API PIN Management Utility
( Documentation)
/usr/local/lib libsiecacrd.dylib N/a HiPath SIcurity Card API Card Interface Library

libsiecadlg.dylib N/a HiPath SIcurity Card API GUI Library

libsiecap11.dylib N/a HiPath SIcurity Card API PKCS#11 Library

libsiecap15.dylib N/a HiPath SIcurity Card API PKCS#15 Library

libiplasn1.dylib ipl3 IPL ASN.1 Library

libiplcsp.dylib ipl3 IPL Crypto Algorithm Library

libiplutils.dylib ipl3 IPL Utility Library
/usr/local/sieca/doc/Images *.gif N/a Images and icons.
/usr/local/sieca/doc/Mac_OS_X ReadMe.MacOSX.html N/a HiPath SIcurity Card API for Mac OS X Readme
/usr/local/sieca/doc/Mac_OS_X/doc PKCS11PinUtilityMacOSX.html N/a HiPath SIcurity Card API PIN Management Utility documentation
/usr/local/sieca/doc/Mac_OS_X/doc/screens *.gif N/a HiPath SIcurity Card API PIN Management Utility documentation screen shots
/usr/local/sieca/lib siecadlg.jar N/a HiPath SIcurity Card API GUI Java Classes
/usr/local/sieca/scripts InitTokenC802.cpd N/a Initialization script for CardOS/M4.00 cards

InitTokenC802.sig N/a Signature file for InitTokenC802.cpd

InitTokenC803.cpd N/a Initialization script for CardOS/M4.01 cards

InitTokenC803.sig N/a Signature file for InitTokenC803.cpd

InitTokenC804.cpd N/a Initialization script for CardOS/M4.01a cards

InitTokenC804.sig N/a Signature file for InitTokenC804.cpd

InitTokenC805.cpd N/a Initialization script for CardOS/M4.10 cards

InitTokenC805.sig N/a Signature file for InitTokenC805.cpd

InitTokenC806.cpd N/a Initialization script for CardOS V4.2 cards

InitTokenC806.sig N/a Signature file for InitTokenC806.cpd

InitTokenC806.rsa2048.cpd N/a Initialization script for CardOS V4.2 cards including RSA 2048bit package.
Rename InitTokenC806.rsa2048.cpd to InitTokenC806.cpd and InitTokenC806.rsa2048.sig to InitTokenC806.sig to include the RSA 2048bit package in the default token initialization sequence run by calling C_InitToken().

InitTokenC806.rsa2048.sig N/a Signature file for InitTokenC806.rsa2048.cpd

InitTokenC807.cpd N/a Initialization script for CardOS V4.3 cards

InitTokenC807.sig N/a Signature file for InitTokenC807.cpd

InitTokenC808.cpd N/a Initialization script for CardOS V4.3B cards

InitTokenC808.sig N/a Signature file for InitTokenC808.cpd


Configuration on Mac OS X

Configuration information is retrieved from the file /private/etc/sieca.conf. The following parameters can be configured:

Parameter Description
P11LogFile PKCS#11 log file location.
P11LogLevel PKCS#11 logging level (1..5).
P11ScriptDir Location of the PKCS#11 token initialization scripts required for C_InitToken().
SCardLogFile Smart card interface log file location.
SCDialogJavaClassPath Java CLASSPATH for smart card dialog GUI components.

Example:

#
# HiPath SIcurity Card API configuration file
#
# Copyright 2005 Siemens AG
# All rights reserved.
#

#
# PKCS#11 logging
#
P11LogFile=/tmp/pkcs11.log
P11LogLevel=4

#
# Scriptfiles for C_InitToken().
#
P11ScriptDir=/usr/local/sieca/scripts/

#
# Smart card interface logging.
#
#SCardLogFile=/tmp/scard.log

#
# CLASSPATH for Java style SCDialog module
#
SCDialogJavaClassPath=/usr/local/sieca/lib/siecadlg.jar

warning.gif Make sure that all users using the PKCS#11 library have sufficient rights to write to the configured log files. Read access to the log files should only be granted to authorized users since the log files may contain sensitive information (decryption results, PIN values, ...).


Registering Card API PKCS#11 with Third Party Applications

In order to use the HiPath SIcurity Card API PKCS#11-module with third party applications (e.g. Netscape) 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 dynamic library module name and location. The dynamic library module name for the HiPath SIcurity Card API PKCS#11-module is:

libsiecap11.dylib

By default this dynamic library will be installed to /usr/local/lib.

Starting the PC/SC Service during Mac OS X System Startup

As long as the PC/SC Service is not started automatically during system startup on Mac OS X 10.3 you will need to start the service manually running 'sudo /usr/sbin/pcscd' from a command line. As this may prove rather inconvinient the following description should give some hints on how to start the PC/SC Service automatically. Please refer to your Mac OS X system documentation for more detailed information on the Mac OS X system startup and how it can be adjusted to meet your specific needs.

In order to automatically start the PC/SC Service during Mac OS X system startup you should create the directory /Library/StarupItems/PCSC and place the following files in it:

/Library/StartupItems/PCSC/PCSC

#!/bin/sh

# Source common setup, including hostconfig.
. /etc/rc.common

StartService( )
{
# Don't start unless PCSC is enabled in /etc/hostconfig
if [ "${PCSC:=-NO-}" = "-YES-" ]; then
ConsoleMessage "Starting PCSC..."
/usr/sbin/pcscd -d syslog &
fi
}

StopService( )
{
ConsoleMessage "Stopping PCSC..."
if [ -e /var/run/pcscd.pid ]; then
kill $(cat /var/run/pcscd.pid)
# Wait for pcscd to shutdown...
while [ -f /var/run/pcscd.pid ]; do sleep 1; done
else
ConsoleMessage "PCSC not running."
fi
}

RestartService( )
{
# Don't restart unless PCSC is enabled in /etc/hostconfig
if [ "${PCSC:=-NO-}" = "-YES-" ]; then
ConsoleMessage "Restarting PCSC..."
StopService
StartService
else
StopService
fi
}

RunService "$1"

The script /Library/StartupItems/PCSC/PCSC must have executable permissions.

/Library/StartupItems/PCSC/StartupParameters.plist

{
Description = "PCSC";
Provides = ("PCSC");
OrderPreference = "Late";
}


You can now use /etc/hostconfig to configure whether the PC/SC Service is started during system startup. Add the line PCSC=-YES- at the bottom of the services section of /etc/hostconfig to start the PC/SC Service. Delete the line or set PCSC=-NO- in case you do not want the PC/SC Service to be started.

Before actually restarting your sytem you can use the commands 'sudo SystemStarter start PCSC' and 'sudo SystemStarter stop PCSC' to test the startup script.