QuickStart – OpenCT

# A quick installation guide to openct

Please read OperatingSystems page first for the general concept and problems and then come back here for step by step instructions. Thanks.

To install openct, please do as user,

    $ wget http://www.opensc-project.org/files/openct/openct-0.6.16.tar.gz
    $ tar xfvz openct-0.6.16.tar.gz
    $ cd openct-0.6.16

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

This will install openct in /usr, but put the config file into /etc. The configure out put is quite long, with many tests for software, versions and so on. At the end a summary is printed, it should look like this:

OpenCT has been configured with the following options

    User binaries:       ${exec_prefix}/bin
    Configuration files: /etc

    Host:                i686-pc-linux-gnu
    Compiler:            gcc
    Compiler flags:      -Wall -g -O2
    Preprocessor flags:  -I${top_builddir}/src/include -I${top_srcdir}/src/include
    Linker flags:
    Libraries:           -lpthread

    PC/SC support:       yes
    Libusb used:         yes

To use usb tokens and readers, libusb support is highly recommended. PC/SC support is only useful, if you want to use openct drivers with applications other than opensc, using the pcsc-lite middleware. This author does only use openct with opensc and thus would not need PC/SC support.

Please note that OpenCT uses pkg-config to find libusb and pcsc-lite. pkg-config should be installed, and - if necessary - PKG_CONFIG_PATH environment set to directories with the *.pc files, like /usr/lib/pkgconfig/. If you cannot install pkg-config or for some reason you want to use a version of e.g. libusb that has no pkg-config file, you can work around this problem by setting environment variables, for example LIBUSB_CFLAGS="-I/path/to/your/libusb/include" and LIBUSB_LIBS="-L/path/to/your/libusb/lib -lusb". This will also work if your pkg-config files are broken for some reason.

    $ make
    $ su root

and as root

    # make install

will install all the files.

At system boot, openct needs to create a status file and start a process for every permanent connected reader. For this you need to install the init script into /etc/init.d/ and create startup and shutdown symlinks.

    # cp etc/init-script /etc/init.d/openct
    # ln -s ../init.d/openct /etc/rc0.d/K50openct
    # ln -s ../init.d/openct /etc/rc1.d/S50openct
    # ln -s ../init.d/openct /etc/rc2.d/S50openct
    # ln -s ../init.d/openct /etc/rc3.d/S50openct
    # ln -s ../init.d/openct /etc/rc4.d/S50openct
    # ln -s ../init.d/openct /etc/rc5.d/S50openct
    # ln -s ../init.d/openct /etc/rc6.d/K20openct

This init script will create the directory /var/run/openct/ when run. If you want to restrict access to openct, it might be best to edit the init script. We have put the mkdir command in the init script, as some distributions use a tmpfs on /var/run/ and thus all files and directories in it vanish after a reboot.

Openct also supports hotplugging. If properly configured you can simply plugin a usb smart card reader and instantly access it, or remove it. Beware: never remove a smart card reader or usb crypto dongle while someone is using it. Incomplete transactions can leave some smart cards confused up to the point of being unusable. This is rare, but it happends (especially while a card is initialized).

Over the time different mechanisms were developed for hotplugging - how the kernel can get the message "here is a new usb device" to the user space application that can make good use of it. OpenCT now suggests to use hald for this, as most distributions prefer this way and favor it.

     mkdir -p /usr/share/hal/fdi/information/10freedesktop/
    cp etc/openct.fdi /usr/share/hal/fdi/information/10freedesktop/10-usb-openct.fdi
    cp openct-policy.fdi /usr/share/hal/fdi/policy/10osvendor/10-usb-openct.fdi
    cp etc/openct.hald /usr/lib/hal/hald-addon-openct # distro dependent
    chmod 0755 /usr/lib/hal/hald-addon-openct # needs to be executable

Note that hald setup does not support readers in pcmcia or pc-card so far. But for usb it was tested and is working fine.

See OperatingSystems for more details and information on other operating systems.

Finaly, openct needs a config file to work correctly.

    cp etc/openct.conf /etc/openct.conf

if you have serial readers (or anything else, not hotplugged), edit /etc/openct.conf and configure your reader. Here is an example for a Towitoko reader connected to the first serial port:

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

Now attach all those serial readers and start openct. Hotplug readers already attached will be found as well, but you can as well attach them later.

    /etc/init.d/openct start

now you can test it as user:

    openct-tool list
      0 Towitoko Chipdrive Micro
      1 Schlumberger E-Gate

As you can see I have a normal, serial reader (Towitoko Chipdrive Micro) and one usb token. If I remove the usb token, it will no longer be listed. If I add a new token, the new one will show up:

    openct-tool list
      0 Towitoko Chipdrive Micro
      1 Aladdin eToken PRO

I tested this on systems with several usb ports, too. But this "screen shot" is from a system with only one usb port, my old laptop.

If you have a card in the reader, you can get the answer to reset ("ATR"), which is a byte string containing some parameters, but can be used very well to identify a card. Default is reader 0, add "-r 1" to use reader 1.

    openct-tool -r 1 atr
    Detected Aladdin eToken PRO
    Card present, status changed
    ATR: 3b e2 00 ff c1 10 31 fe 55 c8 02 9c

and similar commands. openct is ready.