<?xml version="1.0" encoding="utf-8" ?>
<book ns="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" id="openct">
	<title>OpenCT Manual</title>
	<bookinfo>
		<author>
			<firstname>Andreas</firstname>
			<surname>Jellinghaus</surname>
			<email>aj@dungeon.inka.de</email>
		</author>
	</bookinfo>

	<toc />

	<chapter id="openct.about">
		<title>About OpenCT</title>

		<para>
			This is OpenCT, a middleware framework for smart card
			terminals.
		</para>

		<para>
			It all started with a reader driver library - Olaf Kirch
			wanted to write a library to provide a framework for
			people writing drivers for smart card readers. The idea
			was to provide all the usual stuff (T=0, T=1, serial
			vs. USB device handling, etc) in a single place, and
			reduce driver writing to interaction with the device
			itself.
		</para>

		<para>
			OpenCT provides a native OpenCT, CT-API and PC/SC Lite IFD interface with
			an OpenCT ifdhandler resource manager.
		</para>

		<para>
			OpenCT is an open source implementation providing card
			terminal drivers. OpenCT was written by Olaf Kirch
			<email>okir@suse.de</email> with contributions
			from the following people:
		</para>

		<itemizedlist>
			<listitem>
				The checksum code for T=1 (src/ifd/checksum.c)
				was taken from Matthias Bruestle's excellent
				SCEZ library.
			</listitem>

			<listitem>
				The e-gate and CCID drivers were contributed,
				and are copyright by, Chaskiel Grundman
				<email>cg2v@andrew.cmu.edu</email>
			</listitem>

			<listitem>
				The eToken, Eutron and Rainbow iKey drivers are
				based on code written by Andreas Jellinghaus
				<email>aj@dungeon.inka.de</email>
			</listitem>

			<listitem>
				Markus Friedl helped with the *BSD port.
			</listitem>

			<listitem>
				Support for Solaris was contributed by
				William Wanders.
			</listitem>

			<listitem>
				Thanks to Ville Skyttä for help with
				the documentation.
			</listitem>
		</itemizedlist>
	</chapter>

	<chapter id="openct.copyright">
		<title>Copyright and license</title>

		<para>
			Most of OpenCT is copyright by Olaf Kirch <email>okir@suse.de</email>
			under BSD license, but see every source file for the individual authors.
		</para>
	</chapter>

	<chapter id="openct.supported">
		<title>Supported readers and tokens</title>

		<variablelist>
			<varlistentry>
				<term><ulink url="http://www.chipdrive.de/cgi-bin/edcstore.cgi?user_action=detail&amp;catalogno=P209005">Towitoko CHIPDRIVE micro</ulink></term>
				<listitem>
					A cheap and very popular smart card
					reader for the serial interfaces
					manufactured by
					<ulink url="http://www.towitoko.de/">
					Towitoko AG</ulink>. Fully supported.
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><ulink url="http://www.kobil.de/e/index.php?s=smartcard">KOBIL KAAN Professional</ulink></term>
				<listitem>
					A smart card reader by <ulink
					url="http://www.kobil.de/indexe.html">
					KOBIL Systems</ulink>
					for the serial interfaces. Fully supported.
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><ulink url="http://www.readers.slb.com/Products/e-gate/e-gate.html">Schlumberger e-gate</ulink></term>
				<listitem>
					A USB token / smart card reader from
					<ulink url="http://www.readers.slb.com/">Schlumberger</ulink>.
					It was only tested with
					Schlumberger cyberflex 32k cards.
					FIXME: I don't know if that adapter
					should work with other cards as well.
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><ulink url="http://www.ealaddin.com/etoken/pro/usb.asp">Aladdin eToken PRO USB</ulink></term>
				<listitem>
					A USB crypto Token by <ulink
					url="http://www.ealaddin.com/">
					Aladdin Knowledge Systems</ulink>.
					Some older versions could have problems
					with non-Intel mainboards. Except for
					that issue: Fully supported.
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><ulink url="http://www.cryptoidentity.eutron.com/">Eutron CryptoIdentity IT-SEC</ulink></term>
				<listitem>
					A USB crypto Token by <ulink
					url="http://www.eutron.com/">Eutron</ulink>.
					Fully supported.
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><ulink url="http://www.rainbow.com/products/ikey/">Rainbow iKey 3000</ulink></term>
				<listitem>
					A USB crypto Token by <ulink
					url="http://www.rainbow.com/">
					Rainbow Technologies</ulink>.
					Fully supported.
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><ulink url="http://www.omnikey.com/en/kat_smartcard.php?katid=1">OMNIKEY CardMan</ulink></term>
				<listitem>
					A USB smart card reader. Not fully working as of yet.
				</listitem>
			</varlistentry>
		</variablelist>
	</chapter>


	<chapter id="openct.requirements">
		<title>Requirements</title>

		<para>
			To use OpenCT with smart card readers attached to
			the serial port, you only need a kernel with
			a working serial port, nothing special is required.
		</para>

		<para>
			To use OpenCT with smart card readers attached
			via USB you need a bit more: your kernel needs
			to support the USB controller you are using. On
			most computers the USB controller is part of the
			mainboard. If your mainboard uses Intel chips
			you need most likely the "uhci" USB controller
			support, for other vendors most likely the "ohci"
			controller support.
		</para>

		<para>
			FIXME: Add an URL to a generic USB HOWTO
		</para>

		<para>
			You also need to compile your kernel with support for
			the USB device filesystem and mount the filesystem
			to <filename>/proc/bus/usb</filename>. The kernel
			option is CONFIG_USB_DEVICEFS, please turn it on.
			To mount the filesystem, please edit your
			<filename>/etc/fstab</filename>. For a Linux kernel
			2.4.* system, it should have a line
			<screen>
