General information for developers

Allikas: eid.eesti.ee
Redaktsioon seisuga 27. august 2015, kell 22:52 kasutajalt SK (arutelu | kaastöö) (→‎BDOC)
Jump to navigation Jump to search

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.

Certificates

The certification chains used by SK have three levels:[1]

  1. top-level certificate (Juur-SK and EE Certification Centre Root CA)
  2. certificates of the certifier (e.g. ESTEID-SK 2007, which are issued by the top-level certifier)
  3. 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.[2]

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.[1]

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.

File formats

Three file formats connected to eID documents that are used in Estonia are described below.

DDOC

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:[3]

  • 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.[3]

BDOC

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[4] 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).[5]

More detailed information about the current BDOC format can be found in the Estonian standards document EVS 821:2014.

CDOC

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.

Development tools

There are many free development tools for Java, C++, PHP and JavaScript and each developer probably has their own favourites. The situation is different with .NET, where – unless you want to use Mono or similar – the only development tools are provided by Microsoft. As it cannot be presumed that every developer or enthusiast can afford Windows and development tools licences, here's a list of legal opportunities to test them 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.

DigiDoc software

AS Sertifitseerimiskeskus offers a web service and several libraries with the name DigiDoc, which have been created for simplifying usage of eID documents.

Libraries

Several libraries have been created to enable usage of eID functionality in desktop applications. We strongly recommend to use the libraries and guides 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 .

DigiDocService

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.[6]

Mobile ID

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

An overview of mobile ID is given in the eID short introduction and application examples in the Claims use case.

Test service

There is also a free test environment for testing and development.[8]

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").[9] 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.

Test tools

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[10] 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).

Owner's data:

  • first name
  • middle name
  • surname
  • date of birth
  • place of birth
  • personal identification number
  • citizenship
  • gender
  • 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.[11]

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 application: eidenv

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.

Supported software:

  • 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.[12]

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). [14]

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.

USB permissions

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:[13]

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

External links

Here is a list of links and existing sample applications that may help eID developers.

Also, SK customer support abi@id.ee can help you find additional assistance on DigiDoc libraries, services offered by SK or answers to questions by ID card developers.

References

  1. 1,0 1,1 http://www.id.ee/index.php?id=35763
  2. http://www.id.ee/index.php?id=30372
  3. 3,0 3,1 http://id.ee/index.php?id=30289
  4. ISO/IEC 26300:2006 Open Document Format for Office Applications (OpenDocument) v1.0
  5. http://www.id.ee/?id=34070
  6. http://id.ee/index.php?id=35785
  7. http://www.sk.ee/upload/files/DigiDocService_spec_eng.pdf
  8. http://id.ee/index.php?id=35760
  9. http://www.id.ee/?id=36381
  10. Infoturbe koosvõime raamistik. 2007. In Estonian. http://www.riso.ee/et/files/InfoturbeRaamistik.odt
  11. Knowledgebase: for administrators. http://www.id.ee/index.php?id=30583
  12. 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
  13. http://www.opensc-project.org/opensc/wiki/FrequentlyAskedQuestions#Q:IhaveasmartcardreaderinstalledbutaJavaapplicationdoesnotseeit