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

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

Smart Card Readers

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
Mozilla1.7.7SSL Client Authentication
FireFox1.0SSL Client Authentication
Thunderbird1.0Secure eMail (Signature & Encryption)
Netscape7.2SSL 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/binsiecapinN/aHiPath SIcurity Card API PIN Management Utility
(Documentation)
/usr/local/liblibsiecacrd.soN/aHiPath SIcurity Card API Card Interface Library
libsiecadlg.soN/aHiPath SIcurity Card API GUI Library
libsiecap11.soN/aHiPath SIcurity Card API PKCS#11 Library
libsiecap15.soN/aHiPath SIcurity Card API PKCS#15 Library
/etcsieca.confN/aHiPath SIcurity Card API configuration file.
(see Configuration on Linux)
/usr/local/sieca/doc/Images*.gifN/aImages and icons.
/usr/local/sieca/doc/LinuxReadMe.Linux.htmlN/aHiPath SIcurity Card API for Linux Readme
/usr/local/sieca/doc/Linux/docPKCS11PinUtilityLinux.htmlN/aHiPath SIcurity Card API PIN Management Utility documentation.
/usr/local/sieca/doc/Linux/doc/screens*.gifN/aHiPath SIcurity Card API PIN Management Utility documentation screen shots.
/usr/local/sieca/scriptsInitTokenC802.cpdN/aInitialization script for CardOS/M4.00 cards.
InitTokenC802.sigN/aSignature file for InitTokenC802.cpd.
InitTokenC803.cpdN/aInitialization script for CardOS/M4.01 cards.
InitTokenC803.sigN/aSignature file for InitTokenC803.cpd.
InitTokenC804.cpdN/aInitialization script for CardOS/M4.01a cards.
InitTokenC804.sigN/aSignature file for InitTokenC804.cpd.
InitTokenC805.cpdN/aInitialization script for CardOS/M4.10 cards.
InitTokenC805.sigN/aSignature file for InitTokenC805.cpd.
InitTokenC806.cpdN/aInitialization script for CardOS V4.2 cards.
InitTokenC806.sigN/aSignature file for InitTokenC806.cpd.
InitTokenC806.rsa2048.cpdN/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.sigN/aSignature file for InitTokenC806.rsa2048.cpd.
InitTokenC807.cpdN/aInitialization script for CardOS V4.3 cards.
InitTokenC807.sigN/aSignature file for InitTokenC807.cpd.
InitTokenC808.cpdN/aInitialization script for CardOS V4.3B cards.
InitTokenC808.sigN/aSignature 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
P11LogFilePKCS#11 log file location.
P11LogLevelPKCS#11 logging level (1..5).
P11ScriptDirLocation of the PKCS#11 token initialization scripts required for C_InitToken().
SCardLogFileSmart 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:

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.


(*) To support RSA 2048 bit signatures PC/SC Lite v1.2.9beta6 (or above) must be configured with the parameter --enable-extendedapdu at compile time in order to support extended APDUs.


HiPath, SIcurity, CardOS are registered trademarks of Siemens AG.
Linux is a registered trademark of Linus Torvalds in several countries.
Linux penguin logo created by Larry Ewing.
All other trademarks mentioned herein are the property of their respective owners.

Copyright © Siemens AG 2005. All rights reserved.