none	/proc/bus/usb	usbdevfs	defaults	0	0
			</screen>
			and for a Linux kernel 2.5.* or 2.6.* system, it should have a line:
			<screen>
none	/proc/bus/usb	usbfs		defaults	0	0
			</screen>
		</para>

		<para>
			Run <prompt>mount -a </prompt> after editing the
			file <filename>/etc/fstab</filename> for the changes
			to take effect. You can also reboot. If you are using
			sometimes Linux kernels 2.4.* and sometimes
			2.5.*/2.6.*, use the line for kernel 2.4.*. You will
			get a warning, but it will still work.
		</para>

		<para>
			Your kernel also needs to be compiled with hotplugging
			support. The relevant kernel option is CONFIG_HOTPLUG.
			You don't need any of the hardware adapters.
		</para>
	</chapter>

	<chapter id="openct.install">
		<title>Installation</title>

		<para>
			First, you need to build the OpenCT libraries
			and utilities. You do this by first invoking
			the configure script, for instance
			<screen>
% ./configure --prefix=/usr --sysconfdir=/etc
			</screen>
		</para>

		<para>
			This will try configure OpenCT so it is
			installed below <filename>/usr</filename>,
			and so that it expects its configuration
			file <filename>/etc</filename>. If you omit
			the "--sysconfdir" option, OpenCT will
			look for the configuration file in
			<filename>$PREFIX/etc</filename>.
		</para>

		<para>
			Next, you need to compile and install
			all libraries and utilities using
			<screen>
% make
% make install
			</screen>
		</para>

		<para>
			Once that has completed, create the directory
			<filename>/var/run/openct</filename> and set the
			permissions. Do this with the commands:
			<screen>
# mkdir /var/run/openct
# chmod 755 /var/run/openct
			</screen>
		</para>

		<para>
			These default permissions will allow everyone
			on your system to use smart card readers
			available via OpenCT. For details and a more
			restrictive setup, please consult the
			<link linkend="openct.security">chapter
			on Security</link>.
		</para>

		<para>
			Next, you need the configuration file
			<filename>openct.conf</filename>.
			The exact location of the file depends
			on how you invoked the
			<filename>configure</filename> script, but
			using the options shown above, the file
			should go to <filename>/etc</filename>:
			<screen>
