Usage¶

Command-line usage¶

eidreader is a command-line tool. Open a command prompt to try the following commands.

Run the eidreader command with an empty card reader:

$ eidreader
{"eidreader_version": "1.0.0", "success": false, "message": "Could not find any reader with a card inserted"}

Insert a Belgian eID card into your reader and run the command again:

$ eidreader
{"special_status": "0", "eidreader_country": "BE",
"carddata_soft_mask_version": "\x01", ... "document_type": "01",
"carddata_pkcs1_support": '!', "national_number": '...',
"nobility": "", "success": true, "message": "OK",}

Sending data to a web server : Instead of displaying the data to stdout, you can send it to a web server. For this you simply specify the destination URL as first argument:

$ eidreader https://my.server.com/123

This will send the data to https://my.server.com/123 using a HTTP POST request.

There is a special case: when URL starts with an additional schema specification (e.g. beid://https://foo.bar.hjk), then the script removes the first scheme (here beid://). So the following invocation does the same as the previous one:

$ eidreader beid://https://my.server.com/123

This is to support calling eidreader directly as a custom URL schema handler without needing to remove yourself the schema in your handler definition.

Command-line options

-l, --logfile: Log activity to the specified log file.
-c, --cfgfile: Load the specified config file before looking at the standard locations.

Running from behind a proxy

eidreader works from behind a proxy. It uses the getproxies() standard function for finding out the proxies configured on this computer and forwards them to python-requests.

If the proxy requires authentication, you need to specify them in the URL (either in the envvar or in the config file) using the user:pass@ syntax.

Alternative invocation

The following alternative invocation is no longer supported after version 1.0.7.

When invoking eidreader from a script, you may prefer to use Python’s -m option:

$ pythonw -m eidreader.main

Config file¶

eidreader also looks for a file eidreader.ini and reads two settings http_proxy and https_proxy from it. This is just another way to specify proxies. If a config file is found and has these settings, then they override what getproxies() gave.

The eidreader.ini file can be (1) in the current directory, (2) in the user’s home directory or (3) in the same directory as the eidreader script. It should look something like:

[eidreader]
http_proxy = http://user:pass@10.10.1.10:3128
https_proxy = https://user:pass@10.10.1.10:1080

Environment variable¶

PYKCS11LIB¶: The name of the PyKCS11 library to load. You usually don’t need to set it because the script then uses a standard name (which depends on your operating system).

The web application¶

You are responsible for implementing a server that accepts the POST requests issued by eidreader and processes the data.

To invoke eidreader from a browser, you must use a <a href> tag with a custom URL protocol.

Your web application should generate HTML code like this:

<html><body>
<script>
function readeid(url)
{
    var popup = window.open("beid://" + url;, '', '');
    popup.close();
}
</script>
<a href="#" onclick="readeid('https://my.server.com/123')">Read ID card</a>
</body></html>

When the user clicks on that link, their browser will shortly open a popup window on the given URL, which will cause the custom schema handler to run eidreader.

Install once, use from many clients¶

In a Windows network with several clients and a shared network drive (e.g. F:) you can install Python, SWIG and eidreader once to this drive and then run eidreader from any client using something like this:

F:\Python\bin\eidreader.exe

Troubleshooter¶

“src/dyn_unix.c:34:SYS_dyn_LoadLibrary() libbeidpkcs11.so.0: cannot open shared object file: No such file or directory”

or

“LoadLibrary() failed with error 126: The specified module could not be found.”

⟶ you don’t have the beid middleware installed. See https://eid.belgium.be/en/how-install-eid-software

Don’t read¶

>>> from atelier.sheller import Sheller
>>> shell = Sheller()
>>> shell("eidreader --help")  
usage: eidreader [-h] [-l LOGFILE] [-c CFGFILE] [-d] [url]

Read the Belgian eID card from smart card reader and either display the data to
stdout or post it to a web server.
Details see https://.../usage.html

positional arguments:
  url                   Where to POST data to.

options:
  -h, --help            show this help message and exit
  -l LOGFILE, --logfile LOGFILE
                        Log activity to the specified file.
  -c CFGFILE, --cfgfile CFGFILE
                        Read additional config from the specified file.
  -d, --dryrun          Don't actually do anything.

>>> shell("eidreader")  
{"eidreader_version": "1.0.8", "success": false, "message": "Could not find any reader with a card inserted"}

>>> shell("eidreader -d beid://https//xxxxxx.xxxx/receivedata.php?id=123456")  
Invoked as .../eidreader -d beid://https//xxxxxx.xxxx/receivedata.php?id=123456
Got data {"eidreader_version": "1.0.8", "success": false, "message": "Dry run, didn't try to read card data."}
getproxies() returned {}
Load config from ['eidreader.ini', ...]
Using proxies: {}
Would POST data to beid://https//xxxxxx.xxxx/receivedata.php?id=123456

Version 1.0.8 unquotes the specified URL in order to work around #13:

>>> shell("eidreader -d beid%3A//https//xxxxxx.xxxx/receivedata.php%3Fid%3D123456%26date%3D2024-10-24")  
Invoked as .../eidreader -d beid%3A//https//xxxxxx.xxxx/receivedata.php%3Fid%3D123456%26date%3D2024-10-24
Got data {"eidreader_version": "1.0.8", "success": false, "message": "Dry run, didn't try to read card data."}
getproxies() returned {}
Load config from ['eidreader.ini', ...]
Using proxies: {}
Would POST data to beid://https//xxxxxx.xxxx/receivedata.php?id=123456&date=2024-10-24