Operating Systems: General Notes

Operating Systems: General Notes

Serial readers should work fine on all operating systems. USB needs hotplug support, so that you can plugin some new USB device, and if it is a smart card reader, OpenCT needs to be notified. Unfortunatly hotplug on Linux is currently moving from hotplug to udev or hald, so we document all three systems. FreeBSD has devd and no idea about all other systems. Readers in PCMCIA and PC-Card format are experimental and only supported under Linux so far, tested only with the udev setup (but adapting the setup should be easy).

Linux

The current recommended setup is using hal on linux. This way hal will notify openct if a new device is found.
You do not need to compile OpenCT with libusb on linux, it should work well without.

For users prefering a setup with mdev, udev or the old hotplug, we still keep those in our documentation.

hald setup

Hald needs a fdi config file and an addon script it runs when something in the fdi config file matches. To install these files. It is recommended to use separate information and policy fdi files. Installation path for the addon is distro specific and there is no simple way to determine it (see http://bugs.freedesktop.org/show_bug.cgi?id=15768).). It may be /usr/bin, /usr/sbin, /usr/libexec, /usr/libexec/hal, /usr/lib/hal, /usr/lib64/hal, /usr/lib32/hal.

openct daemon needs correct permissions for your smart card device. If your openct daemon is running as root, you don’t have to care about it. Otherwise you have to edit etc/openct.hald and properly set chown and eventually chmod.

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

If you are using hal, don’t install udev rules.

Direct access to device nodes

If required, there are three possible types of policies for direct access to device nodes:

• Only root can access.
• Use standard UNIX UID/GID permissions by editing of /etc/openct.fdi.
• Use UNIX ACL for grating access. Latest hal and openct snapshots support smart-card-reader PolicyKit policy. With such version of hal, direct access is permitted for local users with active terminal.

OpenCT allows those to access smart card via the daemon, that can access the openct socket directory, usualy /var/run/openct. So you can limit access to that directory to a group or a single user if you want.
Several distributions do this by default and limit access to the “scard” group.

Incompatibilities

Different distributions need different setup. Here are most important differences:

• Modern distributions use /dev/bus/usb, older distributions use /proc/bus/usb. You have to check, that your hal provides valid device nodes to the addon.
• In older HAL versions USB is “bus”, not “subsystem”. You have to edit FDI files.
• Device permissions are set in a different way in older distributions (e. g. using resmgr).

PCMCIA and PC-Card readers are not yet supported via hald, advice and patches are very welcome.

Hald documentation is available online at http://people.freedesktop.org/~david/hal-spec/hal-spec.html

Disabling openct addon

If you want to disable openct addon without uninstallation of openct, you can copy etc/openct-disable.fdi to /etc/hal/fdi/policy/.

mdev setup

mdev is provided by busybox to handle hotplug events as udev replacement. It is handy for initramfs configurations.

In order to setup configuration:

• Configure busybox with CONFIG_MDEV, CONFIG_FEATURE_MDEV_CONF, CONFIG_FEATURE_MDEV_EXEC.
• Copy etc/openct_usb.mdev from build output to your initramfs at /lib/mdev/openct_usb.
• Create /etc/mdev.conf at your initramfs with the following content:
  

  .* 0:0 0660 /lib/mdev/openct_usb
  

• For simple installation, copy the following files into your initramfs, and all dependencies.
  

  /usr/sbin/openct-control
  /usr/sbin/ifdhandler
  /etc/openct.conf
  

udev Setup

Serial support needs nothing special (only the serial driver for your serial device), but USB support on Linux has a few requirements:

• libusb needed during compilation and runtime.
• CONFIG_HOTPLUG so the kernel can let us know if you plug in a reader or token.
• udev needs to be installed. This comes with your distribution, and you are advised
  not to install or update it yourself.

OpenCT before 0.6.13 also needs:

• CONFIG_USB_DEVICEFS so we can talk to USB devices from userspace.
• mount usbfs (kernel 2.4: usbdevfs) at /proc/bus/usb, to do that put this line into your /etc/fstab:
  

  usbfs           /proc/bus/usb   usbfs   defaults                0       0
  

  
  (replace “usbfs” with “usbdevfs” for Linux kernel 2.4.* – will work on kernel 2.6.* too)

Also the udev files need to be installed (see QuickStart for full installation instructions):

# cp etc/openct.udev /etc/udev/rules.d/50-openct.rules

	
cp etc/openct_usb /lib/udev/openct_usb
	
cp etc/openct_pcmcia /lib/udev/openct_pcmcia
	
cp etc/openct_serial /lib/udev/openct_serial

Some common problems with udev:

• kernel versions and udev rules do not fit. Several kernels required new udev versions, so updating
  the kernel without udev will not work. Updating udev is something you shouldn’t do yourself, best
  use the distribution udev. As a result you cannot update the kernel or need to update your whole
  distribution.
• For a long time every distribution had usbfs mounted on /proc/bus/usb. Some stopped doing that and
  thus broke OpenCT. This is fixed in OpenCT 0.6.13+. Note: OpenSuse uses hal for connecting Linux kernel
  and OpenCT and thus should work without usbfs mounted on /proc/bus/usb.
• Ubuntu 7.04 (“feisty”) and maybe also older versions had usbfs mounted on /proc/bus/usb/.usbfs and
  a bind mount from /dev/bus/usb to /proc/bus/usb. This broken OpenCT as the device we wanted to open
  was always created too late. OpenCT 0.6.12 has added a work around for this. Ubuntu 7.10 will drop this
  practice (but maybe not have /proc/bus/usb at all).
• Linux Kernel 2.6.22 has changes to the USB code that result in some uevents missing PRODUCT and TYPE
  and DEVICE information. This will be fixed in 2.6.23 and 2.6.22.5. Please update your kernel.
• Linux Kernel 2.6.22+ has a new option CONFIG_USB_DEVICE_CLASS, which is marked deprecated. As long as
  it is on everything is fine. But if turned off there could be problems. This option doesn’t harm OpenCT
  per se, but might break your udev code to generate /dev/bus/usb/xxx/yyy devices. As a result libusb
  will not find any device (because /dev/bus/usb exists it doesn’t look at /proc/bus/usb even if that one
  is fine), and thus also our coldplug code run by “/etc/init.d/openct start” breaks.
• People could compile their kernel without the CONFIG_USB_DEVICEFS option. This option was only needed for
  usbfs, and some might think with /dev/bus/usb it is no longer needed to have usbfs on /proc/bus/usb. But
  without this option the kernel also doesn’t add the DEVICE information to the kernel events, and thus
  OpenCT can be notified by udev about new devices, but will not have the name of the new device and thus
  cannot process this information. OpenCT 0.6.13+ can work without CONFIG_USB_DEVICEFS.
• udev has a mechanism as alternative to DEVICE, it is called DEVNAME. But it only works with the proper udev
  rules and on many distributions those are not in place, resulting in DEVNAME like /dev/2-1.7 – something
  OpenCT can’t work with. A proper udev rules looks like this:
  

    SUBSYSTEM=="usb", ACTION=="add", ENV{DEVTYPE}=="usb_device", \
      NAME="bus/usb/$env{BUSNUM}/$env{DEVNUM}", MODE="0644"
  

  
  OpenCT 0.6.13+ has this rule and a modified script so we can construct the device name from udev information
  stored from a previous event and read by udevinfo later.

Hotplug Setup

Serial support needs nothing special (only the serial driver for your
serial device), but USB support on Linux has a few requirements:

• libusb needed during compilation and runtime.
• CONFIG_HOTPLUG so the kernel can let us know if you plugin a reader or token.
• hotplug utilities will be called by the kernel and run openct.
• CONFIG_USB_DEVICEFS so we can talk to USB devices from userspace.
• mount usbfs (kernel 2.4: usbdevfs) at /proc/bus/usb, to do that put this line into your /etc/fstab:
  

  usbfs           /proc/bus/usb   usbfs   defaults                0       0
  

  
  (replace “usbfs” with “usbdevfs” for Linux kernel 2.4.* – will work on kernel 2.6.* too)

Also the hotplug files need to be installed (see QuickStart for full installation instructions):

# cp etc/openct.usermap /etc/hotplug/usb/openct.usermap

	
cp etc/openct_usb /etc/hotplug/usb/openct

FreeBSD

On FreeBSD
1. Install from ports

• security/openct
• security/opensc
  move the configuration files in place and add the right flags to rc.conf:
  

  cp /usr/local/etc/opensc.conf-sample /usr/local/etc/opensc.conf
  echo pcscd_enable="YES"  >> /etc/rc.conf
  /usr/local/etc/rc.d/pcscd start
  cp /usr/local/etc/openct.conf-sample  /usr/local/etc/openct.conf
  echo openct_enable="YES" >> /etc/rc.conf 
  /usr/local/etc/rc.d/openct start
  

  
  1. add to /etc/devd.conf or /usr/local/etc/devd/openct.conf (with appropriate device ids):
  

  # Aladdin eToken PRO USB crypto token
  attach 100 {
          device-name "ugen[0-9]+";
          match "vendor" "0x0529";
          match "product" "0x0514";
          action "/usr/local/sbin/openct-control attach usb:529/514 usb /dev/$device-name";
  };
  detach 100 {
          device-name "ugen[0-9]+";
          match "vendor" "0x0529";
          match "product" "0x0514";
          action "/bin/pkill -fx '/usr/local/sbin/ifdhandler -H [a-z0-9]+ usb /dev/$device-name'";
  };

• Feitian SCR301
  #
  attach 100 {
  device-name “ugen[0-9]+”;
  match “vendor” “0×096e”;
  match “product” “0×0503”;
  action “/usr/local/sbin/openct-control attach usb:96e/503 usb /dev/$device-name”;
  };
  detach 100 {
  device-name “ugen[0-9]+”;
  match “vendor” “0×096e”;
  match “product” “0×0503”;
  action “/bin/pkill -fx ‘/usr/local/sbin/ifdhandler -H [a-z0-9]+ usb /dev/$device-name’”;
  };
  
  1. reload devd config
  

  /etc/rc.d/devd restart
  

  
  1. And confirm you can see the USB device, see it with openct and then with the opencs tools:
  

  usbconfig

• To double check the vendor and product identifiers in above devd.conf addition
  usbconfig dump_device_desc
  openct-tool list
  openct-tool atr
  pkcs15-tool -c
  

List of issues for FreeBSD:

• the above has only examples for one vendor/product each.
  We could include example files for either or both in openct with all devices listed.
• Timeout setting in libusb can be overly agressive for card which take many minutes to generate an onboard RSA.

OpenBSD

install from ports
cd /usr/ports/security/openct
make install clean
cd /usr/ports/security/opensc
make install clean

Erase and key generation works so far, but OpenSSL does not: the OpenSSL shell exits after the engine load command for some unknown reason. Note you need to specify the engine shared object file as *.so.0.0 (on Linux it is simply *.so).

Also OpenBSD has a hotplugd, but so far it does not support USB devices. So you need to run

openct-control shutdown
openct-control init

every time you add or remove a USB crypto token.

Now OpenBSD Current (2005-07-20) passes all OpenSC regression tests with an Aladdin eToken PRO.

Other tokens however did not work, these problems need to be investigated, as well as how to get it to work without UGEN_DEBUG.

other BSD

OpenCT should work, but this wasn’t tested for sometime. Latest OpenCT seems to not find libusb, we are working on it.

Solaris

Latest OpenCT supports Solaris fine and was tested to work.

Sunray

Sunray including client/server architecture was added to OpenCT (in version 0.6.5).