# cp etc/openct.conf /etc/
			</screen>
		</para>

		<para>
			You need to edit the config file for any serial
			reader you might have. If you are only using
			USB tokens, the default file is already fine.
		</para>

		<para>
			Third you need an init script to perform some
			operations on startup and shutdown. OpenCT
			ships with an init script that should work
			at least on Debian systems.
			Install the script by copying it from the
			source directory:
			<screen>
# cp etc/init-script /etc/init.d/openct
			</screen>
		</para>


		<para>
			Now configure your runlevels to start the init
			script every time the system boots, and to stop
			the init script every time the system shuts down.
			Use whatever your distribution provides or a
			GUI tool like the KDE runlevel editor.
		</para>

		<para>
			Debian users can do this with a single command:
			<screen>
# update-rc.d openct start 99 2 3 4 5 . stop 01 0 1 6 .
 Adding system startup for /etc/init.d/openct ...
   /etc/rc0.d/K01openct -> ../init.d/openct
   /etc/rc1.d/K01openct -> ../init.d/openct
   /etc/rc6.d/K01openct -> ../init.d/openct
   /etc/rc2.d/S99openct -> ../init.d/openct
   /etc/rc3.d/S99openct -> ../init.d/openct
   /etc/rc4.d/S99openct -> ../init.d/openct
   /etc/rc5.d/S99openct -> ../init.d/openct
#
			</screen>
		</para>

		<para>
			Call the init script once with "start".
			Or reboot. :-)
			<screen>
# /etc/init.d/openct start
			</screen>
		</para>

		<para>
			And now the last task: if you want to use
			USB readers or USB crypto tokens, you need
			to configure the hotplug system to call
			openct every time there is a new smart
			card reader or crypto token. The future
			releases will work better without hotplug
			scripts because of multi-OS support issues.
			For now, we recommend you to install Linux
			hotplug package before installing OpenCT.
			After that, the standard install mechanism
			should add all required files correctly
			to directory <filename>/etc/hotplug</filename>.
		</para>
	</chapter>

	<chapter id="openct.debug">
		<title>Debugging</title>

		<para>
			Edit <filename>openct.conf</filename>
			and set debug to 4.
		</para>

		<para>
			If the problem is with some USB crypto token,
			please grep for usb_control - these are the
			lines we need to see what is happening.
		</para>

	</chapter>

	<chapter id="openct.files">
		<title>OpenCT files and tools</title>

		<para>
			This chapter will list all tools and files and
			explain what they do.
		</para>

		<section id="openct.files.varrunopenct">
			<title>/var/run/openct - OpenCT status directory</title>

			<para>
				This directory holds status files for OpenCT.
				Create it with: <screen>
mkdir /var/run/openct
chmod 755 /var/run/openct
				</screen>
			</para>

			<para>
				By default everyone can use smart cards via
				OpenCT. You can create a group "openct", assign
				users to that group, and limit access to
				smart cards via openct like this:
				<screen>
chgrp openct /var/run/openct
chmod 750 /var/run/openct
				</screen>
			</para>
		</section>

		<section id="openct.files.sbinopenctcontrol">
			<title>sbin/openct-control - OpenCT manager</title>

			<para>
				Run openct-control once to setup the
				<filename>status</filename> file in
				<filename>/var/run/openct</filename>.
				Without that file OpenCT will not work.
			</para>

			<para>
				<screen>
# /usr/sbin/openct-control
usage: openct-control [-d] [-f configfile] command
  -d   enable debugging; repeat to increase verbosity
  -n   disable coldplugging
  -f   specify config file (default /etc/openct.conf)
  -h   display this message

Where command is one of:
init - initialize OpenCT
attach device ident - attach a hotplug device
status - display status of all readers present
shutdown - shutdown OpenCT
				</screen>
			</para>
		</section>

		<section id="openct.files.sbinifdhandler">
			<title>sbin/ifdhandler - OpenCT device handler</title>

			<para>
				This app is called by openct-control to handle
				one device, e.g. a smart card reader or an USB
				token.
			</para>

			<para>
				<screen>
