ARCHITECTURE OF ID-SOFTWARE

Document version: 0.6
Software version: 3.12
Last updated: 19.02.2016

Introduction

The purpose of this document is to describe the architecture of ID-software.

ID-software is a collection of software components offering support for PKI-based functionality, i.e. operations with different cryptographic tokens (e.g. eID cards), handling digitally signed documents, file encryption/decryption and signing and authentication in web environment. The ID-software comprises end-user applications, software libraries, web components, drivers for communicating with the cryptographic tokens and other complementary components.

Main sources for information about ID-software are www.id.ee and Open-EID GitHub repository.

This document covers description of ID-software and its components, their deployment in different environments, provided and required interfaces. The document does not include components that have reached the end of their support nor the components that have not yet been released.

The document is based on the latest released state of the ID-software components. At the time of writing, the latest released version of ID-software is version 3.12. Latest version numbers of the various ID-software components are provided at http://www.id.ee/?lang=en&id=36798.

The document is targeted for:

Background

The main owner/manager of the ID-software is Estonian Information System Authority (RIA, https://www.ria.ee/en/).
Main contractor for developing the software is AS Sertifitseerimiskeskus (SK, https://sk.ee/en). In case of a few of the components, SK is also the owner.

Development of ID-software has been mainly done in Estonia, however, the ID-software is released for international usage.
The software is distributed open-source (mainly under LGPL/BSD licence) and is accessible from the following locations:

ID-software components can be logically divided in the following groups:

The following table maps the main ID-software components, their owner/developer (i.e. the main contractor) and the functionality they offer.

Table: Mapping of ID-software components and functions

Component Function Owner/ Developer Licence
Handling BDOC documents Handling DDOC documents Handling CDOC documents Calculating RSA signature Card management operations Authentication
Desktop applications DigiDoc3 Client (incl. DigiDoc3 Crypto) yes (1) yes - validation only (1) yes - - - RIA/SK LGPL
ID-card utility - - - - yes (1) - RIA/SK LGPL
Software libraries JDigiDoc (Java) yes (2) yes yes yes (1) - - RIA/SK LGPL
DigiDoc4j (Java) yes yes (1) - yes (1) - - RIA/SK LGPL
Libdigidocpp (C++) yes yes (1) - yes (1) - - RIA/SK LGPL
CDigiDoc (C) - yes yes yes (1) - - RIA/SK LGPL
NDigiDoc (.NET) - - yes - - - SK/SK BSD3
Web components Browser signing modules - - - yes (1) - - RIA/SK LGPL
hwcrypto.js (JavaScript) - - - yes (1) - - RIA/SK MIT
pkcs11-module-loader - - - - - yes (3) RIA/SK LGPL
Driver components Minidriver - - - yes (1) - yes (1) RIA/SK LGPL/BSD3
EstEID-pkcs11 - - - yes (1) - yes (1) RIA/SK -
EstEID-tokend - - - yes (1) - yes (1) RIA/SK APSL / LGPL
Smartcardpp - - - yes (1) yes (1) yes (1) RIA/SK LGPL/BSD3

Remarks:

(1) - The functionality is provided via base components.
(2) - Only BDOC with time-marks is supported (TM profile). Additional information is provided in the component's documentation.
(3) - The component is used only once for setting the proper parameters for authentication in Firefox browser.

The main functions offered by ID-software are described in the following table.

Table: Functions offered by ID-software

Function Description
Handling BDOC documents Handling documents in BDOC 2.1 (XAdES/ASiC-E) digital signature format that is a profile of ETSI XAdES (XML Advanced Electronic Signature) and ETSI ASiC formats. More information on the formats’ life cycle can be found from http://www.id.ee/?lang=en&id=34336 .
Handling DDOC documents Handling documents in DIGIDOC-XML 1.3 (DDOC) digital signature format that is a profile of ETSI XAdES (XML Advanced Electronic Signature) format. More information on the formats’ life cycle can be found from http://www.id.ee/?lang=en&id=34336
Calculating RSA signature Calculating the RSA signature value in browser or desktop/server environment. The operation involves connecting with the signature token’s driver, sending the data to be signed and receiving digital signature value calculated with the token owner’s RSA private key. The following cryptographic tokens are supported: hardware-based tokens (e.g. PKCS#11-based eID cards, USB cryptostick and Mobile-ID); software-based tokens (e.g. PKCS#12 software token)
Handling CDOC documents Encrypting and decrypting documents in ENCDOC-XML 1.0 (CDOC) format.
Card management operations Renewal of the certificates on the card, PIN/PUK management, reading personal data file.
Authentication Authentication with ID-card. The operation is generally done via native operating system/browser components. In case of Estonian ID-cards and Firefox browser, a PKCS#11 module loader script is used for setting the proper parameters for authentication in Firefox browser.

Component model

The following chapter depicts ID-software component diagrams, including variations of the components used in different supported environments.
In the context of the component diagrams in this document, the ID-software components have been divided to three different packages to show the component’s owner/developer:

Other components are regarded as external to ID-software.
Note that not all of the external base libraries are included in the component model to avoid duplicity with other documentation – the base libraries are listed and described in the documentation of the respective ID-software components and can be accessed via the references provided.

Desktop applications

DigiDoc3 Client


Figure: Components of DigiDoc3 Client

Table: Components of DigiDoc3 Client

Component Description Owner/ Developer
DigiDoc3 Client End-user desktop applications that own a common GUI. DigiDoc3 Client enables handling digitally signed documents. DigiDoc3 Crypto subcomponent enables file encryption/decryption. Wiki: https://github.com/open-eid/qdigidoc/wiki Code repository: https://github.com/open-eid/qdigidoc RIA/SK
DigiDoc3 Client base libraries Libdigidocpp (and its base libraries, including CDigiDoc), etc. See ID-card utility's interfaces -
Kill switch (v3.9-v3.11) Service for centrally managing DigiDoc3 Client application’s life cycle. The application periodically connects with the service to check if the application’s version is still supported. If not, then the application cannot be used any longer and a newer version must be installed. RIA
Error reports repository Repository where the DigiDoc3 Client application’s and ID-card utility program’s error reports (generated with BreakPad base library) are sent. RIA
DigiDocService web service SOAP-based web service that is used by DigiDoc3 Client for signature creation with Mobile-ID. See also http://www.sk.ee/upload/files/DigiDocService_spec_eng.pdf. SK/SK
LDAP directory Directory of active certificates issued by SK (as the CA in Estonia). The directory is used by DigiDoc3 Crypto subcomponent for finding authentication certificate (and the respective public key) of the recipient of the encrypted document. See also https://sk.ee/en/repository/ldap/ldap-kataloogi-kasutamine/ SK/SK
Central configuration repository Described in chap. Central configuration service RIA
Central configuration client Described in chap. Central configuration service RIA/SK
TSL repository Repository for accessing the TSL (Trust Service status List) lists that can be used as a central source of trust anchor information during digital signature creation and validation processes. The European Commission’s TSL list (https://ec.europa.eu/information_society/policy/esignature/trusted-list/tl-mp.xml) is used as the central TSL list (with references to national lists). -
Time-stamping service RFC3161 based time-stamping service. -
OCSP service RFC6960 based OCSP service. Also offered by SK for Estonian and a number of foreign certificates (see www.sk.ee). -
Libdigidocpp Described in chap. Software libraries RIA/SK
CDigiDoc Described in chap. Software libraries RIA/SK
Minidriver Used via CNG interface in Windows environment only. Described in chap. Drivers RIA/SK

DigiDoc3 Client interfaces

Provided:

Required:

ID-card utility


Figure: Components of ID-card utility

Table: Components of ID-card utility

Component Description Owner/ Developer
ID-card utility End-user desktop application for managing ID-card’s PIN/PUK codes replacement, certificates’ renewal and other services. Code repository: https://github.com/open-eid/qesteidutil . Wiki: https://github.com/open-eid/qesteidutil/wiki RIA/SK
ID-card utility’s base libraries See ID-card utility's interfaces -
ID-Updater Used in Windows and OSX only, described in chap. Updating mechanisms. In case of Windows platform, the ID-Updater can be executed from ID-card utility program. RIA/SK
ID-Updater service Used until v3.11 of ID-software. Since v3.12, replaced with the Central configuration service RIA/SK
Central configuration client Described in chap. Central configuration service RIA/SK
Central configuration repository Described in chap. Central configuration service RIA
ID-card owner’s photo repository Repository where the Estonian national ID-cards photos’ are kept. ID-card’s owner can download the photo after the user has been authenticated with PIN1 code. RIA
Error reports repository Described in chap. DigiDoc3 Client RIA
@eesti.ee e-mail checking service Service that enables to set the properties of e-mail address (@eesti.ee) that is provided for Estonian national ID-card owners by the state. The user must be authenticated with PIN1 code. RIA
Certificate's renewal service Service for renewing certificates on the Estonian national ID-card and Digi-ID card. RIA
M-ID checking service Service for checking the status of Estonian national ID-card owner’s Mobile-ID certificates. The user must be authenticated with PIN1 code. SK

ID-card utility's interfaces

Provided:

Required:

Software libraries


Figure: Java software libraries and their components


Figure: C/C++ software libraries and their components

Figure: .NET software libraries and componentsp>

Table: Software libraries and their components

Component Description Owner/ Developer
DigiDoc4j Java software library that enables handling documents in BDOC 2.1(XAdES/ASiC-E) and DIGIDOC-XML 1.3 formats. Documentation: http://open-eid.github.io/digidoc4j/ . Code repository: https://github.com/open-eid/digidoc4j RIA/SK
DigiDoc4j utility program Small command line application that implements the main functionality of DigiDoc4j library. Used for testing purposes. Can also be used as a source for sample client code for using DigiDoc4j. See also http://open-eid.github.io/digidoc4j/ RIA/SK
JDigiDoc Java software library that enables handling documents in BDOC 2.1 (XAdES/ASiC-E) and DIGIDOC-XML 1.3 formats and encryption/decryption in ENCDOC-XML 1.0 (CDOC). Documentation: http://id.ee/public/SK-JDD-PRG-GUIDE.pdf Code repository: https://github.com/open-eid/jdigidoc RIA/SK
JDigiDoc utility program Small command line application that implements the main functionality of JDigiDoc library. Used for testing purposes. Can also be used as a source for sample client code for using JDigiDoc. See also http://id.ee/public/SK-JDD-PRG-GUIDE.pdf. RIA/SK
Libdigidocpp C++ software library that enables handling documents in BDOC 2.1  (XAdES/ASiC-E) and DIGIDOC-XML 1.3 formats (via CDigiDoc base library). Wiki: https://github.com/open-eid/libdigidocpp/wiki Code repository: https://github.com/open-eid/libdigidocpp Documentation: http://open-eid.github.io/libdigidocpp/ RIA/SK
Libdigidocpp utility program Small command line application (digidoc-tool.exe) that implements the main functionality of Libdigidocpp library. Used for testing purposes. Can also be used as a source for sample client code for using Libdigidocpp. See also http://open-eid.github.io/libdigidocpp/ RIA/SK
CDigiDoc Software library in C that enables handling digitally signed documents in DIGIDOC-XML 1.3 format and encryption/decryption in ENCDOC-XML 1.0 (CDOC). Documentation: http://id.ee/public/SK-CDD-PRG-GUIDE.pdf Code repository: https://github.com/open-eid/libdigidoc Wiki: https://github.com/open-eid/libdigidoc/wiki RIA/SK
CDigiDoc utility program Small command line application that implements the main functionality of CDigiDoc library. Used for testing purposes. Can also be used as a source for sample client code for using CDigiDoc. See also http://id.ee/public/SK-CDD-PRG-GUIDE.pdf RIA/SK
NDigiDoc Software library in .NET enabling encryption/decryption in ENCDOC-XML 1.0 (CDOC). Documentation: http://id.ee/public/NDigiDoc.pdf Code repository: https://github.com/open-eid/ndigidoc SK/SK
NDigiDoc utility program Small command line application that implements the main functionality of NDigiDoc library. Used for testing purposes. Can also be used as a source for sample client code for using NDigiDoc. See also http://id.ee/public/NDigiDoc.pdf. SK/SK
DigiDocCSharp .NET C# wrapper classes for using Libidigidocpp library’s functionality in .NET environment. Created with Swig tool. See also https://github.com/open-eid/libdigidocpp/blob/master/examples/DigiDocCSharp/README.md RIA/SK
TSL repository Described in chap. DigiDoc3 Client -
Time-stamping service Described in chap. DigiDoc3 Client -
OCSP service Described in chap. DigiDoc3 Client -

DigiDoc4j library’s interfaces

Provided:

Required:

DigiDoc4j utility program’s interfaces

Provided:

Required:

JDigiDoc library’s interfaces

Provided:

Required:

JDigiDoc utility program’s interfaces

Provided:

Required:

Libdigidocpp library’s interfaces

Provided:

Required:

Libdigidocpp utility program’s interfaces

Provided:

Required:

CDigiDoc library’s interfaces

Provided:

Required:

CDigiDoc utility program’s interfaces

Provided:

Required:

NDigiDoc library’s interfaces

Provided:

Required:

NDigiDoc utility program’s interfaces

Provided:

Required:

Web components

Web signing components

The web signing component diagrams describe components that are needed for signature creation in web applications with eID cards.

Figure: Components for signature creation in web environment

Table: Components for signing in web environment

Component Description Owner/ Developer
hwcrypto.js JavaScript library that enables communication with the browser signing modules (plug-in or extension) of the different web browsers. Wiki: https://github.com/open-eid/hwcrypto.js/wiki . Code repository: https://github.com/open-eid/hwcrypto.js RIA/SK
Web application A web application that implements signature creation with an eID-token in browser environment. -
EstEID Firefox plug-in Browser signing module (NPAPI-based plug-in) that is used in Firefox (supported in Windows and Linux) and Safari (supported in Mac OS) browsers. The plug-in enables data exchange with the cryptographic token’s driver that is used for signing. In Windows environment, the driver that is implementing CNG/CAPI interface is used, along with the operating system’s native PIN insertion and certificate selection dialogs. Otherwise, PKCS#11 driver is used. Code repository: https://github.com/open-eid/browser-token-signing . Wiki: https://github.com/open-eid/browser-token-signing/wiki RIA/SK
EstEIDPluginBHO Browser signing module (BHO-based plug-in) that is used in Internet explorer browser (supported in Windows operating system). The plug-in enables data exchange with the cryptographic token’s driver that is used for signing. By default, the CNG/CAPI and minidriver is used along with its certificate selection and PIN insertion dialogs. Alternatively, in case of using PKCS#11 driver, the operating system's native PIN insertion dialog is used, certificate is selected via CAPI interface. Code repository: https://github.com/open-eid/browser-token-signing . Wiki: https://github.com/open-eid/browser-token-signing/wiki RIA/SK
chrome-token-signing Comprises two subcomponents: browser extension component and native OSX/Linux/Windows component that implements Native Messaging API (JSON). The browser extension enables data exchange with the native component that in turn interacts with the cryptographic token’s driver for signing. Code repository: https://github.com/open-eid/chrome-token-signing . Wiki: https://github.com/open-eid/chrome-token-signing/wiki RIA/SK
Minidriver Used via CNG interface in Windows environment only. Described in chap. Drivers RIA/SK

Hwcrypto.js library’s interfaces

Provided:

Required:

EstEID Firefox plug-in’s interfaces

Provided:

Required:

EstEIDPluginBHO plug-in’s interfaces

Provided:

Required:

Chrome-token-signing interfaces

Provided:

Required:

Web authentication components

Authentication in web browsers is done with the browsers’ and operating systems’ native components. In case of authenticating in Firefox browser then Firefox pkcs11-module-loader JavaScript component is used to load the OpenSC PKCS#11 driver by the browser.

Figure: Web authentication components

Table: Web authentication components

Component Description Owner/ Developer
pkcs11-loader.js A JavaScript component that is used to load the OpenSC PKCS#11 driver to the Firefox browser’s cryptographic devices list during each initialization of the browser. Needed during authentication process with eID-card in Firefox browser in all supported operating systems. Code repository: https://github.com/open-eid/firefox-pkcs11-loader Wiki: https://github.com/open-eid/firefox-pkcs11-loader/wiki RIA/SK
OSX native certificate selection and PIN dialog PIN dialog and certificate selection windows provided by the operating system’s native components. -
Minidriver Described in chap. Drivers RIA/SK

Drivers


Figure: Cryptographic tokens’ drivers

Table: Cryptographic token driver components

Component Description Owner/ Developer
EstEID PKCS#11 driver A driver for accessing eID-cards. Connects with the card via the operating system’s native PC/SC interface. Used as a default driver for signature creation with eID card in browser environment in case of OSX platform. Used as a default driver for authentication with eID card in browser environment in case of Firefox browser in OSX platform. Code repository: https://github.com/open-eid/esteid-pkcs11 Wiki: https://github.com/open-eid/esteid-pkcs11/wiki RIA/SK
OpenSC PKCS#11 driver A driver for accessing eID-cards. Connects with the card via the operating system’s native PC/SC interface. Used as a default driver for authentication with eID card and signature creation in web browser environment in case of Linux platform. Wiki: https://github.com/OpenSC/OpenSC/wiki -
One-pin OpenSC PKCS#11 driver Version of OpenSC PKCS#11 driver that only enables authentication functionality. Used as a default driver for authentication with eID card in browser environment in case of Windows platform. Wiki: https://github.com/OpenSC/OpenSC/wiki -
Smartcardpp eID card driver’s helper component. Inner component. Code repository: https://github.com/open-eid/smartcardpp Wiki: https://github.com/open-eid/smartcardpp/wiki RIA/SK
Minidriver Used as a default driver for accessing Estonian eID-cards via CNG interface for signature creation in web browser environment in case of Windows platform. Used as a default driver for authentication with eID card in Chrome and Internet Explorer browsers in case of Windows platform. Code repository: https://github.com/open-eid/minidriver Wiki: https://github.com/open-eid/minidriver/wiki RIA/SK
ATR Filter Base component for Minidriver (see http://support.microsoft.com/kb/981665 for more information). -
Esteid Tokend A driver for accessing eID-cards. Connects with the card via the operating system’s native PC/SC interface. Used as a default driver for authentication with eID card in browser environment in case OSX platform. Code repository: https://github.com/open-eid/esteid-tokend Wiki: https://github.com/open-eid/esteid-tokend/wiki RIA/SK
PKCS#12 implementation via base library An implementation of PKCS#12 interface by the component’s base libraries. -

PKCS#11 driver interfaces

Components:

Provided:

Required:

Minidriver interfaces

Provided:

Required:

PKCS#12 implementation via base library

Provided:

Tokend driver interfaces

Components implementing the interface:

Provided:

Required:

PC/SC driver interfaces

Provided:

Required: not in the scope of this document.

Updating mechanisms

The following chapter describes automatic updating mechanisms of different ID-software desktop applications. Several combinations of central software update checking and distribution environments are used depending on the end-user’s operating system.

Windows updating mechanism


Figure: Updating mechanisms in Windows

Table: Updating mechanisms in Windows

Component Description Owner/ Developer
ID-updater Service that is periodically checks if newer versions of related ID-software components are available for download, initiates the download and installation if necessary. Uses Central configuration service for determining the latest available software versions. RIA/SK
MS Update Microsoft Update – see Microsoft’s documentation for more information. -
Chrome Web Store See https://chrome.google.com/webstore/detail/token-signing/ckjefchnfjhjfedoccjbhjpbncimppeg -

OS X updating mechanism


Figure: Updating mechanisms in OSX

Table: Updating mechanisms in OSX

Component Description Owner/ Developer
ID-updater Described in chap. Windows updating mechanism RIA/SK
Apple App Store See Apple App Store documentation. -
Chrome Web Store** See https://chrome.google.com/webstore/detail/token-signing/ckjefchnfjhjfedoccjbhjpbncimppeg -

Linux updating mechanism


Figure: Updating mechanism in Linux

Table: Updating mechanisms in Linux

Component Description Owner/ Developer
Ubuntu package updates Managed and maintained by SK. The binary packages are released for installation and updating to https://installer.id.ee/media/ubuntu/ repository. RIA/SK
Packages updates for other distros Managed by the open-source community. Packages are built, added and updated in Estobuntu and Fedora distributions by the package maintainers. -
Chrome Web Store See https://chrome.google.com/webstore/detail/token-signing/ckjefchnfjhjfedoccjbhjpbncimppeg -

Central configuration service

The central configuration service's purpose is to enable on-line and central management of ID-software components configuration settings.

Figure: Central configuration service's client and server components

Table: Central configuration service's components

Component Description Owner/ Developer
ID-Updater ID-Updater component (only in Windows and OSX) requests data from the central configuration client component, the latest availabe ID-software versions are read from the configuration file. See also Updating mechanisms RIA/SK
ID-card Utility ID-card Utility requests configuration data from the central configuration client component. Described in chap. ID-card Utility RIA/SK
DigiDoc3 Client DigiDoc3 Client requests configuration data from the central configuration client component. Described in chap. DigiDoc3 Client RIA/SK
Central configuration client Central Configuration Client component manages the configuration file validation and updating processes, returns the validated configuration data to the Requesting Application (DigiDoc3 Client or Utility program) and if necessary, updates the data from Central Configuration Server RIA/SK
Central configuration service Central Configuration Server component provides configuration data on-line to the Central Configuration Client component RIA
config.json The central configuration file is named config.json, the file is in JSON format. The configuration file is signed RIA/SK
config.rsa Stores the central configuration file's signature value. RIA/SK
config.pub Public key used for validating the central configuration file's signature value. RIA/SK
Libdigidocpp DigiDoc3 Client's base library, also uses the central configuration file's settings. Described in chap. Software libraries RIA/SK

Central configuration client's interfaces

Provided:

Required:

Central configuration repository's interfaces

See Central configuration repository's interfaces.

Interfaces with external services

The following chapter describes interfaces that different ID-software components may have with external services. Relatsionships with the external services are depicted in different ID-software component models above.

Central configuration repository's interfaces

ID-updater service interface (until v3.11)

Kill switch service interface (v3.9-v3.11)

DigiDocService web service interface

Error reports repository interface

LDAP directory interface

TSL repositories’ interfaces

Time-stamping service interface

OCSP service interface

ID-card owners’ photo repository interface

Eesti.ee e-mail checking service interface

Mobile-ID validity checking service interface

Certificate's renewal service interface (since v3.12.x)

Deployment model

The following subchapters describe physical deployment of ID-software components in collaboration with external components that were depicted in chap. Component model in case of the most common use cases.

Signing in web browser

Figure: Signing in web browser via a web application

Additional notes:

Signing with DigiDoc3 Client


Figure: Deployment of components during signature creation with DigiDoc3 Client

Additional notes: