Since 2003 the Belgian government issues electronic identity cards called "eID" cards. These cards have cryptographic keys on them that allow digital signatures. This enables you to authenticate to government e-services using a smart card reader, your eID and pin (which you have to set when you receive your eID card). While setting up the software on Windows is straight forward I found the process for Linux less trivial hence I like to documented it.
So if you want to use your eID card to login to Belgian governmental services on Linux you can use this as a guide. My setup is a Linux Mind 20.3 "Una" which was not considered a support OS at time of writing (20.2 "Uma" was) so these instructions should not be limited to supported OS-es.
The well documented part
In order to be able to authenticate using an eID you need some middleware on your computer. This middleware provides the interface between your browser plugin and your eID in the smartcard reader. This section describes the installation of this middleware.
This piece of software is available via https://eid.belgium.be and at time of writing the Linux version can be found at https://eid.belgium.be/en/linux-eid-software-installatie . I do appreciate that they have tried to support a variety popular Linux distributions but what I respect most is their decision to have it available as opensource. In my case I used a newer release of Mint and therefore I downloaded the tarbal from the link under "Downloads for unsupported distributions". Surprisingly they don't mention their github repo which has a better README.md. So I'd advise to start there: https://github.com/Fedict/eid-mw or either just check out the instructions and use it to install the code packaged in the tarbal.
The github page details the pre-requisites. For my distribution I was able to install them using:
sudo apt-get install libtool autoconf automake libassuan-dev autoconf-archive libpcsclite-dev libgtk-3-dev libcurl4-openssl-dev libproxy-dev libxml2 libp11-kit-dev openssl
Once you have the pre-requisites installed you can just use the commands from the github README.md to install the middleware:
autoreconf -i
./configure
make
sudo make install
After this the middleware is installed. It comes with a binary application which you can run via the command `eid-viewer` and use to verify it is working correctly.
No card reader found
At this stage the application opened but the status bar at the bottom stated "No cardreader found" even when my cardreader was connected. Generally when a card reader is connected but no eID is inserted it should read "Ready to read identity card" but when testing just make sure to insert an eID card because the card reader might require this. In my case however I was stuck at "no cardreader found".
The most likely explanation was that Linux didn't know how to communicate with my card reader and that it requires a device driver. Since it is a card reader that has many years I didn't have the documentation that came with it and the device itself only has a label "Digipass by vasco" which is too little to get a specific driver.
Fortunately Linux can help here. Since my smart cardreader is a USB device I can list all the USB devices and get there VendorId and ProductId using lsusb:
lsusb
...
Bus 003 Device 006: ID 1a44:0001 VASCO Data Security International Digipass
...
When you Google this you arrive at the useful linux-hardware.org website (specifically https://linux-hardware.org/?id=usb:1a44-0001). There they link to https://salsa.debian.org/rousseau/CCID which is a driver that works with quite a lot of models. This time I found the instructions on the website more useful: (i.e. https://ccid.apdu.fr/ ). It also seems that you can do a `sudo apt-get install libccid` but I only saw this package afterwards. In my case I have compiled from source.
If at this stage you still aren't able to check your card via `eid-viewer` then make sure to install `pcscd` which is a daemon that allows access to a smart card. You'll need it anyway at a later point. After installing you can also start the corresponding service:
sudo apt-get install pcscd
sudo service pcscd start
Hopefully at this stage you can open `eid-viewer` and see your card details.
Now make it work on firefox
There is an official extension for firefox to make it work with firefox which is available at https://addons.mozilla.org/nl/firefox/addon/belgium-eid/ .
However for me it always would notify me at startup with "A recent enough version of the Belgian electronic identity card software could not be found. Is the eID software installed and up-to-date?".
I know the software is up-to-date since I have installed the latest version. This part required a bit more research so I'll split up in 2 sections; the explanation and the solution so you can skip to the solution if you are only interesting in getting yours working. If the solution doesn't work for you the explanation can give insights in how it works to aid troubleshooting on your end.
The explanation
Whenever you get stuck you need to troubleshoot. One tool for troubleshooting is debugging. Recent versions of Firefox allows to debug extensions out of the box. If you browse to "about:debugging" then you get a debugging screen for Firefox, when you select "This Firefox"then you can see all the extensions that are currently installed. When you click the "inspect" button for the "eID Belgium" plugin you'll get a screen (if you've used developer tools from Firefox or Chrome this looks very familiar). There is a debugger tab in which you can find the main thread which runs "background-script.js". This allows you to see what the plugin actually does. In this particular case it tries to install a pkcs11 security module. When that fails it shows the notification we saw earlier.
Since automatic installation doesn't work I thought let's do it manually and I followed instruction from https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/PKCS11/Module_Installation and after I added the module I could see in security devices that Firefox can even see the attached card reader. Full of optimism I try a test login via https://iamapps.belgium.be/tma/?lang=en leading to a disappointing failed login.
The Firefox window to manage security devices gives very little configuration options but the issue at hand here is that the Firefox extension "eID Belgium" is not allowed to use the pkcs11 module that I imported manually. If you've tried creating this security module manually you'd want to delete it again because although it shows the cardreader it won't be usable and it will give rise to name conflict as you can only have one module named "beidpkcs11".
The proper way to go about it is via a native manifest: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#manifest_location . This manifest was actually built but it was put on /usr/local/lib/mozilla/pkcs11-modules/beidpkcs11.json which seems not checked by Firefox (perhaps in the past it was . There is also an alternate version that acts as a fallback /usr/local/lib/mozilla/pkcs11-modules/beidpkcs11_alt.json . This fallback uses p11-kit but in my case the first version works perfectly.
The solution
Put the generated manifest on the location where Firefox expects it:
sudo mkdir -p /usr/lib/mozilla/pkcs11-modules/
sudo ln -s /usr/local/lib/mozilla/pkcs11-modules/beidpkcs11.json /usr/lib/mozilla/pkcs11-modules/beidpkcs11.json
Restart firefox and you should no longer see the notification pop-up and ideally the lights of your card reader are even blinking.
Note according to the docs the following 3 locations should be valid:
/usr/lib/mozilla/pkcs11-modules/beidpkcs11.json/usr/lib64/mozilla/pkcs11-modules/beidpkcs11.json ~/.mozilla/pkcs11-modules/beidpkcs11.json
For me option 2 didn't work even though I'm on Firefox 96.0.1 (64-bit). Option 1 & 3 both worked. So use 1 if you want it to be system-wide or option 3 if you only want it to be available for a specific user.
The final test
Now go to https://iamapps.belgium.be/tma/?lang=en and you should be able to authenticate successfully!
Finally you can start the fun part; the filing of your taxes! Or whatever you wanted to do.
Edit: I wanted to create a PR to add the native manifest but it seems somebody has beaten me to it (with this change). So likely the next version will be easier to install.
