Tag Archives: ausweisapp2

Using the German electronic identity card (eID) in Ubuntu 20.04

The new eID functionality of the German identity card enables you to identify yourself with your real name towards government or commercial web services. It makes sure that it is really you who uses the web services, and not someone who stole your online identity by email spoofing, SIM swapping, IMSI catcher, etc. .

In this example, we will be using the eID to sign a PGP key. This will uniquely identify the owner of the German identity card as the owner of the PGP key, which can then be used to sign and encrypt emails. That way PGP no longer relies on a web of trust, but works similar to the PKI concept of S/MIME certificates, in that it checks the real identity of the owner of the certificate, and then signs the certificate by a common public authority that everyone trusts.

Prerequisites

  • A German identity card with eID functionality.
  • A supported RFID card reader, e.g. from REINER SCT.
  • Operating system drivers for your card reader. In Ubuntu 20.04 drivers for all REINER SCT card readers (also called "cyberJack") are included in the package libifd-cyberjack6. You can download Ubuntu drivers from their website too, but they didn't work for me.
  • On Linux, the pcscd daemon that enables access to smart card readers.
  • An application called AusweisApp2 that handles authentication (PIN entry) and authorization (who wants to access what kind of information on your eID). In Ubuntu 20.04 AusweisApp2 is already included in the standard repositories (version 1.20.0). The app is also included as a snap install (newer version 1.20.2), but that didn't work for me (for the error message see below).

First steps

  • Make sure you have the letter with the initial PIN for your eID at hand.
  • IMPORTANT: Make sure your RFID card reader is updated to the latest firmware release. With most card readers, the firmware can only be updated while you install the card reader on a Windows system.
  • IMPORTANT: Remove usbguard. Even after I permanently added the card reader to the list of allowed devices, pcscd could not find my card reader, or AusweisApp2 did not properly recognize my card reader and complained about missing drivers.
  • Install all necessary software packages and drivers for Ubuntu 20.04:
    pcscd pcsc-tools libifd-cyberjack6 libusb-1.0-0 libusb-1.0-0 libccid libpcsclite1 libpcsc-perl libpcsclite-dev

Test your card reader

Start the pcscd daemon in debug mode:

$ sudo pcscd -df
00000000 [140135772616640] pcscdaemon.c:347:main() pcscd set to foreground with debug send to stdout
00000086 [140135772616640] configfile.l:293:DBGetReaderListDir() Parsing conf directory: /etc/reader.conf.d
00000017 [140135772616640] configfile.l:329:DBGetReaderListDir() Skipping non regular file: ..
00000006 [140135772616640] configfile.l:369:DBGetReaderList() Parsing conf file: /etc/reader.conf.d/libccidtwin
00000029 [140135772616640] configfile.l:329:DBGetReaderListDir() Skipping non regular file: .
00000009 [140135772616640] pcscdaemon.c:663:main() pcsc-lite 1.8.26 daemon ready.
00003514 [140135772616640] hotplug_libudev.c:299:get_driver() Looking for a driver for VID: 0xABCD, PID: 0x1234, path: /dev/bus/usb/001/001
...

Plug in your card reader.

IMPORTANT: If you use a USB card reader, plug it directly into your PC or laptop. Do not use a USB hub, as the hub may not provide enough power for the USB device. Also make sure to use the USB cable that came with the card reader. Longer cables may result in unstable connections.

In the output of the pcscd daemon (after a couple of seconds, wait for it!), you will see something like this:

99999999 [140135764219648] hotplug_libudev.c:655:HPEstablishUSBNotifications() USB Device add
00000158 [140135764219648] hotplug_libudev.c:299:get_driver() Looking for a driver for VID: 0x0C4B, PID: 0x0500, path: /dev/bus/usb/002/012
00000010 [140135764219648] hotplug_libudev.c:440:HPAddDevice() Adding USB device: REINER SCT cyberJack RFID standard
00000050 [140135764219648] readerfactory.c:1074:RFInitializeReader() Attempting startup of REINER SCT cyberJack RFID standard (1234567890) 00 00 using /usr/lib/pcsc/drivers/l
ibifd-cyberjack.bundle/Contents/Linux/libifd-cyberjack.so
CYBERJACK: Started
00001347 [140135764219648] readerfactory.c:950:RFBindFunctions() Loading IFD Handler 3.0
00023288 [140135764219648] readerfactory.c:391:RFAddReader() Using the pcscd polling thread

Notice that the pcscd daemon uses the driver from the package libifd-cyberjack we installed earlier. You can also check the output from the pcscd client tool:

