Sample applications

Allikas: eid.eesti.ee
Redaktsioon seisuga 27. august 2015, kell 13:01 kasutajalt SK (arutelu | kaastöö) (→‎libdigidoc configuration)
Jump to navigation Jump to search

Sample applications

Requirements

Sample code has been created on the platform Ubuntu 12.04 Long-Term Support a.k.a Precise Pangolin (64-bit), using the default package versions:

  • libdigidoc 3.6.0.707-ubuntu-12-04
  • libdigidocpp 3.6.0.771-ubuntu-12-04
  • gcc 4.6.3-1ubuntu5
  • OpenJDK 7u7-2.3.2a-0ubuntu0.12.04.1
  • PHP 5.3.10-1ubuntu3.4
  • Apache 2.2.22-1ubuntu1.1

In addition to these, the following external libraries are required for deploying Java applications:

Note: These are the versions of libraries used at development. This means that it may be possible to compile source code with older libraries and, at the same time, newer libraries may simplify it (e.g. having a more comfortable API). If there are certain requirements about version or environment for some application, they are mentioned accordingly.

Sample application in C++

The C++ sample application uses the library libdigidocpp, which is distributed as part of the DigiDoc3 client software -- it is not offered to developers separately. However, if the developer uses a Linux-based operation system, this library can be downloaded from EISA's Fedora, openSUSE or Ubuntu repositories without the client application.

It's important to note that libdigidocpp itself supports only BDOC. To work with DDOC-format documents, libdigidocpp dynamically loads the libdigidoc C-library and uses that -- therefore to support DDOC, you need to have libdigidoc installed (see Libraries).

In addition to the library, certain header files are also necessary. In Windows, the headers are installed with the base software. In Linux, it is necessary to install the libdigidocpp-dev or libdigidocpp-devel package to access the headers. Furthermore, if the C library is used (e.g. for encryption) then its header files are required as well -- for Windows, the latest version is available here, and for Linux, through the installation of either the libdigidoc-dev or libdigidoc-devel package. The C library's headers are not necessary for the aforementioned dynamic loading of libdigidoc.

By default, the sample applications request PIN by using their own solution, which is dependent on unistd.h (which Windows does not have). In the libdigidocpp library's SVN host, there is the EstEIDConsolePinSigner class, which does work under Windows, but as of 2 May 2012 it is not in the library available in EISA's Ubuntu repositories. However, if you have this class, while compiling sample applications add the -DHAVE_ESTEID_CONSOLE_PIN_SIGNER key to use it.

Sample application in Java

The Java sample application uses the JDigiDoc library. In sample code, the library has only been used for creating client applications, but it can similarly be used for server applications.

Java configuration file

The JDigiDoc library uses the file Properties for configuration management. The keys that are read from the file are presented in appendix 1 of documentation of the jdigidoc library.[1]

