Skip to content

Development

Jump to bottom
Wouter Verhelst edited this page Apr 19, 2022 · 25 revisions

Announcement applet 1.8

An official communication has been be sent to developers to announce the planned release of a new version of the card applet (version 1.8, whereas the current applet version is 1.7).

Developing for the Belgian eID

Overview

The Belgian electronic ID card is an ISO 7816-compliant contact smart card that can be read by most standard card readers available today.

Working with the card can be done in a number of ways; which way is best depends on the used platform and the needs of the application.

Most applications will either want to read specific data off the card, authenticate the user with their eID, or allow the user to digitally sign a document with the eID. This document will provide some insight in how to do all three, with pointers to further documentation.

Reading data off the card

The recommended way to do this is to use the PKCS#11 module that is provided as part of the official eID software as downloaded from the eID website.

PKCS#11 is a standard cryptographic API which allows applications to offload certain cryptographic operations to alternative hardware or software implementations. It is used in the context of the eID to support cryptographic signatures (see below); however, the PKCS#11 standard also allows for reading "data", and this feature is used in the official eID software to offer applications the ability to read information off the card (identity, address, card information,..).

Note that there are also some alternative PKCS#11 implementations in existence which support the Belgian eID. While these alternative implementations support the cryptographic operations, they usually do not support the identity information. Therefore, they cannot be used to read all data off the card.

For more information on how to read e.g. identity information from the card, see the examples directory in the eID software code repository. Additionally, the card data document explains which field names to use to get the correct data off the card.

For more information on how PKCS#11 works, read the PKCS#11 API documentation:

While the PKCS#11 API provides a method to read data off the card that is not too complicated to use once one is used to it, its background as what is mainly a cryptographic API mean that getting data off the card in this manner may be a bit difficult for the unexperienced developer. To remedy this a bit, the core functionality of the native eid-viewer implementations, first released with version 4.2 of the eID software, is implemented as a library that can be used from C, C#, or Objective-C. It presents an event-based interface to reading the card; that is, applications need to simply configure themselves, tell the library what information they're interested in, and then wait for data to arrive. It is written on top of the PKCS#11 API.

While the eid-viewer API is easier to use, due to the fact that it always reads all information off the card, it is not as efficient as using the PKCS#11 API directly.

More information about this API implementation (and how to use it) can be found in the eid-viewer library documentation.

For applications that simply need to read data from the card and store it for later use, the eID viewer supports an XML format that is defined in a xsd file. This format can be generated as well as consumed by the eid-viewer API; additionally, the eid-viewer has a drag-and-drop functionality where the user can drag the eID data by starting a drag from the eid-viewer's photo UI element. Since the XML format is not signed, however, this method is not appropriate in cases where a proof of identitity (as opposed to an indication of identity) is required.

In a browser context

When trying to read data from the card in a website (browser) context, the above does not work, as it would either require direct access to the PKCS#11 module from the browser context, or access from the webserver to the user's card (both of which are not possible).

Instead, the following options exist:

  • If nothing more than the user's name, surname, RRN number, date of birth, or gender are required, then one can perform an authentication (see below); the certificate contains the name, surname, and RRN number, and the date of birth as well as the user's gender are encoded in the RRN number.
  • If proof of identity is not required, then using the drag-and-drop functionality of the eID viewer may suffice (see above)
  • If these two options do not suffice, then a browser addon using Native Messaging APIs may be appropriate. The native component of the addon can then use the PKCS#11 APIs to read from the card, and the addon can pass it through the webpage using normal WebExtension APIs

Note that there are also a few third-party commercial identity providers who have implemented the third of the above three options.

Authentication

Authenticating a user with an eID on the web can be done in one of two ways:

  • Using mutual SSL: The user may install the eID software on their OS, so the webbrowser can use it. Once this has been done, they can authenticate themselves against a server which asks for a certificate under one of the Belgian root certificates. This approach is used by CSAM, the Belgian federal authentication service. Since the authentication certificate contains the user's name and national registry number, this information is available to applications that use this method of authenticating. Additionally, since the national registry number is based on (amongst other things) the user's date of birth and gender, that information is also available to the web server. If more information is needed, then this method is not appropriate.
  • The webserver may provide in-browser code (e.g., a Java applet, or some javascript code in cooperation with a browser add-on) which allows the user to log on to their card, sign data, and provide identity information to the webserver. Due to the direct access of the card, this method allows to provide more information that is found on the card than the mutual SSL method. An eid-applet exists which implements this; however, due to the removal of support for Java applets in most browsers these days, the use of the eID applet is now deprecated. Some third-party providers have implemented other alternatives which work in essentially the same manner; however, as a government service, we cannot link to these third-party providers.

For custom applications that want to use the Mutual SSL method, it is recommended that a cryptographic API is used which uses the eID software. Examples of this include (note that this list is incomplete):

  • Microsoft's CryptoAPI
  • Apple's NSURLConnection for HTTP connections, or the Common Crypto framework for lower-level options
  • Mozilla's NSS library, when configured with the PKCS#11 module
  • OpenSSL with the PKCS#11 engine and the PKCS#11 module

All these options implement standard TLS communication in ways that allow a user who has installed the eID software to authenticate with their eID card.

Note that authentication should be done with the authentication certificate (and using its private key), never with the signing certificate.

Digitally signing data with the card

To digitally sign documents or data with the card, it is recommended that cryptographic API's like the ones enumerated in the previous section are used. However, please note the following:

  • Digitally signing data should be done with the private key of the Signature certificate, never with the authentication key.
  • The card requires that a PIN code be entered anew for every signature operation: while it is possible to do multiple signing operations without re-entering the PIN using the authentication key, this is not true for signing data with the signature certificate.
  • Applet 1.7 cards requires that the "sign with signature key" instruction is preceded immediately by the instruction to send the PIN code to the card. It is therefore not possible to send the PIN code before selecting any algorithms. Unfortunately, however, that is precisely what Microsoft's CryptoAPI and Apple's API sets attempt to do. As such, these implementation only allow the default hashing and padding algorithms to be used with the signature certificate.
    Applet 1.8 cards allow a select algoritm instruction in between those commands.

Test environments

A set of test cards that contain the applet v1.8 are currently available for pre-order, and will be shipped when they are available.
A set of test cards that contain the applet v1.7 are available for order.
Both sets of cards can be ordered through the easysign website.

More information and tooling for the test cards can be found at zetescards

Raw access

If the above methods of accessing the card do not apply (e.g., because the development is for a platform that the PKCS#11 module does not support), then developing your own API may be required. To do so, the card specifications are available through two documents:

For Applet 1.7 Cards:

For Applet 1.8 Cards:

The two documents assume a general familiarity with smartcards and ISO-7816.

Support

For help with developing for the eID, please use the eid-middleware-dev Google Group.

If you wish to send patches to the eID middleware itself, or you think you have found a bug in the middleware, please use the github infrastructure (issues and pull requests) to report them.

Clone this wiki locally