HiPath SIcurity Card API V3.1 PKCS#11 for Linux

System Prerequisites
Supported Applications
Installation
Configuration
Registering Card API PKCS#11 with Third Party Applications
Running HiPath SIcurity Card API with a more recent version of PC/SC Lite than 1.2.0

System Prerequisites

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

System

• SuSE Linux 9.1.
• SuSE Linux 9.3.
• PC/SC Lite v1.2.0 - You might need to updated from PC/SC Lite v1.1.1 which is shipped with SuSE Linux 9.1. (Download PC/SC Lite 1.2.0, PGP Signature)
• PC/SC Lite v1.2.9beta6 shipped with SuSE Linux 9.3.(*)
  (see Running HiPath SIcurity Card API with a more recent version of PC/SC Lite than 1.2.0)

HiPath SIcurity Card API PKCS#11 should work on all Linux platforms that meet the following prerequisites:

• Kernel 2.4.21 or above
• glibc 2.3.3 or above
• PC/SC Lite 1.2.0 or above
• XFree86 4.3 or above

Smart Card Readers

• OMNIKEY CardMan 2020 USB Driver for Linux v2.4.0
• OMNIKEY CardMan 3121 USB (CCID) Driver for Linux v1.2.0

Make sure that the PCSC Lite deamon is running on your system. For more information refer to the documentation of your Linux distribution.

Supported Applications on Linux

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

Application	Version	Use Cases
Mozilla	1.7.7	SSL Client Authentication
FireFox	1.0	SSL Client Authentication
Thunderbird	1.0	Secure eMail (Signature & Encryption)
Netscape	7.2	SSL Client Authentication, Secure eMail (Signature & Encryption)
PAM pkcs11_login PAM module	0.77-221 0.3	Linux Logon

Installation on Linux

Extract the HiPath SIcurity Card API tar archive as user root to the root directory of your Linux installation.

user@system > su - Enter password: root@system # cd / root@system # tar -xzvf HiPath_SIcurity_Card_API_<version>.tar.gz root@system # exit

This will install the following files on your system:

Path	File	Version	Description
/usr/local/bin	siecapin	N/a	HiPath SIcurity Card API PIN Management Utility (Documentation)
/usr/local/lib	libsiecacrd.so	N/a	HiPath SIcurity Card API Card Interface Library
	libsiecadlg.so	N/a	HiPath SIcurity Card API GUI Library
	libsiecap11.so	N/a	HiPath SIcurity Card API PKCS#11 Library
	libsiecap15.so	N/a	HiPath SIcurity Card API PKCS#15 Library
/etc	sieca.conf	N/a	HiPath SIcurity Card API configuration file. (see Configuration on Linux)
/usr/local/sieca/doc/Images	*.gif	N/a	Images and icons.
/usr/local/sieca/doc/Linux	ReadMe.Linux.html	N/a	HiPath SIcurity Card API for Linux Readme
/usr/local/sieca/doc/Linux/doc	PKCS11PinUtilityLinux.html	N/a	HiPath SIcurity Card API PIN Management Utility documentation.
/usr/local/sieca/doc/Linux/doc/screens	*.gif	N/a	HiPath SIcurity Card API PIN Management Utility documentation screen shots.
/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.

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.

Configuration on Linux

Configuration information is retrieved from the file /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.

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

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 shared object module name and location. The shared object module name for the HiPath SIcurity Card API PKCS#11-module is:

libsiecap11.so

By default this shared object will be installed to /usr/local/lib.

Running HiPath SIcurity Card API with a more recent version of PC/SC Lite than 1.2.0

The PKCS#11 library libsiecap11.so shipped with HiPath SIcurity Card API has been linked to the library libpcsclite.so.0.0.1 which belongs to PC/SC Lite 1.2.0. When the Linux runtime linker loads the PKCS#11 library it tries to resolve this dependency to libpcsclite.so.0 (only the libraries major version is evaluated). The attempt to resolve this dependency fails since PC/SC Lite 1.2.9betaX contains a later version of libpcsclite.so (libpcsclite.so.1.0.0).

This dependency problem can be worked around with the following steps:

• Search for the directory where libpcsclite.so.1.0.0 is installed on your system (usually /usr/local/lib or /usr/lib).
• Create a new symbolic link named libpcsclite.so.0 to libpcsclite.so.1.0.0 in that directory (ln -s libpcsclite.so.1.0.0 libpcsclite.so.0). Running this ln command will usually require root privileges.

This information is given without any warranty. In tests at our side the solution appeared to work stable with PC/SC Lite 1.2.9beta6.