Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Developing for the Belgian eID
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 an 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.
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.
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.
- The card 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.
Developers who wish to test functionality that is not provided immediately by their own personal card can override certain content on the card by way of the test cards framework. In addition, the test cards framework can be combined with the eID test CA implementation, which allows to generate certificates and signature algorithms other than the ones on the card itself. By using the test CA, developers can test verification of cards with SHA256 signatures even if they own SHA1 cards themselves, or vice versa, and other similar things.
In case the test cards framework does not suffice, a physical test card can be ordered through the easysign website
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:
- The Card Applet Reference Manual document the APDU commands supported by the card
- The Card Content document documents the card filesystem, documenting the names and structures of the various EFs on the card.
The two documents assume a general familiarity with smartcards and ISO-7816.
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.