Belpic for Ubuntu

Introduction

When Belgium introduced its electronic Identity Card (eID, a.k.a the Belpic project), it received quite some attention from Microsoft : a speech by Bill Gates, a dedicated website about the Belgian eID, .... Far less attention has gone to the fact that the so-called eID middleware, the software that reads the chip and presents its data to user applications, is open source software - it is in fact an adaptation of source code from the OpenSC project,with its source published under the LGPL.

One of the most popular 'eID Card Readers' for use with the Belgian ID card is the ACS ACR38U. It's a cheap smartcard reader that works out of the box on Windows XP and is often referred to as "eID card Reader". So after I migrated to Ubuntu Linux, I wanted to get this card reader working, and use my electronic ID card just as I had before, when I was still using Windows. It wasn't as easy as I expected ...

Both the ACR38U and Belpic (eID, BeID) packages have been improved in newer releases of Ubuntu, so if you're using a recent version, do try a straightforward setup first. If you run in any sort of trouble, you can refer back to this page for some testing and troubleshooting procedures. The procedure described here is to get the stuff working in Ubuntu 6.06 (Dapper Drake)

However, with a lot of trial and error and some reading here and there, I got it working. I'll save you the story of everything I tried (that failed) and go straight to what you want to know : how do I get my Belgian eID to work on Ubuntu.

Mixed System : Ubuntu 6.06 ('Dapper Drake') + packages from "Edgy Eft"

There are packages for the Belgian eID in 6.06 (Dapper) Universe, but especially the support for the ACS ACR38U SmartCard Reader is problematic. So I (yes, after lots of trial and error), I decided to use packages from the Edgy Eft repositories. Although they're newer and may have a bug here and there, they're actually being developed further so it can only get better. :-)

To get access to the required Edgy Eft repositories, simply add the following lines to /etc/apt/sources.list. Note that this will make the update notifier alert you about a couple of 100 new updates available. DO NOT INSTALL them : these are all "newer" packages from Efty Eft, so you'd be saying goodbye to your Ubuntu 6.06 LTS.

		## edgy sources - enkel voor ACR38U en Belpic packages
		deb http://be.archive.ubuntu.com/ubuntu/ edgy main universe
	

the Belpic /eID packages are better supported in newer versions of Ubuntu, and, depending on what version you use, not all workarounds described here may be necessary. This page is about Ubuntu 6.06 (Dapper Drake). Still, you might find some useful information here for installing eID / Belpic packages on other systems. Apply good judgment, and have fun.

Drivers for the ACS ACR38U SmartCard Reader

first plug in the card reader, check that your operating system has detected it, and install drivers:

	# check that card reader is plugged in and detected by OS
	
	lsusb |grep "Smart Card"
			Bus 001 Device 003: ID 072f:9000 Advanced Card Systems, Ltd ACR38 AC1038-based Smart Card Reader

	if test "$?" -eq "0"; then echo "ok"; else echo "no smartcard reader detected"; fi


	# install drivers
	apt-get update
	apt-get -y -t edgy install libacr38u libacr38ucontrol0	
	

Setting up the 'middleware'

Now, install the following 3 packages. Note the '-t edgy' option to get the packages and any dependencies they might have from the Edgy Edge repositories

		apt-get -y -t edgy install beid-tools
		apt-get -y -t edgy install pcscd
		apt-get -y -t edgy install libpcsclite-dev 
	

You need all 3, even though there are no dependencies given. Missing packages will result in errors such as

	#missing libpcsclite-dev 
	Starting Belpic PC/SC daemon: 
	20:39:30: Error: Failed to load shared library 'libpcsclite.so: 
	cannot open shared object file: No such file or directory'

	#missing pcscd
	winscard_clnt.c:320:SCardEstablishContextTH() Cannot open public shared file: /var/run/pcscd.pub
	

Preliminary testing

You can now do some preliminary tests to see if you can read data from a smartcard chip. First, we will run pcscd in the foreground so we can see how it talks to the card reader

	#stop pcscd (running in background)
	/etc/init.d/pcscd stop

	#run in foreground. 
	pcscd --apdu --foreground
	

