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.

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

Don’t read

>>> from atelier.sheller import Sheller
>>> shell = Sheller()
>>> shell("eidreader --help")  
usage: eidreader [-h] [-l LOGFILE] [-c CFGFILE] [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

options:
  -h, --help            show this help message and exit
  -l LOGFILE, --logfile LOGFILE
  -c CFGFILE, --cfgfile CFGFILE
>>> shell("eidreader")  
{"eidreader_version": "1.0.7", "success": false, "message": "Could not find any reader with a card inserted"}