OpenCT Manual

This is OpenCT, a middleware framework for smart card terminals.

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.

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

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

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

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.

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.

FIXME: Add an URL to a generic USB HOWTO

You also need to compile your kernel with support for the USB device filesystem and mount the filesystem to /proc/bus/usb. The kernel option is CONFIG_USB_DEVICEFS, please turn it on. To mount the filesystem, please edit your /etc/fstab. For a Linux kernel 2.4.* system, it should have a line

none    /proc/bus/usb   usbdevfs        defaults        0       0
                        

and for a Linux kernel 2.5.* or 2.6.* system, it should have a line:

none    /proc/bus/usb   usbfs           defaults        0       0
                        

Run mount -aafter editing the file /etc/fstabfor 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.

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.

First, you need to build the OpenCT libraries and utilities. You do this by first invoking the configure script, for instance

% ./configure --prefix=/usr --sysconfdir=/etc
                        

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

Next, you need to compile and install all libraries and utilities using

% make
% make install
                        

Once that has completed, create the directory /var/run/openctand set the permissions. Do this with the commands:

# mkdir /var/run/openct
# chmod 755 /var/run/openct
                        

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 chapter on Security.

Next, you need the configuration file openct.conf. The exact location of the file depends on how you invoked the configurescript, but using the options shown above, the file should go to /etc:

# cp etc/openct.conf /etc/
                        

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.

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:

# cp etc/init-script /etc/init.d/openct
                        

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.

Debian users can do this with a single command:

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

Call the init script once with "start". Or reboot. :-)

# /etc/init.d/openct start
                        

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 /etc/hotplug.

Edit openct.confand set debug to 4.

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.

This chapter will list all tools and files and explain what they do.

mkdir /var/run/openct
chmod 755 /var/run/openct
                                

chgrp openct /var/run/openct
chmod 750 /var/run/openct
                                

# /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
                                

# /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
                                

# /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
                                

# 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,
        };
};
                                

Install and configure the file /etc/openct.confas discussed. Configure your CT-API application to load lib/libopenctapi.so.

Install and configure the file /etc/openct.confas discussed. Configure PC/SC Lite /etc/reader.conf to load lib/openct-ifd.so.

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

OpenCT has a proprietary, but very easy to use interface. Take a look at the header files include/openct/*.hand the library lib/libopenct.*.

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: lib/pkg-config/libopenct.pc

See the pkg-config man page for detailed information.

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 http://www.opensc.org/

If you try to use a USB device, please try this: Do you have a /procfilesystem? This command should work: ls /proc/sys

Is your kernel compiled with USB support? Does the USB support work? This command should list all USB devices: lsusb

Is your kernel compiled with hotplugging support? This command give the same output on your system:

% cat /proc/sys/kernel/hotplug
/sbin/hotplug
%
                        

Do you have a hotplug script? This command should work: ls /sbin/hotplug

Did you create the directory /var/run/openct? What files are in there? What are the file permissions? Try this command, it should work and give you a similar output:

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

See the security chapterfor details on file permissions of this directory.

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?)

You can restrict access to smart card readers using OpenCT to one user with these commands:

# chown user /var/run/openct
# chmod 700 /var/run/openct
                        

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:

# chgrp group /var/run/openct
# chmod 750 /var/run/openct
                        

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

If you want all users to be able to access smart card readers using OpenCT:

# chmod 755 /var/run/openct