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 eID supporting applications: eidenv, cdigidoc, digidoc-tool, jdigidoc
- 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.
AS Sertifitseerimiskeskus kasutab kolmetasemelist sertifitseerimisahelat:
- tipmised sertifikaadid (Juur-SK ja EE Certification Centre Root CA)
- sertifitseerimise sertifikaadid (nt ESTEID-SK 2011, mis antakse välja tipmise sertifitseerija poolt)
- lõppkasutaja sertifikaadid (nt ID-kaardile kantavad isikusertifikaadid, mis antakse välja ESTEID-SK 2011 alt).
Juur-SK on vanema sertifitseerimisahela tipmine ahel, mis aegub 2016. aastal. Alates 2011. aasta juulist on kasutusel uus ahel, mille tipmiseks sertifikaadiks on EE Certification Centre Root CA.
Ühe märkimisväärse erinevusena anti Juur-SK ahelas kehtivuskinnituse teenuse (OCSP-responder) sertifikaadid välja sertifitseerija ehk teise taseme sertifikaatide alt. EECCRCA ahelas antakse kehtivuskinnituse teenuse sertifikaadid välja aga otse juursertifikaadi alt.
ID-kaardi, elamisloakaardi ning Digi-ID isikusertifikaadid on välja antud sertifitseerimise sertifikaadi ESTEID-SK, ESTEID-SK 2007 või ESTEID-SK 2011 alt, sõltuvalt väljastamise hetkest. Sertifikaadi organisatsiooniks (O) on märgitud kas "ESTEID" või "ESTEID (DIGI-ID)" ning organisatsiooni üksuseks (OU) "authentication" või "digital signature" vastavalt sellele, kas tegu on isikutuvastus või allkirjastamissertifikaadiga. Samuti on sertifikaatidel laiendid põhikasutusvaldkonna (keyUsage) ning lisakasutusvaldkondade (extKeyUsage) määramiseks: isikutuvastussertifikaadil on põhikasutusvaldkonnaks DigitalSignature, KeyEncipherment ja DataEncipherment ning lisakasutusvaldkonnaks ClientAuthentication ja SecureEmail, allkirjastamissertifikaadil on põhikasutusvaldkonnaks ainult NonRepudiation ning lisakasutusvaldkonnad puuduvad.
Tähelepanu: Isikutuvastussertifikaadi küljes olev DigitalSignature lipp ei tähenda, et sellega saaks anda seaduslikult siduvaid allkirju -- seda näitab allkirjastamissertifikaadi küljes olev NonRepudiation lipp.
Täpsemat infot sertifikaatide profiilide kohta leiab sk.ee lehelt.
Kõik SK sertifikaadid on kättesaadavad nende kodulehelt.
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 id.ee webpage.
All signed containers that follow this format bear the extension .ddoc.
BDOC is a new digital signature format that has been created to replace 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).
More detailed information about the current BDOC format can be found in the Estonian standards document EVS 821:2009.
Software developers should bear in mind that as of 2012, the BDOC format is being updated due to the new ASiC signature container standards (ETSI TS 102 918, ETSI TS 103 171, ETSI TS 103 174). Therefore, there will be more changes in the BDOC format supported at the time of writing. As the current BDOC standard compatible signature has not found usage in information systems, SK discourages deploying it in the near future. This will make the future transfer to a new international standard easier. Current information about the BDOC format can be found at http://www.id.ee/bdoc. For the reasons stated above, example applications do not presently include BDOC.
In the case of CDOC format, the structure described in the XML Encryption Syntax and Processing (XML-ENC) standard is followed. You can read more about encryption in the chapter on encryption.
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 (ISOd) 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.
Four libraries have been created to enable usage of eID functionality in desktop applications:
- jdigidoc - a Java library which is the recommended first choice when developing new applications.
Supported formats: DDOC, BDOC, CDOC.
- libdigidoc - a C library that will no longer be supported when a replacement will emerge. Not recommended for new developing projects.
Supported formats: DDOC, CDOC.
- libdigidocpp - a C++ library that is used in the DigiDoc3 client. Not offered to developers on its own, but can be obtained with the client,
Supported formats: BDOC.
- libdigidoccom - COM interface for the libdigidoc library. Does not support encryption.
Supported formats: DDOC.
- ndigidoc - a .NET library for encryption and decryption. Presently only supports software key pairs, i.e. not usable with ID card; the recipient's secret key must be on the hard disk in a PKCS#12 type container.
Supported formats: CDOC. There is a plan to create a .NET library that would replace the COM library.
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 only supports signed documents in the DDOC format – at present, BDOC is not supported. 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. An overview of mobile ID is given in the eID short introduction and application examples in the Claims use case.
There is also a free OpenXAdES 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 "Testimine" ("Testing").  As an alternative, a tester can register his or her own phone number that supports mobile ID in OpenXAdES 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 (SK's comment on 31 May 2012) is by using the eidenv.exe utility, which is included in the ID card software. Therefore, the application guide does not deal with this subtopic.
eID supporting applications: eidenv, cdigidoc, digidoc-tool, jdigidoc
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.
cdigidoc, digidoc-tool, jdigidoc
cdigidoc, digidoc-tool and jdigidoc (not to be confused with the jdigidoc library) are applications that allow basic eID actions. All of them demonstrate the possibilities of their libraries (libdigidoc, libdigidocpp and jdigidoc respectively) and are a good source for sample code.
For receiving guidelines on how to use the applications, it is enough to deploy them without command line keys, upon which help text will be displayed. Cdigidoc and jdigidoc applications have been discussed further in the respective library documentation.
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.
- 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 previously, 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.
Technical notes and observations
The fault in pre-2011 ID cards
Enne 2011. aastat välja antud ID-kaartidega, s.t 1024-bitiste võtmetega ei ole võimalik krüpteerida rohkem kui 384 bitti (48 oktetti), kuigi PKCS #11 standardi kohaselt peaks olema võimalik krüpteerida kuni 936 bitti (117 oktetti). Muuhulgas tähendab see ka seda, et andmeid allkirjastades tuleb kasutada räsialgoritmi, mille väljund oleks ülimalt 384 bitti -- nt DigiDoc-teekides kasutatakse sellel põhjusel läbivalt SHA-224 algoritmi.
Padding oracle attack
In 2012, the attack that works on several widespread cryptographic devices, including the Estonian eID documents, was intensified. In the course of that attack, it is possible to decrypt text that has been encrypted on 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 rights.
The easiest way to bypass this is to manually grant the required rights. 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, rights are lost. udev or some such tool 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 (texts in Estonian).
- "How the ID card works and how to use it for secure operations on the Internet."
- From the user's viewpoint rather than the developer's: Using the Estonian ID card under Debian
- A good starting point is the ID.ee "Develop services" webpage.
- DigiDoc world.
- Explanation of concepts, terminology.
- Sample applications.
- Configuring ID card support for Apache and IIS web servers.
- A PHP sample application with source code for signing on the web with mobile ID.
- JDigiDoc uses the IAIK PKCS#11 library. Here is its documentation.
Also, SK customer support firstname.lastname@example.org can help you find additional assistance on DigiDoc libraries, services offered by SK or answers to questions by ID card developers.