# /usr/sbin/ifdhandler
usage: ifdhandler [-Hds] [-r reader] driver [device]
  -r   specify index of reader
  -F   stay in foreground
  -H   hotplug device, monitor for detach
  -s   send error and debug messages to syslog
  -d   enable debugging; repeat to increase verbosity
  -h   display this message
				</screen>
			</para>
		</section>

		<section id="openct.files.opencttool">
			<title>bin/openct-tool</title>

			<para>
				<screen>
# /usr/bin/openct-tool
usage: openct-tool [-d] [-f configfile] [-r reader] command ...
  -d   enable debugging; repeat to increase verbosity
  -f   specify config file (default /etc/openct.conf)
  -r   specify index of reader to use
  -h   display this message

command: can be one of the following
 list  list all readers found
 atr   print ATR of card in selected reader
 wait  wait for card to be inserted
 rwait wait for reader to attached
 mf    try to select main folder of card
 read  dump memory of synchronous card
				</screen>
			</para>
		</section>

		<section id="openct.files.openctconf">
			<title>etc/openct.conf</title>

			<para>
				<screen>
# Set debug level
debug	= 0;
#
# Enable hot plugging
hotplug	= yes;
#
# Path to ifdhandler
ifdhandler = /usr/sbin/ifdhandler;

#
# Configuration for ifdproxy (if you use it)
ifdproxy {
#	server-port     = /var/run/openct/.ifdproxy,
#	device-port     = :6666;
};

# Configure static, non-hotplug aware readers here
#
# For a list of drivers try command 'ifdhandler -i', please
# notice that not all drivers have serial device capability.

#reader towitoko {
#	driver = towitoko;
#	device = serial:/dev/ttyS0;
#};

#
# Hotplug IDs
driver	egate {
	ids = {
		usb:0973/0001,
	};
};
driver	etoken {
	ids = {
		usb:0529/050c,
		usb:0529/0514,
	};
};
driver	eutron {
	ids = {
		usb:073d/0005,
	};
};
driver	ikey2k {
	ids = {
		usb:04b9/1202,
	};
};
driver	ikey3k {
	ids = {
		usb:04b9/1300,
	};
};
driver	cardman {
	ids = {
		usb:076b/0596, # OMNIKEY CardMan 2020
		usb:076b/1784, # OMNIKEY CardMan 6020
		usb:08d4/0009, # Fujitsu Siemens SCR USB SmartCard Reader
	};
};
driver	ccid {
	ids = {
		usb:08e6/3437,
		usb:08e6/3438,
		usb:08e6/4433,
		usb:04e6/5115,
		usb:04e6/E001,
		usb:04e6/E003,
		usb:076b/3021,
		usb:0783/0003,
	};
};
				</screen>
			</para>
		</section>
	</chapter>

	<chapter id="openct.ct-api">
		<title>Using OpenCT via CT-API interface</title>

		<para>
			Install and configure the file
			<filename>/etc/openct.conf</filename> as discussed.
			Configure your CT-API application to load
			<filename>lib/libopenctapi.so</filename>.
		</para>
	</chapter>

	<chapter id="openct.pcsc">
		<title>Using OpenCT via PC/SC Lite</title>

		<para>
			Install and configure the file
			<filename>/etc/openct.conf</filename> as discussed.
			Configure PC/SC Lite /etc/reader.conf to load <filename>lib/openct-ifd.so</filename>.
		</para>

		<para>
			<screen>