Important lines in the configuration file:

  • DIGIDOC_SIGN_PKCS11_DRIVER - API driver of the card PKCS11,
  • DIGIDOC_LOG4J_CONFIG - logging configuration file,
  • SIGN_OCSP_REQUESTS - whether to sign OCSP requests (this is needed e.g. for using SK's OCSP service),
    • DIGIDOC_PKCS12_CONTAINER - location of the certificate used for signing, in PKCS12 format,
    • DIGIDOC_PKCS12_PASSWD - password for opening the PKCS12 file of the certificate used for signing,
    • DIGIDOC_OCSP_SIGN_CERT_SERIAL - serial number of the certificate used for signing,
  • DIGIDOC_CA_1_CERT#, DIGIDOC_CA_1_OCSP#_CERT, DIGIDOC_CA_1_OCSP#_CA_CERT - certificate locations; use the prefix jar://, to give the location from classpath.

Sample application in PHP

DigiDocService

For signing and signature verification in PHP, DigiDocService can be used. To enable communication with the service over HTTPS, the cURL extension has to be added to PHP.

The interface of DigiDocService is defined in WSDL, upon which the PHP class for using the service is generated. Although PHP 5 comes with built-in SOAP client and the possibility to generate a class upon WSDL[2], sample code uses the included SOAP module from PEAR, with which the code will also work with older versions. The code should work with PHP 4.3.4 at least, but working on older versions is not excluded either. If the web application uses PHP 5, it is advisable to use built-in tools for new developments.

For reading XML files and DigiDoc containers, a shortened and slightly modified version of sample code is used, which is available at https://www.openxades.org/ddservice/. If the shortened version lacks the desired functionality, it may be present in the full version.

SWIG

If there is no wish or possibility to use DigiDocService, DigiDoc libraries can be used as an alternative. None has been written for PHP; therefore, a wrapper around an existing one has to be used.

To simplify interfacing with a library and minimise wrapped surface, a simple middle layer was created in the sample code that hides the usage of libdigidoc library behind a function. The middle layer is transmission-specific, which is why it is not suitable for general use, but it will give an idea of what it could be like. After that, a SWIG wrapper was created around the middle layer, not the library. The result was a PHP extension with the help of which it is possible to use all the methods of the middle layer.

The extension is used for signing and encrypting the server-side response. The latter of these cannot be done with DigiDocService, which is more proof of the necessity of using libraries.

Compiling the extension

Download: Source code of the middle layer

Because of the created middle layer, the digidoc interface in source code is very simple -- it only contains the directive for the inclusion of digidoc.h headers. From the interface, the wrapper's code can be generated by giving the command:

swig -php digidoc.i

As a result of this, three new files are created: digidoc_wrap.c, digidoc.php and php_digidoc.h.

  • The first, digidoc_wrap.c, contains the code in C needed for compiling the PHP extension.
  • The second, digidoc.php, can be included in PHP scripts. It attempts to load the extension dynamically and places the wrapped functions into the abstract class digidoc.
  • The last, php_digidoc.h, contains necessary header information for when you wish to link the extension statically into a PHP interpreter. If you do not want to do that, this file is not needed.[3]

After that, the middle layer code together with the generated C code of the wrapper should be compiled into one shared object. For compiling, the header locations of PHP interpreter headers must also be given, which can be done with the php-config tool, and then the libdigidoc library should be linked. E.g. using GCC, the compiling would look like this:

$ gcc `php-config --includes` -fPIC -c digidoc.c digidoc_wrap.c
$ gcc -shared digidoc.o digidoc_wrap.o -ldigidoc -o digidoc.so

Loading the extension

When including digidoc.php, it is attempted to dynamically load the created extension with the command dl (if it hasn't been loaded already). As there have been problems with the dl command[4], it is first better to load the module manually. For that, a line has to be added to the php.ini configuration file (or the existing one changed):

extension=digidoc.so  # Linux
extension=digidoc.dll # Windows

libdigidoc configuration

As the SWIG wrapper uses the libdigidoc library, the file digidoc.conf must be changed for configuring it. Default values are mostly suitable, but there is one important line: DIGIDOC_OCSP_URL, which determines where the OCSP query will be sent. For testing purposes, the value should be http://demo.sk.ee/ocsp.

Attention: Do not forget to change it back when you want to send queries in a product environment using the libdigidoc library.

Sample application in JavaScript

Several signing plugins have been made for different operation systems and browsers, but their API-s are somewhat different. To simplify adding signing support to web applications, a JavaScript library was created that offers a unified interface for communicating with all plugins.[5][6]

The library's interface facilitates:

  • loading the best installed plugin for the operating system and the browser
  • reading the user's signing certificate from the ID card and
  • signing the given hash with the user's ID card.

Error messages of the library are in Estonian, English, Lithuanian and Russian. For choosing the desired language, the value of the method loadSigningPlugin() should be set respectively to "est", "eng", "lit" or "rus".

All three are used in the claims presentation web form and the sample code is available there.

The library with documentation is available at: http://id.ee/index.php?id=30496

In addition to the library, a new universal plugin was also created that is distributed as part of the ID card base software and is recommended for use in the future, as the older Java applet is no longer updated.[6]

Sample application in the .NET framework

Although .NET allows several operations to be performed with the smart card with the tools already included in the framework, it lacks support for the DDOC format. Therefore, for signing or verifying a container in a .NET application, a COM-library must be used or the appropriate functionality implemented.

.NET sample code can be seen in the claim application.

There is a plan to create a separate .NET library by 2013 that will replace the COM library.[7]

Claims presentation use case

Use case participants

For demonstrating eID's different possibilities and how to combine them, the following use case is used:

Let's presume there is an organisation to which claims can be presented. For that, the organisation has to set up a web server with a web form. Communication with the server is carried out over the HTTPS protocol and it requires the user to identify himself (See [1] in the list below). In the form, the name and personal identification number fields have been pre-filled with data taken from the certificate. After that, the user writes down his claim, which the web service will place into a DigiDoc container with the name and personal identification number, using DigiDocService[2.1]. As a last step, the user is asked to sign the container in the web browser[2.2].

The created container is forwarded to another service, which checks the signature [2.3] and issues an automatic response in a container that is signed with the organisation's digital stamp and encrypted with the public key from the user's certificate[3]. The user can save the presented claim and the received answer in his computer and then take a closer look at the answer with the DigiDoc client.

Parallel to the web form, there is also an application where the user has to identify himself[4]. Then the signed container is created in the client's computer[5, 6] and sent as a whole to the same service as the web form. In addition to the claim, the application also includes the information found in the personal data file of the ID card [7]. The server response is the same, but this time it is also decrypted[8] and the signature is verified within the application[8], not the DigiDoc client.

Therefore, the use case demonstrates

  1. personal identification on the Web,
  2. usage of DigiDocService
    1. for creating containers,
    2. signing and
    3. signature verification,
  3. encrypting a file with the sender's certificate,
  4. personal identification in an application,
  5. creating a container in an application,
  6. signing in an application,
  7. reading the personal data file of an ID card,
  8. decrypting a file and
  9. verifying a signature in an application.

Web server

The web server is either Apache httpd or Microsoft IIS (naturally other web servers may be used, but these will not be discussed here). In both cases, it is necessary to have PHP support installed and the server configured to use HTTPS. All of this is done as normal and there is no eID specifics.

For logging in with an ID card, the server has to be additionally configured to request the user for his certificate on the relevant webpage. Guidelines for it can be found on the corresponding ID.ee page. In the present use case, an ID card is only used on the web form so that the guide should be consulted for this application only. If all applications run on the same web server, requesting the certificate should be configured for the web form only; the certificate should definitely not be requested by the claims handling service; otherwise, other applications cannot present claims to it.

Servers configured according to these guidelines verify the validity of users' certificates against revocation lists (CRL, Certificate Revocation List) only -- adding OCSP (Online Certificate Status Protocol) requests would be a good idea. But as mentioned at certificate validity check, it is not easily done in a web server.

As noted above, the client's certificate is only used in the SSL/TLS session at the web form, where DigiDocService support already exists. Therefore, validity confirmation can also be asked through this service. In the mobile ID web form, DigiDocService performs a validity check for us, so there is no need to do it separately.

Web form

Web form sequence diagram

Download: Web form source code

The web form is written in PHP and it uses DigiDocService for creating and signing containers. Read more about using PHP under languages.

  1. The web server carries out a personal identification in the course of the SSL/TLS handshake.
  2. The application uses DigiDocService for verifying client certificate validity. See certificate validity check in an SSL/TLS session to learn why it is done like that.
  3. The user is presented a web form that consists of four fields. Three of them (name, surname and personal identification number) are pre-filled with the data obtained at personal identification.
  4. When the form is presented, contents of the fields and the user's signing certificate with its serial number is sent to the server (although the serial number could be read from the certificate, it is better to leave this work to the client's side).
  5. A text file is created from the data inserted into the form and it is saved in a temporary folder.
  6. A new session is started with DigiDocService and a container created, where the freshly created file's hash is put (StartSession). Although it is possible to send the source files to the service, it is more sensible from the point of view of privacy and data volume to send hashes.
  7. Preparations are made to sign the container: The user's certificate is sent to DigiDocService together with the metainformation, i.e. role and location (PrepareSignature). In sample code, constants are used for metainformation, as asking them from the user is trivial and does not require a special example. The service returns a container hash that the client has to sign.
  8. The next page is displayed to the user, with the signing certificate's serial number and the hash to be signed.
  9. The user clicks the button "Sign", upon which the process is handed over to the JavaScript library that obtains the signature to the hash from the user.
  10. The signature is sent back to the web form with the next query, and the web form finalises the signing process (FinalizeSignature), downloads the signed container (GetSignedDoc) and closes the session (CloseSession).
  11. In the downloaded container, the hashes are replaced with the actual files that were saved on the disk beforehand, and forwarded to the claims handling service.
  12. The downloaded container and the response from the organisation are saved on the disk, from where the user can in turn download them using his browser.

After installing the web form, it must be made sure it has writing rights in its own folder and the beginning of claims.php must be changed: the command require_once must refer to the file DigiDoc.class.php in the claims handling service. If there is a wish to install the web form and the claims handling service into separate machines, the named file should also be copied from the source code of the claims handling service into the web form.

Mobile ID

Mobile ID's web form sequence diagram. The parts in the blue boxes are repeated until a query result is obtained. The communication between the mobile operator and the user is missing from the scheme, because it is not important from the point of view of development.

Download: Web form source code

A version of the web form that uses mobile ID. In general, it is an application quite like the web form (see also installing requirements there), with two important differences.

First, the client's certificate is not requested in the course of the SSL/TLS handshake -- the certificate is on mobile ID SIM and the user's web browser has no access to it. Instead, we use the DigiDocService method MobileAuthenticate for forwarding an authentication query. As method parameters, we give the user's phone number and language preference. After that, we invoke the method GetMobileAuthenticateStatus every five seconds until it returns authentication results. The method also returns the user's certificate, the validity of which has already been verified.

Second, the document is not signed with a web browser plugin but with mobile ID. Consequently, we do not invoke the methods PrepareSignature and FinalizeSignature, but MobileSign and GetStatusInfo: the first sends a signing query and the second we check every five seconds until we have a result. The rest of the steps needed for hashing documents, creating containers and determining metainformation are the same as with the web form.

The interval of five seconds that has been chosen for both status checks is good for testing, when the test numbers answer quickly. In a product environment, users take much longer to answer mobile ID queries, so that the interval can also be increased (especially the waiting time before the first query is made).

Note: The response obtained from the claims handling service is encrypted and the only receiver is the mobile ID's personal identification certificate - but as mobile ID does not support encryption, this response cannot be read. However, the contents of the response are not important at all -- the fact that the response was returned shows that the statement was correct and its sending successful.

Claims handling service

Claims handling service sequence diagram

Download: Service source code (needs also the SWIG-wrapper to work)

The claims handling service is written in PHP and uses DigiDocService for verifying the signature on the claim. For signing and encrypting the response, a SWIG wrapper around the libdigidoc library is used.

  1. A POST query is presented to the service with two mandatory fields: claim and cert.
    • cert must contain the personal identification certificate of the receiver of the response in a base64 coded DER form (this is not PEM, because the lines BEGIN and END are absent),
    • claim must contain the signed claim. The file's MIME type has to be either application/x-ddoc or application/vnd.bdoc-*.
  2. The service checks if the upload was successful and if the signature on the claim is valid. For validity check, the claim is sent to DigiDocService, using the query StartSession, where the flag bHoldSession has been put to negative so that the connection would be closed immediately. As a response, DigiDocService sends the signature's status.
    • Again, not the whole claim is sent to DigiDocService but data files with their hashes.
  3. The contained data files are read from within the claim and written on the disk.
  4. If the signature is valid, a response is generated. Its contents are not important to us, so it is a constant string.
  5. The libdigidoc library is reset and a signing container created (in the SWIG wrapper, the corresponding methods are initialize and new_signature_container).
  6. The generated response is added to the container (add_data_file) and signed (sign_container). The PIN used for signing can be either an argument of the signing function or a value of the key AUTOSIGN_PIN in the configuration file of the libdigidoc library (in this case when the function is invoked, the value of the parameter pin will remain NULL).
  7. The signed response is written on the disk and released from memory (methods save_signed_document and free_signature_container. NB! Here it would be reasonable to retain the container in the memory, as it will be read from the disk again right away -- but this cannot be done at the moment, as the library function createSignedDocInMemory produces a faulty XML, so we have to use the version that writes on the disk).
  8. The service creates a new encryption container (new_encryption_container) and encrypts the freshly generated response (encrypt_ddoc).
  9. The used transport key is encrypted with the public key of the certificate on the field cert and is added to the container (add_recipient).
  10. The encrypted container is saved on the disk (method save_encrypted_container. NB! Again, it would be better not to write the container on the disk, but the conversion of the container into XML in the memory is hidden from us in the library, and the only way to generate XML is to write the file). The memory taken for the container is freed (free_encryption_container) and the response is sent to the sender of the initial query.

While installing the service, it must be made sure that it has writing rights in its own folder and the conf.php file must be tweaked, where at least the DD_RESPONSE_SERVER address must be changed (this is used by the web form and its value should be set to the address of the claims handling service).

Attention: Keep in mind that the class necessary for the communication with the DigiDoc service is generated by PHP only once, and then saved to disk. If, following that, the developer alters either the rest of the source code or conf.php, or installs the PHP cURL module, then the wsdl.class.php must be deleted so that it could be generated as new.

Configuring the digital stamp

If the service uses a digital stamp instead of an ID card for signing, libdigidoc version 3.7 or newer is needed and the digital stamp drivers must be installed. Also, some changes have to be made in the settings file of libdigidoc library.

For installing drivers, see the chapter Using the crypto-stick.

The default location of the settings file of libdigidoc library is %PROGRAMFILES%\Estonian ID card\digidoc.ini (Windows) or /etc/digidoc.conf (Linux).

The following lines should be present in the settings file (module location may differ):

DIGIDOC_DEFAULT_DRIVER=1
DIGIDOC_DRIVERS=1
DIGIDOC_DRIVER_1_NAME=OpenSC
DIGIDOC_DRIVER_1_DESC=OpenSC projects PKCS#11 driver
DIGIDOC_DRIVER_1_FILE=/usr/lib/opensc-pkcs11.so

Here, it is necessary to use the freshly installed SafeNet eToken module instead of the OpenSC one. For this, just replace the existing module or add a new one. The last version would look like this (again, the actual module locations may differ):

DIGIDOC_DEFAULT_DRIVER=2
DIGIDOC_DRIVERS=2
DIGIDOC_DRIVER_1_NAME=OpenSC
DIGIDOC_DRIVER_1_DESC=OpenSC projects PKCS#11 driver
DIGIDOC_DRIVER_1_FILE=/usr/lib/opensc-pkcs11.so
DIGIDOC_DRIVER_2_NAME=eToken
DIGIDOC_DRIVER_2_DESC=SafeNet eToken PKCS#11 driver
DIGIDOC_DRIVER_2_FILE=/lib/libeToken.so.8

In addition, the number of the slot used for digital signing must be changed:

DIGIDOC_SIGNATURE_SLOT=0

Claims application

Claims application sequence diagram

Download: Claims application source code (Java, .NET)

This is a command line application that generates a claim on the basis of information gathered from the user and the personal identity document, puts it in a container, signs and sends it to the claims handling service. In response, a new container is delivered. The application decrypts it, verifies the signature and displays the contents of the container to the user.

The application is originally written in Java, where the JDigiDoc library is used, and then ported to .NET, where a COM library is used. Some subparts of the application (signing, personal identification, signature verification and data decryption) have also been rewritten in C++, but as its usage is quite similar to Java, there was no need to re-port the whole application.

  1. The application performs personal identification as described in personal identification and executed in the standalone personal identification application.
    • The .NET application verifies certificate validity using only CRL; for OCSP support, third party libraries must be used (e.g. Bouncy Castle).
  2. The user is asked for input for the claim - it is a simple, one-line text input. As libraries are only able to use files that have been saved on the disk, the input information is saved into a temporary file.
  3. The personal data read from the card is temporarily saved on the disk (libraries don't support reading the personal data file, which is why it has to be done manually, on the basis of the EstEID card user manual (in Estonian) -- read more about whether and how to read the personal data file from Using the personal data file.
  4. The data is contained in a DDOC container and signed -- in the course of the latter, the validity of the certificate for signing is also used.
  5. It is checked whether the container verifies and it is written on the disk.
  6. The container is sent to the claims handling service and an encrypted container is received in response.
    • As the COM library does not support decrypting, in the case of a .NET application, the server is requested an unencrypted response. Therefore, the next step is also missed.
  7. The transport key in the container is decrypted with the secret key of the user's personal identification certificate and it is used for decrypting the signed response from the service.
  8. The signed response is saved on the disk and then its signature is verified.
  9. The contents of the response from the service are displayed to the user.

NB! The Java application requires Java version 1.7 or later.

By default, personal identification in the claims application works only with cards employing 2048-bit keys. In order to use older cards, the relevant hash algorithm must be changed in the source code (see The fault in pre-2011 cards).

Using the application

The Java application comes with an Ant build script that compiles all classes and generates a JAR file out of them. Before compilation, the locations of used libraries have to be changed in the Ant script. After that, it is enough to deploy ant command that will create client.jar. The script requires Ant version 1.7 or later.

The Java application depends on the following libraries (All these come installed with the JDigiDoc package, so they only need referencing):

  • bcprov-jdk15on-147.jar
  • commons-codec-1.6.jar
  • commons-compress-1.3.jar
  • esteidtestcerts.jar
  • iaikPkcs11Wrapper.jar
  • jakarta-log4j-1.2.6.jar
  • jdigidoc-3.6.0.157.jar

The .NET application comes with Visual Studio 2010 project files that can be used for compiling the application. If there is none, a reference to the COM library has to be added to the project. After the reference has been added, under References, the Properties of DIGIDOCLIBCOMLib have to be opened and Embed Interop Types value set to False.

After that, the application can be deployed with the command:

java -jar client.jar [-cfg config] [url] # Java
EidClient.exe [url]                      # .NET

If an HTTPS connection is created with the service (very advisable), then it is checked that the issuer of the server certificate is known to the system. For Java, this means that the key should be present in keystore and for .NET that it should be installed in the Windows certificate repository.

If the service uses self-signed certificates (e.g. at testing), these need to be added to the Java keystore beforehand:

keytool -import -alias <certificate alias> -file <certificate location> -keystore <keystore location>

E.g. under Ubuntu:

# keytool -import -alias snakeoil -file /etc/ssl/certs/ssl-cert-snakeoil.pem -keystore /usr/lib/jvm/default-java/jre/lib/security/cacerts

For installing a self-signed certificate in the Windows certificate repository, it is enough to double-click it and choose "Install certificate".

Signing application

The application is a command line utility that is given a list of files as input data and it returns a container with signed files and OCSP validity confirmation.

C++

Download: Source code

Compiling:

gcc sign.cpp common/EstEIDConsolePinSigner.cpp -ldigidocpp -o sign

Usage:

./sign infile:mimetype... outfile
  • infile - files to sign
  • mimetype - the signed file's MIME tüüp type, e.g. text/plain
  • outfile - name of the generated container; if the file name ends with extension .bdoc, a signature in the BDOC format is created; otherwise, it is DIGIDOC-XML

Java

Download: Source code

Compiling (where $JAVA_LIB is the location of necessary Java libraries):

javac -cp $JAVA_LIB/jdigidoc.jar JavaSign.java

Usage:

java JavaSign [-cfg config] infile1 ... infileN outfile[.bdoc]
  • config - the used configuration file, by default jdigidoc.cfg is sought in the present folder
  • infile - files to sign
  • outfile - name of the created container; if the file name ends with extension .bdoc, a signature in the BDOC format is created; otherwise, it is DIGIDOC-XML

On deploying, Java classpath must have the following libraries (All these come installed with the JDigiDoc package, so they only need referencing):

  • bcprov-jdk15on-147.jar
  • commons-codec-1.6.jar
  • commons-compress-1.3.jar
  • esteidtestcerts.jar
  • iaikPkcs11Wrapper.jar
  • jakarta-log4j-1.2.6.jar
  • jdigidoc-3.6.0.157.jar

Requires Java 1.7 or later, because the MIME type of the signed file is determined by the class Files.

Personal identification application

The application is a command line utility that determines whether the user has access to private keys corresponding to the certificate (in other words, if the user knows the ID card's PIN1). The user enters the PIN1 code of the card in the reader, upon which a message is displayed on whether personal identification was successful or not. Should any other error occur (e.g. the certificate of the ID card is invalid), a corresponding error message is displayed.

By default, the applications work only with cards employing 2048-bit keys. In order to use older cards, the relevant hash algorithm must be changed in the source code (see The fault in pre-2011 cards).

C++

Download: Source code

Compiling:

gcc auth.cpp common/EstEIDConsolePinSigner.cpp -ldigidocpp -ldigidoc -o auth

The application is deployed without the arguments:

./auth

Java

Download: Source code

Compiling (where $JAVA_LIB is the location of necessary Java libraries):

javac -cp $JAVA_LIB/jdigidoc.jar:$JAVA_LIB/bcprov-jdk15on-147.jar JavaAuth.java

When deploying, the optional argument -cfg config can be given, which works similar to the signing application:

java JavaAuth [-cfg config]

On deploying, Java classpath must have the following libraries (All these come installed with the JDigiDoc package, so they only need referencing):

  • bcprov-jdk15on-147.jar
  • commons-compress-1.3.jar
  • esteidtestcerts.jar
  • iaikPkcs11Wrapper.jar
  • jakarta-log4j-1.2.6.jar
  • jdigidoc-3.6.0.157.jar

Signature verification application

A command line utility that verifies the signature on the container presented to it.

C++

Download: Source code

Requires Xerces-C++ XML Parser development headers. For Windows, these are available from the library's home page; for Linux, either the libxerces-c2-dev or libxerces-c-devel has to be installed.

Compiling:

gcc verify.cpp -ldigidocpp -o verify

Usage:

./verify infile
  • infile - the file whose signature is to be checked

Data decryption application

A command line utility that decrypts the container presented to it.

In DigiDoc applications, the data to be encrypted is first placed in a DDOC container, which is then placed within a CDOC container. While the application in question extracts the DDOC from the CDOC upon decryption, it leaves the data files inside the DDOC. The reason is that the DDOC might be encrypted and the signature might need verification before extraction. Furthermore, the developer might want to archive an unencrypted, but digitally signed DDOC document (as eID document encryption is not appropriate for this purpose.

Regardless of the current application's behavior, the inner DDOC is in most real-world cases not signed, allowing it to be extracted at once after decryption. For an example, see the signature verification application.

C++

Download: Source code

Compiling:

g++ decrypt.cpp -ldigidoc -o decrypt

Usage:

./decrypt infile pin outfile
  • infile - the file to decrypt
  • pin - PIN1 of the card used at decryption
  • outfile - the file in which to save the decrypted result

Simple access control in Apache httpd

A short and simple example on how to allow access only with an ID card and to certain users in an Apache httpd web server. For the examples below, the Apache httpd web server has to be configured, using SSL and requiring a certificate from users (i.e. SSLVerifyClient require).

If access has to be given to a small number of users that changes seldom, the easiest way is to do it with the SSLRequire directive:

SSLRequire %{SSL_CLIENT_S_DN_CN} in {"MÄNNIK,MARI-LIIS,47101010033", "SURNAME,NAME,PERSONAL IDENTIFICATION NUMBER"}

If access has to be given to a large number of people, it is more convenient to change the access files than the configuration files. We set up Basic authentication and use FakeBasicAuth:

AuthType Basic
AuthName "ID card only"
AuthBasicProvider file                      # Here obviously also some other module can be used
AuthUserFile /somewhere/folder/httpd.passwd # This file has to be at a secure location where others cannot read or modify it
Require valid-user

SSLOptions +FakeBasicAuth

Now when a SSL/TLS session with the server is started; mod_ssl tries to carry out Basic authentication with the client certificate's Distinguished Name as user name and "password" as password. Therefore, the corresponding lines have to be added to the access file for each person. This can be easily done with the htpasswd utility:

htpasswd -b /somewhere/folder/httpd.passwd <DN> password

A Distinguished Name in the right format can be found with the openssl utility:

openssl x509 -noout -subject -in <certificate>

The test card's DN is for example /C=EE/O=ESTEID/OU=authentication/CN=M\xC3\x84NNIK,MARI-LIIS,47101010033/SN=M\xC3\x84NNIK/GN=MARI-LIIS/serialNumber=47101010033.

Attention: Because of FakeBasicAuth, nothing but the literal word "password" can be used for password. As it is not hard to determine somebody's name and personal identification number, the DN and password used at authentication are also easy to find. Therefore, the server must be configured so that a protected folder cannot be accessed without SSL/TLS. Then, even if somebody tries to use another person’s DN, it will be replaced with the one read from his or her own certificate.

References