If it's running, insert a smartcard (eg a bank card) to see if it is detected. You should get something like this :

	root@knix:~# pcscd --apdu --foreground
	pcscdaemon.c:259:main() pcscd set to foreground with debug send to stderr
	pcscdaemon.c:464:main() pcsc-lite 1.3.1 daemon ready.
	hotplug_libusb.c:407:HPAddHotPluggable() Adding USB device: 001:003
	readerfactory.c:1095:RFInitializeReader() Attempting startup of ACS ACR38U 00 00.
	readerfactory.c:933:RFBindFunctions() Loading IFD Handler 2.0
	eventhandler.c:419:EHStatusHandlerThread() Card inserted into ACS ACR38U 00 00
	Card ATR: 3B 98 13 40 0A A5 03 01 01 01 AD 13 11
	

unplug the card reader and plug it back in if necessary.

When this seems to work, you can test the beid-tools to see if the Belpic software is able to work with the card reader.

	## stop pcscd (press ctrl+C) and get it running in background again
	/etc/init.d/pcscd start
	
	## list Card Readers
	beid-tool -l

	# Readers known about:
	# Nr.    Driver     Name
	# 0      pcsc       ACS ACR38U 00 00

	## test card reading
	beid-tool -a

	# Using card driver: Belpic smartcards
	# Card ATR: 3A 97 13 50 0A B5 0.....

	

If it doesn't work the first time, try unplugging the card reader and plug it back in. If that doesn't work, you got some troubleshooting ahead ...

Install the Belpic GUI

This is the standard user interface, the program you use to read the data on the chip in the eID, reset the PIN, etc. In "Dapper", it is called 'eidviewer', in "Edgy" it is 'beidgui'. They look the same, but have different, incompatible dependencies, so we stick with beidgui.

	apt-get -y -t edgy install beidgui
	

Run beidgui (command line or from the menu Applications: Other:Reading and Administration) and check that you can actually read the chip an a Belgian eID card

Install additional tools

In order to fully use the Belgian eID (from a user perspective), you also need some additional tools. These are all in the "Belpic" package, but that returns a dependency problem when you try to install the Edgy version on Dapper (and likewise for the Dapper versions with Edgy packages). However, you can install them as follows :

	apt-get -y -t edgy install libbeid2-dev
	apt-get -y -t edgy install libbeid2
	apt-get -y -t edgy install libbeidlibopensc2-dev
	apt-get -y -t edgy install libbeidlibopensc2
	
	

/var/run/openct/status: No such file or directory

OpenSC has support for three driver types : PCSC, OpenCT and CT-API. Belpic only needs PC/SC, and will produce errors you leave support for OpenCT enabled. Edit /etc/beidbase.conf, and insert a statement that limits the use of drivers to pcsc. Right before the reader_driver config feels like an OK place to do this.
OpenSC FAQ

	    ## specify driver family pcsc.
        #Others (openct, ..) are not needed for Belpic and may produce errors/warnings
        reader_drivers = pcsc ;

		reader_driver pcsc {
								.....
		

Use eID in A web browser for sites that require eID authentication

To use the eID in web applications, you need to register the eID certificates in your browser. Browse to file:///usr/share/beid/beid-pkcs11-register.html for an automated procedure. This can also be done from the command prompt (or a script). Be sure to register the certificate while running firefox (or other application) under a normal user account, i.e. not as root. When you register the certificate as root, you'll always have to run firefox as root to be able to use it (and you can not add the same certificates as an other user).

	#register certificates in firefox
	firefox file:///usr/share/beid/beid-pkcs11-register.html
	

You can manually install from Firefox menu Edit::Preferences::Advanced::SecurityDevices::Load. In the dialog box, enter
Module name: Belgium Identity Card PKCS#11
Module File Name: libbeidpkcs11.so
or: Module File Name: /usr/lib/libbeidpkcs11.so

To test with an eID-enabled web application, surf to FedICT : Toepassingen

Instructions for use of eID with other applications (Thunderbird; OpenOffice.org, Acrobat, ...) : FedICT : Toepassingen : Configureren

Manage a mixed system

Don't forget to undo the edgy repository (delete the "edgy" line from /etc/apt/sources.list), or set up apt pinning (preferences file) to keep a mixed system without replacing everything with packages from Edgy Eft.