FRIENDLYNAME     "OpenCT"
DEVICENAME       OPENCT_DEV
LIBPATH          /usr/lib/openct-ifd.so
CHANNELID        1
			</screen>
		</para>

	</chapter>

	<chapter id="openct.library">
		<title>Writing smart card applications using OpenCT</title>

		<para>
			OpenCT has a proprietary, but very easy to use
			interface. Take a look at the header files
			<filename>include/openct/*.h</filename> and
			the library <filename>lib/libopenct.*</filename>.
		</para>

		<para>
			If your application uses autoconf, we made
			it easy for you to search for OpenCT and
			link with libopenct by shipping OpenCT with
			a pkg-config file:
			<filename>lib/pkg-config/libopenct.pc</filename>
		</para>

		<para>
			See the pkg-config man page for detailed information.
		</para>
	</chapter>

	<chapter id="openct.trouble">
		<title>Troubleshooting</title>

		<para>
			If something does not work, please join the OpenSC
			mailing list and ask for help. For details on the
			mailing list take a look at <ulink
				url="http://www.opensc.org/" />
		</para>

		<para>
			If you try to use a USB device, please try this:
			Do you have a <filename>/proc</filename> filesystem?
			This command should work:
			<prompt>ls /proc/sys</prompt>
		</para>

		<para>
			Is your kernel compiled with USB support? Does the
			USB support work? This command should list all
			USB devices:
			<prompt>lsusb</prompt>
		</para>

		<para>
			Is your kernel compiled with hotplugging support?
			This command give the same output on your system:
			<screen>
% cat /proc/sys/kernel/hotplug
/sbin/hotplug
%
			</screen>
		</para>

		<para>
			Do you have a hotplug script?
			This command should work:
			<prompt>ls /sbin/hotplug</prompt>
		</para>

		<para>
			Did you create the directory
			<filename>/var/run/openct</filename>? What files are in
			there? What are the file permissions?
			Try this command, it should work and give you a
			similar output:
			<screen>
% ls -la /var/run/openct/
total 8
drwxr-xr-x    2 root     root         4096 2003-07-02 08:13 ./
drwxr-xr-x    8 root     root         4096 2003-07-02 08:13 ../
-rw-r--r--    1 root     root         1728 2003-07-02 08:13 status
%
			</screen>
			See the <link linkend="openct.security">security
			chapter</link> for details on file permissions
			of this directory.
		</para>

		<section id="openct.trouble.usb">
			<title>Problems with USB devices</title>
		<para>
			Are you using an USB smart card reader or
			USB crypto token? What is it's USB vendor and
			product id? <prompt>lsusb</prompt> will tell you.
		</para>

		<para>
			Is that product id listed in
			<filename>openct.conf</filename>? If not, please
			add it.
		</para>

		<para>
			If you have a file
			<filename>/etc/hotplug/usb/openct.usermap</filename>, is the
			vendor and product id listed in that file?
		</para>

		<para>
			If that solves the problem, please let the OpenCT
			developers know, so we can improve the default
			configuration and documentation. You can reach
			us using the OpenSC developer mailing list at
			<email>opensc-devel@opensc.org</email>.
		</para>

		</section>
	</chapter>

	<chapter id="openct.security">
		<title>Security</title>

		<para>
			The default setting is not very secure: all users
			can access your smart card readers. Several processes
			can use the same smart card reader at the same time,
			but they always have to be owned by the same users.
			(FIXME: is it necessary to issue a LOCK command for
			this, or will it always work like this?)
		</para>

		<para>
			You can restrict access to smart card readers using
			OpenCT to one user with these
			commands:
			<screen>
# chown user /var/run/openct
# chmod 700 /var/run/openct
			</screen>
		</para>

		<para>
			You can also create a group, add users to that group
			and restrict access to smart card readers using OpenCT
			to that group with these commands:
			<screen>
# chgrp group /var/run/openct
# chmod 750 /var/run/openct
			</screen>
		</para>

		<para>
			In both cases root can still access the smart
			card readers. Replace <replaceable>user</replaceable>
			and <replaceable>group</replaceable> with the user
			and group of your choice.
		</para>

		<para>
			If you want all users to be able to access smart card
			readers using OpenCT:
			<screen>
# chmod 755 /var/run/openct
			</screen>
		</para>
	</chapter>
</book>