Erinevus lehekülje "Command line applications" redaktsioonide vahel

Allikas: eid.eesti.ee
Jump to navigation Jump to search
(Uus lehekülg: '= 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 p...')
(Erinevus puudub)

Redaktsioon: 29. mai 2014, kell 13:24

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.

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