General information for developers
- 1 General information for developers
- 1.1 Certificates
- 1.2 File formats
- 1.3 Development tools
- 1.4 Test tools
- 1.5 Using the personal data file
- 1.6 eidenv
- 1.7 Using the eToken crypto-stick
- 1.8 Using the ID card's @eesti.ee mail address
- 1.9 Technical notes and observations
- 1.10 External links
- 1.11 References
General information for developers
This section contains usable information that developers should know, regardless of whether it is their aim to work on existing applications or develop new applications.
The certification chains used by SK have three levels:
- top-level certificate (Juur-SK and EE Certification Centre Root CA)
- certificates of the certifier (e.g. ESTEID-SK 2007, which are issued by the top-level certifier)
- end-user certificates (e.g. a person’s certificates added to an ID card that are issued on the basis of ESTEID-SK 2007).
The Juur-SK certificate is the topmost chain of an older certification chain, which will expire in 2016. Since July 2011, a new chain is used, the top-level certificate of which is EE Certification Centre Root CA.
A significant difference is that in the Juur-SK chain, the OCSP responder certificates were issued by the certifier, i.e., from under second-level certificates. In the EECCRCA chain, the OCSP responder certificates are issued directly from under the top-level certificate.
The personal certificates of the ID card, electronic residence card, and Digi-ID are issued by the certification certificate ESTEID-SK, ESTEID-SK 2007 or ESTEID-SK 2011, depending on the time of issuance. The certificate's organisation (O) is either "ESTEID" or "ESTEID (DIGI-ID)" and the organisational unit (OU) is either "authentication" or "digital signature" depending on whether the certificate is meant for identification or digital signing.
Furthermore, the certificates have extensions that determine their primary usage (keyUsage) and extended usage (extKeyUsage).
- For the identification certificate, the primary usage is DigitalSignature, KeyEncipherment, and DataEncipherment; and extended usage is ClientAuthentication and SecureEmail;
- For the signing certificate, the primary usage is NonRepudiation and there are no extended usages.
Attention: The flag DigitalSignature on an identification certificate does not mean that it can be used to give legally binding signatures -- this is signified only by the signing certificate's NonRepudiation flag.
For more information about certificate profiles, see here.
All SK certificates are available from here.
Three file formats connected to eID documents that are used in Estonia are described below.
DigiDoc file format is the standard's ETSI 101 903 (XML Advanced Electronic Signatures – XAdES) profile "XAdES-X-L". This standard describes the structure of digitally signed documents and the profile lets the following signable features to be tied to the signature:
- The certificate used for signing
- Time of signing
- Location of signing
- Signer's role or resolution
- OCSP server certificate
- OCSP response
A DigiDoc container is effectively an XML document with the initial files or their locations and hashes, signatures related to the files and the signatory's certificate, validity confirmation and the validity confirmer's certificate as its elements.
The first version of the DigiDoc file format was named SK-XML, while all following versions have been called DIGIDOC-XML. At the time of writing, the file format is in version 1.3. Detailed format descriptions can be found on the respective id.ee webpage.
All signed containers that follow this format bear the extension .ddoc.
BDOC is a new digital signature format which has replaced the Estonia-specific DDOC digital signature format.
Its main difference from the DDOC format is that it follows the OpenDocument standard: as a result, it is a zip container with signed files and signatures separated from each other in it. As a result, a BDOC container can be opened with any application that recognises the zip format, and the files contained in it are easily readable -– special applications like the DigiDoc client are only required for checking the integrity of initial files and signatures.
As ZIP is a compressed format, BDOC files can be significantly smaller than DDOC files. Additionally, BDOC files are better supported for forwarding by mail, as there have been problems forwarding documents in the DDOC format (some mail servers have filtered out attachments in the DDOC format).
The BDOC digital signature format comprises two technically different subformats. In order for end users to be able to easy differentiate between these subformats, each subformat has obtained its own file extension - .bdoc and .asice. See below for details on technical differences between the subformats.
Most Estonian companies and e-services have already migrated to the BDOC format. However, it might still happen that their infosystems may sometimes not be able to process the files with the extenstion .bdoc. The .acise file format is primarily known as the internationally recognised digital signature format.
- .bdoc or BDOC-TM or ASiC-E LT-TM is the BDOC signature format with a time-mark. The RFC 2560 standard based time-marks ensure long-term proofability of the authenticity of the signature. This format has been used as a default digital signature format in Estonia since 2015.
- .asice or BDOC-TS or ASiC-E LT is the BDOC signature format with a time-stamp. In contrast to the LT-TM format, long-term proofability of the authenticity of the signature is ensured by the RFC 3161 standard based time-stamps. The ASiC-E LT signature is highly compliant with the international standards.
More detailed information about the current BDOC format can be found in the Estonian standards document EVS 821:2014.
When it comes to deciding on choosing the BDOC signature profile, consider the purpose of the signed documents and potential end users. To ensure better compliance with international standards, it's recommended to sign documents with the time-stamp signature profile. Signature validation, on the contrary, works better when both profiles are supported. Also note that when you add a signature to the signed document, this signature must be created in the same format.
One of the long-time validity mechanisms is to add BDOC an archive timestamp. This mechanism builds on notion “let’s secure what may be weak”. Successive time- stamps protect the whole material against vulnerable hashing algorithms or the breaking of the cryptographic material or algorithms. The BDOC archive time-stamping profile is possible to validate with libdigidocpp library. See the chapter "Opening document, validating signatures and extracting data files" in the document http://open-eid.github.io/libdigidocpp/manual.html.
The container is an XML document with the root element EncryptedData, which contains:
- identifier of the encryption algorithm AES-128-CBC,
- encrypted symmetric key (separate for each recipient):
- identifier of the encryption algorithm RSA 1.5,
- recipient's name
- recipient's certificate (the public key of which was used for encryption),
- encrypted key
- metainfo of the contained data:
- name of initial file,
- file size,
- file MIME type,
- initial data in an encrypted form.
Although XML-ENC supports encrypting any number of files, DigiDoc applications place all the initial files into a DDOC container and then encrypt this as one file.
- Microsoft .NET Framework 4 (Web Installer)
- Windows SDK for .NET4 (ISO images) and a list of its contents
- Windows SDK for Windows 7 and .NET Framework 4 (Web Installer, so you can choose components)
- Visual Studio 2010 Express (limited to .NET and C# but free)
- The trial version of Windows 7 lasts for 3 months, after which it can be extended to 8 months for free.
The recommended operation system is Windows 7 because support for Windows XP will end on 8 April 2014, while for Windows 7 it is 14 January 2020.
AS Sertifitseerimiskeskus offers a web service and several libraries with the name DigiDoc, which have been created for simplifying usage of eID documents.
Several libraries have been created to enable usage of eID functionality in desktop applications or in information systems. We strongly recommend to use the libraries from the id.ee page. You can find there information about supported formats in each library and length of support period.
For new developments we recommend to use the newest version of the Java library digidoc4j or c++ library libdigidocpp. Quite possibly the easiest way to use the library is via the provided command line utility. See the chapter "Utility program overview" in the document http://open-eid.github.io/digidoc4j/ and the chapter "Libdigidocpp utility program" http://open-eid.github.io/libdigidocpp/manual.html#utility .
This library is intented to replace jdigidoc library.
- Release information: http://www.id.ee/?lang=en&id=36972
- Documentation: http://open-eid.github.io/digidoc4j/
- Source code and tips for integrators: https://github.com/open-eid/digidoc4j
- Backlog: https://www.pivotaltracker.com/n/projects/1110130
This library is intented to replace libdigidoc library.
- Release information: http://www.id.ee/index.php?id=36484
- Documentation: http://open-eid.github.io/libdigidocpp/
- Source code and tips for integrators: https://github.com/open-eid/libdigidocpp
Version 3.12 (release date IQ 2016) contains API changes, additional info is available at https://github.com/open-eid/libdigidocpp/wiki/API-changes-(v3.12).
As an alternative for libraries, there is also DigiDocService, a SOAP-based paid web service. It enables personal identification, digital signing and signature check functionalities to be tied to other information systems. The service can be used from different development environments/platforms that support RPC-encoded SOAP 1.0.
Functionality offered by the service:
- Identification with mobile ID.
- Certificate validity verification (allows identification with ID card or another smart card)
- Creation of DigiDoc files
- Digital signing with mobile ID
- Digital signing with the ID card (and other smart cards)
- Verification of the content and signatures of digitally signed files (DigiDoc).
DigiDocService supports signed documents in the BDOC and DDOC format.
Access to the service is IP-based, and application providers have to sign a contract with AS Sertifitseerimiskeskus to obtain access. The cost of the service depends on the number of signing and authentication queries per month as well as the number of simultaneous queries received from one application.
Mobile ID can only be used through the DigiDocService –- therefore, there may be a need to add DigiDocService support to a service that to date has been independent of it. It also means that the service provider has to be trusted. The reward is simplicity of development -- details of implementation and communication with the mobile operators is hidden from the developer and DigiDocService will work with just a few parameters given to it.
The mobile ID protocol is asynchronous, i.e. there is no immediate response to a query; it has to be retrieved later separately. As users have to verify codes and enter PINs in the course of mobile ID queries, which will take time, it is reasonable to free the line connection resources in the meantime. Therefore, the query method will first be generated and then its status checked periodically.
There is also a free test environment for testing and development.
To avoid using mobile networks in the course of testing, mobile ID test phone numbers can be used in the testing environment. While using the test service, the name of the application (method parameter ServiceName) always has to be the Estonian-language string "Testimine" ("Testing"). As an alternative, a tester can register his or her own phone number that supports mobile ID in test environment and use it for testing.
ID cards, digital IDs and digital stamps (eToken on a crypto-stick) can be ordered for testing from AS Sertifitseerimiskeskus. For a digital stamp, a customised value subject field (CN, Common Name) can be ordered. A pricelist and further information is available on the SK test cards page.
Test certificates have to be installed in order to use test cards: For Windows, there is a specific test certificate package, and for Linux there is either the esteidcerts-dev or the esteidcerts-devel package (depending on the package manager).
Using the personal data file
The Information Security Interoperability Framework states: ID card's personal data file contains the same information as can be visually seen on the card. It contains the card owner's name, expiry date and the like. It is relevant that it also contains card owner's ID code. When the owner inserts the card in the chipcard reader, the system can make out the ID code quickly and use it in further operations.
It is sensible to use the ID card's personal data file for personal identification in situations where visual identification is also possible (e.g. crossing a border).
Digital ID only contains the document number in the personal data file -- other fields are empty.
Data contained on an ID card
The following data can be read without a PIN being entered (it is sufficient to have the card in the reader).
- first name
- middle name
- date of birth
- place of birth
- personal identification number
- type of residence permit
The following data can be read about the ID card itself:
- ID card serial number
- ID card expiration date
- ID card issuing time
For unambiguous identification of the card, information from the file FID=EEEE/5044 (Personal Data File) can be used.
Using the personal data file on the Web
The new Digidoc plugin cannot be used for reading the personal data file from the ID card. The only way to read the file is by using eidenv which is part of the OpenSC software.
The command line application eidenv displays the personal data on the card, thereby replacing the IDUtil application. It is distributed as part of the OpenSC software and is included in the ID card software package. eidenv source code is available here: http://www.opensc-project.org/opensc/browser/OpenSC/src/tools/eidenv.c
Using the -x key deploys this program as argument in an environment where the ESTEID_* variables with the same data have been included. E.g. in the case of an ID card, they are:
$ eidenv -x /usr/bin/printenv ... ESTEID_SURNAME=MÄNNIK ESTEID_GIVEN_NAMES1=MARI-LIIS ESTEID_GIVEN_NAMES2= ESTEID_SEX=N ESTEID_CITIZENSHIP=EST ESTEID_DATE_OF_BIRTH=01.01.1971 ESTEID_PERSONAL_ID=47101010033 ESTEID_DOCUMENT_NR=AS0010876 ESTEID_EXPIRY_DATE=01.02.2017 ESTEID_PLACE_OF_BIRTH=EESTI / EST ESTEID_ISSUING_DATE=01.02.2012 ESTEID_PERMIT_TYPE= ESTEID_REMARK1= ESTEID_REMARK2= ESTEID_REMARK3= ESTEID_REMARK4=
This makes it possible to create different applications that use personal data without having to communicate directly with the card -- they just use the appropriate environment variable. However, such an application can easily be deceived, as the source of the values cannot be verified. Therefore, this approach is only usable in closed environments that are controlled by the service provider.
To receive more information about the application, it has to be deployed with a -h or --help key.
Using the eToken crypto-stick
At the time of writing, SK only supports the eToken crypto-stick on Windows and everything required for it can be downloaded at https://installer.id.ee/media/SafeNetAuthenticationClient_8_1_SP1Windows.zip.
Linux and other platforms have not been tested by SK and are not supported, but they do offer the necessary drivers to expert users. A container with everything needed for Linux, including documentation, can be downloaded at https://installer.id.ee/media/SafeNetAuthenticationClient_Linux_8.1.zip. Even though the software depends on Hardware Abstraction Layer (HAL), it is not a package dependency. HAL is deprecated and by default not supported by many operating systems / distributions, hence, it might be becessary to install the libhal1 package manually.
- Red Hat Enterprise 5.4 (32-bit and 64-bit) on 2.6 kernel
- CentOS 5.4 (32-bit and 64-bit) on 2.6 kernel
- SUSE Linux Enterprise 11 (32-bit and 64-bit) on 2.6 kernel
- Fedora 11 (32-bit)
- Fedora 12 (32-bit)
- Ubuntu 9.10 (32-bit)
- Ubuntu 10.04 (32-bit and 64-bit) on 2.6 kernel
The packages contain several utilities, but the most important are the drivers and PKCS#11 modules. The latter are located at %SYSTEMROOT%\System32\eToken.dll (Windows) and /lib/libeToken.so.8 (Linux; the last number depends on the version) -- these will be required if you wish to communicate with the digistamp through PKCS#11 API.
Using the ID card's @eesti.ee mail address
The ID card's authentication certificate also includes the mail address Name.Surname@eesti.ee, which is given to the card owner by the state for lifelong usage; in the case of many people with the same name combination, subsequent persons will get the mail address in the form Name.Surname.N@eesti.ee, where N is their number of sequence. On certificates issued before 2005, the mail address is in the form Name.Surname_XXXX@eesti.ee., where XXXX is a randomly generated four digit number. When a certificate is renewed, this will also be renewed, but the previous forms will also remain active.
A distinct feature of the @eesti.ee mail address is that as it is the only mail address included in the certificates, it is the only address to which mail encrypted with some standards (e.g. S/MIME) can be sent.
It is a forwarding address only -- each citizen has to show a real mailbox address in the eesti.ee portal to which all mail sent to the @eesti.ee address will be forwarded. The user also has the option to decline all unsigned and/or unencrypted mail. Therefore, there is no guarantee that the mail sent to that address will be read by the person and the mail address usage should be confirmed with the owner.
There are also some X-tee queries related to administration of the mail account, described by the relevant webpage of the State portal (in Estonian).
Technical notes and observations
The fault in pre-2011 ID cards
The ID cards issued before 2011 (i.e., those using 1024 bit keys) are unable to encrypt more than 384 bits (48 octets), even though according to the PKCS#11 standard, it must be possible to encrypt up to 936 bits (117 octets). It means, among other things, that when digitally signing data, one has to use a hash algorithm which outputs 384 bits at most. For this reason, the SHA-224 algorithm is used everywhere within the DigiDoc libraries.
Padding oracle attack
In 2012, the attack that works on several widespread cryptographic devices, including the Estonian eID documents, was improved. In the course of that attack, it is possible to decrypt text that has been encrypted for a certificate on an eID document or to create a personal identification signature (a legally binding signature cannot be faked with this attack). This means that the attack only accesses the first, personal identification key pair. The attack is successful because Estonian eID documents use PKCS#1 v1.5 padding.
The attack only works if there exists a padding oracle using the attacked eID document. A padding oracle is a party who accepts a message from the attacker, tries to decrypt it using the eID document tied to itself and then answers whether the attempt was successful or not (and that's it -- oracle does not return the decrypted message). An oracle can be a non-malevolent software running on the user's computer (if it was malware, the ID-card would be much easier to attack), a web service (when a service provider's digital stamp is attacked), etc.
The attacker can use the oracle's response to decrypt text directed to the oracle's eID document or to fake a personal identification signature. With ID cards issued before 2011, it takes respectively 11.5 hours and 49,000 oracle queries (with a median of 3.5 hours and 14,500 queries) or 48 hours and 203,000 queries (with a median of 30 hours and 126,500 queries). With newer cards, it takes respectively 27 hours and 28,300 oracle queries (with a median of 10 hours and 10,800 queries) or 103 hours and 109,000 queries (with a median of 65 hours and 69,000 queries). 
However, at the time of writing, such an attack is not possible to execute, as there are no suitable oracles. This is a point of attention for developers, not to write software that would fulfil the abovementioned requirements -- it is sufficient for the attack to happen if the software answers whether the decryption was successful or not.
Yusuke Kawamoto and Joe-Kai Tsay, two creators of the attack, have been to Estonia to present their work and a video of the visit is available on UTTV.
In Linux, the pcscd package depends on the libccid package, which will also install the required udev rules so that the pcscd daemon can interact with the card reader. Although everything usually works well, it may happen that the daemon does not get the required permissions.
The easiest way to bypass this is to manually grant the required permissions. For that, one needs to know what bus the card reader is on and the device number.
$ lsusb ... Bus 002 Device 003: ID 058f:9520 Alcor Micro Corp. EMV Certified Smart Card Reader
In this case, the card reader is device 3 on bus 2. Therefore, this is required:
# chown :pcscd /dev/bus/usb/002/003 # chmod g+w /dev/bus/usb/002/003
As a result, ls -l should display crw-rw-r-- 1 root pcscd ... 003.
This solution works, but it is not very good -- for example, when the device number changes, permissions are lost. udev or some such system is better, but the above solution is offered in the event that nothing else works.
Java and libpcsclite
Java tries to use /usr/lib/libpcsclite.so for working with card readers, which is not at that location in Debian/Ubuntu. For things to work, a symlink needs to be created:
sudo ln -s /lib/libpcsclite.so.1 /usr/lib/libpcsclite.so # Ubuntu sudo ln -s /usr/lib/libpcsclite.so.1 /usr/lib/libpcsclite.so # Debian
Here is a list of links and existing sample applications that may help eID developers.
- "How the ID card works and how to use it for secure operations on the Internet." (in Estonian).
- From the user's viewpoint rather than the developer's: Using the Estonian ID card under Debian (in Estonian).
- A good starting point is the ID.ee "For developer" webpage.
- A PHP sample application with source code for signing on the web with mobile ID.
- IAIK PKCS#11 library documentation.
Also, SK customer support email@example.com can help you find additional assistance on DigiDoc libraries, services offered by SK or answers to questions by ID card developers.
- ISO/IEC 26300:2006 Open Document Format for Office Applications (OpenDocument) v1.0
- Infoturbe koosvõime raamistik. 2007. In Estonian. http://www.riso.ee/et/files/InfoturbeRaamistik.odt
- Knowledgebase: for administrators. http://www.id.ee/index.php?id=30583
- R. Bardou, R. Focardi, Y. Kawamoto, L. Simionato, G. Steel, J. Tsay. Efficient Padding Oracle Attacks on Cryptographic Hardware. Cryptology ePrint Archive, Report 2012/417. http://eprint.iacr.org/2012/417