$ pcsc_scan
Using reader plug'n play mechanism
Scanning present readers...
0: REINER SCT cyberJack RFID standard (1234567890) 00 00

Thu Nov 19 13:17:31 2020
Reader 0: REINER SCT cyberJack RFID standard (1234567890) 00 00
 Event number: 0
 Card state: Card removed,

As you can see, pcscd properly detected the card reader. Now insert your identity card into the card reader while pcsc_scan is running. The output of pcsc_scan will show something like this:

Thu Nov 19 13:21:24 2020
Reader 0: REINER SCT cyberJack RFID standard (1234567890) 00 00
 Event number: 3
 Card state: Card inserted,
...
Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
       Personalausweis (German Identity Card) (eID)

Install and start the application AusweisApp2

Install the application AusweisApp2 from the general Ubuntu repository. Do not install the snap app! In my case, the snap version of AusweisApp2 did not work properly. I got the following error message in my system logs:

Nov 18 17:32:03 server ausweisapp2-ce.pcscd[6911]: 07606784 readerfactory.c:1105:RFInitializeReader() Open Port 0x200000 Failed (usb:0c4b/0500:libudev:0:/dev/bus/usb/002/006)
Nov 18 17:32:03 server ausweisapp2-ce.pcscd[6911]: 00000015 readerfactory.c:376:RFAddReader() REINER SCT cyberJack RFID standard (1234567890) init failed.
Nov 18 17:32:03 server ausweisapp2-ce.pcscd[6911]: 00000073 hotplug_libudev.c:526:HPAddDevice() Failed adding USB device: REINER SCT cyberJack RFID standard

After you start the application, go to Start -> Settings -> USB card reader to check if the app can communicate with your card reader.

If you haven't done so before, the app will ask you to change the initial PIN that you received by mail. You have to set your own PIN before you use any online service.

Test the authentication process

Go to Start -> Self-Authentication -> See my personal data. Here you can check the data that is stored on your eID, and also make sure that the authentication process is working properly.

Click on "Proceed to PIN entry". On your card reader, you will need to confirm the service provider who wants to access your card, and also which information is requested from your card. Of course you also need to enter your new PIN.

Sign your PGP certificate

Go to Start -> Provider -> Other services -> Schl├╝sselbeglaubigung. The key signing service is provided by Governikus, the company who develops AusweisApp2.

Click on "To online application". This will start your default web browser and open the URL https://pgp.governikus.de/pgp/ . Of course you can also enter the URL directly into your web browser. Just make sure that AusweisApp2 is running in the background.

On the website you may upload your PGP public certificate. After successful authentication by eID, you will receive an email with your certificate signed by Governikus. The signature makes sure that the PGP key really belongs to you and not someone else who is impersonating you by using your email address (email spoofing) or smartphone number (SIM card swapping, IMSI catcher).

Summary

The whole eID authentication process on a website can be described as follows:

  1. Start the pcscd daemon, either by "sudo systemctl start pcscd", or if this doesn't work by "sudo pcscd -f".
  2. Plug in you card reader. You should see a confirmation in the daemon output (or by typing "systemctl status pcscd" if you started pcscd with systemctl):
    "CYBERJACK: Started"
  3. Start the application AusweisApp2.
  4. Go to the website that requests eID authentication ("elektronischer Personalausweis"), and click on "Login".
  5. Control is transferred to AusweisApp2. There you should see who requests information, and what kind of information.
  6. Insert the identity card into your card reader.
  7. In AusweisApp2, click on "Proceed to PIN entry".
  8. Control is transferred to your card reader. There you need to confirm:
    1. The service provider.
    2. The information he wants to access.
    3. Enter your PIN.
  9. On the display of your card reader, you should see something like "Tunnel established". AusweisApp2 shows something like "Authentication successful". The website should automatically proceed to its regular contents, just as if you would have entered a regular username and password.
  10. That's it.

Troubleshooting

  • If you see the following error message in the output of pcsc_scan, it means that pcsc_scan cannot communicate with the daemon pcscd. Make sure that the daemon is running.
SCardGetStatusChange: RPC transport error.
  • If AusweisApp2 does not recognize your card reader, or complains about missing drivers, try to start pcscd from the command line ("sudo pcscd -f"), and not as a background service ("sudo systemctl start pcscd"). Also make sure that you removed usbguard and did a reboot afterwards.
  • If the authentication process is not working, try to update the firmware of your smart card reader to the latest version. This might only be possible under Windows during driver installation.
Share