Usage

Simple 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

-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.

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

eidreader and the web application

eidreader is designed to collaborate with a web application.

You are responsible for implementing a server that accepts the POST request and processes the data. An example of such a web server is Lino Avanti (Hint: install and run a demo server and click on the [Read eID card] link in the Quick links section).

Use URL with custom protocol in your HTML

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.

Alternative invocation

Instead of invoking the eidreader script, you can use Python’s -m option:

$ pythonw -m eidreader.main

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\python.exe -m eidreader.main