manual openlimit middleware version 3 server ... -...

Manual

OpenLimit Middleware Version 3 Server

Product Version: 1.5

Administration Manual Date: 7 April 2015 Document version: 1.17

OpenLimit Middleware Version 3 Server 1.5 | Administration Manual, Document version: 1.17

2

© OpenLimit SignCubes AG 2011-2015

This documentation is the intellectual property of OpenLimit SignCubes AG.

It may not be duplicated or published (either completely or in part) without the prior written

consent of OpenLimit SignCubes AG, irrespective of the method or the means employed, be they

electronic or mechanical. The software or hardware descriptions used in this documentation, as

well as the company or brand names, are in most cases registered trademarks or brands and

are, as such, the property of the relevant manufacturers. They are used without guarantee of

free usability. We essentially conform to the writing conventions used by the manufacturers .

The inclusion of product and commercial names etc. in this documentation – even without this

being indicated specifically – does not justify the assumption that the use of such names can be

considered as being unrestricted under the terms of protective legislation on trademarks and

brand names.

This documentation offers administrators instructions for installation and configuration of the

OpenLimit Middleware Version 3 Server, product version 1.5 (abbreviated to OpenLimit V3

Server). In addition, start-up and exiting of the V3 Server software is also described.

In individual cases there can be variations concerning processes described in the

documentation and the actual application. OpenLimit SignCubes AG is not liable for possible

variations or their consequences.

Please send any information or comments you may have to [email protected].

OpenLimit SignCubes AG

Zugerstraße 74

CH - 6341 Baar

Switzerland

www.openlimit.com

mailto:[email protected]


3

Contents

1 Introduction .................................................................................................... 8

1.1 Requirements for Secure Operation .................................................................................... 8

1.2 System requirements .............................................................................................................. 9

2 First Steps ...................................................................................................... 10

2.1 Installation of the OpenLimit V3 Server ........................................................................... 10

2.2 Uninstallation of the V3 Server ............................................................................................ 11

2.3 Update ........................................................................................................................................ 11

2.4 Downgrade of Maintenance Packages................................................................................ 12

2.5 General Restrictions ............................................................................................................... 12

2.6 General Information for the Operation of the V3 Server............................................... 12

2.6.1 Manual Stop of the V3 Server .......................................................................................................................... 12

2.7 Details on Using the OpenLimit V3 Server with SELinux ................................................ 13

3 General Information ....................................................................................... 14

3.1 Certificate Qualities ............................................................................................................... 15

3.1.1 Advanced Certificates ....................................................................................................................................... 15

3.1.2 Qualified Certificates ........................................................................................................................................ 15

3.1.3 Accredited Certificates ..................................................................................................................................... 15

3.2 Security Compatibility and Suitable Algorithms ............................................................. 16

3.2.1 Trusted List ......................................................................................................................................................... 16

3.2.2 Algorithm Catalogs ............................................................................................................................................ 17

3.3 Communication Model of the OpenLimit V3 Server ........................................................ 17

3.3.1 Overview .............................................................................................................................................................. 18

3.3.2 SDK Interface ...................................................................................................................................................... 18

3.3.3 Timestamp (RFC 3161) ........................................................................................................................................ 18

3.3.4 OCSP Response (RFC 2560) .............................................................................................................................. 19

3.3.5 Certificate Revocation List (CRL) (RFC 3280) ............................................................................................... 19


4

4 Delivery State ............................................................................................... 20

4.1 Trusted Lists ........................................................................................................................... 20

4.2 Configuration Files ................................................................................................................ 20

4.2.1 bootsvr.cfg (/home/olsc/v3server/bin) ....................................................................................................... 20

4.2.2 siqCRL.cfg (/home/olsc/v3server/bin).......................................................................................................... 20

4.2.3 siqDiag.cfg (/home/olsc/v3server/bin) ......................................................................................................... 21

4.2.4 siqOCSP.cfg (/home/olsc/v3server/bin) ........................................................................................................ 21

4.2.5 siqPolicies.cfg (/home/olsc/v3server/bin) ................................................................................................... 21

4.2.6 siqSEMKSrv_svr.cfg (/home/olsc/v3server/bin) ......................................................................................... 24

4.2.7 siqService.cfgLog (/home/olsc/v3server/bin) ............................................................................................ 25

4.2.8 siqTSP.cfg (/home/olsc/v3server/bin) .......................................................................................................... 25

5 Configuration ................................................................................................ 27

5.1 bootsvr.cfg .............................................................................................................................. 27

5.1.1 Specify the Available Java Heap Memory (-Xmx) ....................................................................................... 27

5.1.2 Protection of Java (-Xrs) ................................................................................................................................. 27

5.1.3 Available Memory for Java Threads (-XX) ................................................................................................... 27

5.1.4 File Encoding to Be Used (-Dfile.encoding) ................................................................................................. 28

5.1.5 Available Memory for Java Threads (-Djava.awt.headless) ..................................................................... 28

5.1.6 Proxy Configuration (-Dhttp) .......................................................................................................................... 28

5.1.7 Further Java Options ....................................................................................................................................... 29

5.2 siqDiag.cfg ............................................................................................................................... 29

5.2.1 Enabling the Diagnosis Functionality ........................................................................................................... 29

5.2.2 Determining the Diagnostic Scope ................................................................................................................. 31

5.2.3 Rotation of Diagnostic Log Files .................................................................................................................... 32

5.3 siqSEMKSrv_svr.cfg ................................................................................................................ 32

5.3.1 Settings That Must Not Be Modified .............................................................................................................. 32

5.3.2 Determining the VerificationModel ............................................................................................................... 33

5.3.3 Changing the Order of the Revocation Check ............................................................................................. 33

5.3.4 Determining the Archiving Period for Retaining Revocation Information ........................................... 34


5

5.3.5 Certificate Key Usability Settings (KeyUsage) ..................................................................................... 34

5.3.6 Setting the Maximum File Size for Signature Information ....................................................................... 34

5.3.7 Keep the Socket for the WebService Alive (KeepAlive) .............................................................. 35

5.3.8 Collecting Requests That Are Currently Not Processable (BackLog)............................................... 35

5.3.9 Retry Start-Up (RetryCreate, RetryCreateWait) .............................................................. 35

5.3.10 Maximum HTTP Message Size (MaxHTTPMsgSize)........................................................................... 36

5.3.11 Binding the V3 Server to a Network Address (SOAPHost, SOAPPort) ....................................... 36

5.3.12 Using External OCSP Responses during a Signature Verification .......................................................... 36

5.4 siqPolicies.cfg ......................................................................................................................... 37

5.4.1 Options that must not be modified ............................................................................................................... 37

5.4.2 Policies for OCSP Response Retrieval .......................................................................................................... 38

5.4.3 Certificate Revocation List (CRL) Policies ................................................................................................... 38

5.4.4 Timestamp Policies ........................................................................................................................................... 39

5.5 siqCRL.cfg ................................................................................................................................ 39

5.5.1 Formatting of Issuer DN .................................................................................................................................. 40

5.5.2 Formatting of a CDP URL ................................................................................................................................. 40

5.5.3 Determining the Issuer DN of a Certificate .................................................................................................. 41

5.6 OCSP ........................................................................................................................................... 41

5.6.1 siqOCSP.cfg .......................................................................................................................................................... 41

5.6.2 OCSP Cache.......................................................................................................................................................... 41

5.7 Retrieval of Timestamps ...................................................................................................... 42

5.7.1 General ................................................................................................................................................................ 42

5.7.2 The TSP Module GenericTSPModule ................................................................................................ 43

5.7.3 siqTSP.cfg ........................................................................................................................................................... 43

5.7.4 The Trustmanager in Detail ............................................................................................................................ 43

5.8 Logging ..................................................................................................................................... 44

5.8.1 Activate Logging ............................................................................................................................................... 44

5.8.2 Order of Processing Log Configuration Files .............................................................................................. 45

5.8.3 General Processing Instructions for Configuration Files ......................................................................... 45

5.8.4 Details About the Individual Configuration Sections ................................................................................ 45


6

5.8.5 Log rotation ....................................................................................................................................................... 48

6 Configuration via the AdminTool ..................................................................... 51

6.1 Important Information ........................................................................................................... 51

6.2 AdminTool Functions .............................................................................................................. 51

6.2.1 Importing a Certificate ..................................................................................................................................... 51

6.2.2 Deleting a Certificate ....................................................................................................................................... 52

6.2.3 Manual Storage of Imported Certificates .................................................................................................... 52

6.2.4 Getting Information About a Specific Certificate ...................................................................................... 52

6.2.5 Displaying Information About All Available OpenLimit V3 Server Certificates ................................... 53

6.2.6 Displaying Quality Information About the Indicated Certificate ............................................................ 55

6.2.7 Changing the Log Level of the OpenLimit V3 Servers ............................................................................... 56

6.3 AdminTool Options ................................................................................................................ 56

6.3.1 Options -h -? -help -–help ........................................................................................................ 56

6.3.2 Option -trustlevel ............................................................................................................................... 56

6.3.3 Option -kernelAddress <kernel_adress> ...................................................................... 57

6.3.4 Option -kernelPort <kernel_port> ..................................................................................... 57

7 Electronic Signature Verification ................................................................... 58

7.1 Introduction ............................................................................................................................ 58

7.1.1 Verification of Document Type and Check for Available Signatures ..................................................... 59

7.1.2 Verification of SignedAttributes and Correlation with the Document .................................................. 59

7.1.3 XML – Verification of the SignedInfo and Correlation with the Document ........................................... 59

7.1.4 Certificate Chain Structure and Technical Signature Verification ......................................................... 59

7.1.5 Validity Model for Signature Verification .................................................................................................... 59

7.1.6 Verification of Algorithm Security Compatibility ...................................................................................... 60

7.2 Verification Results (Importance of Return Values) ....................................................... 61

7.2.1 SIQ_E_VRF_INCOMPLETE (e1002000) ............................................................................................................... 61

7.2.2 SIQ_E_VRF_NOSIGNATURES (e1002001) .......................................................................................................... 62

7.2.3 SIQ_E_VRF_WRONGMESSAGEDIGEST (e1002002) .......................................................................................... 62

7.2.4 SIQ_E_VRF_WRONGSIGNATURE (e1002003) ................................................................................................... 62


7

7.2.5 SIQ_E_VRF_WRONGCERTIFICATE (e1002004) ................................................................................................. 63

7.2.6 SIQ_E_VRF_CERTIFICATE (a1002005) .............................................................................................................. 63

7.2.7 SIQ_E_VRF_WEAKALGORITHM (a1002006) ...................................................................................................... 64

7.2.8 SIQ_E_VRF_INFORMATION (61002FF0) ............................................................................................................ 64

7.2.9 SIQ_E_VRF_SUCCESS (21002FFF) ..................................................................................................................... 64

8 Information on Technical Questions ............................................................... 65

8.1 Which Hash Algorithms Are Supported? ........................................................................... 65

8.2 Which Signature Types Are Supported? ........................................................................... 65

8.2.1 Signature Container ......................................................................................................................................... 65

8.2.2 Technical Signatures ........................................................................................................................................ 65

8.2.3 Padding Schemes .............................................................................................................................................. 65

8.3 Error Handling ........................................................................................................................ 66

8.3.1 Support ............................................................................................................................................................... 66


8

1 Introduction

The OpenLimit V3 Server is designed to verify signatures in CMS (RFC 5652), PKCS #7 and XML-DSig format.

Thereby, available electronic signatures are processed in the following container formats:

The signature exists as a detached signature to the original document

Signature and document are encoded in a connected data container

The signature is part of a PDF document and embedded in the document as PDF signature.

For further information concerning the verification of electronic signatures, please

see chapter “7 Electronic Signature Verification“.

This documentation describes the correct installation and configuration of the OpenLimit V3

Server software. In addition, possible proxy settings are described by way of example and

reference notes concerning the operation of the OpenLimit V3 Server are given.

The OpenLimit V3 Server supports – in this configuration – the following operating systems:

RedHat 5.6 64-bit

RedHat 6.0 64-bit

SUSE Linux Enterprise (SLES) 11 64-bit

This documentation is exclusively addressed to users of the OpenLimit V3 Server on one of the

operating systems listed above. Use of the product on another operating system may require

different configurations not described in this documentation.

1.1 Requirements for Secure Operation

The OpenLimit V3 Server has an integrated recognition of modifications on the delivered binary

files and several configuration files. During the self-test, the correctness of the delivered

binary files is checked when starting the software. If the self-test of the product during start-up

is successful, the start-up is successfully completed.

In case the verification of components has failed, start-up is interrupted. If there are further

modules loaded during runtime, the hash values of these modules are also verified during

loading. In the event of a successful result the module will be loaded. If the verification has

failed the module will not be loaded and the V3 Server will be deactivated. (Please see chapter

8.2 Which Signature Types Are Supported?)


9

1.2 System requirements

Processor: Intel / AMD (Dual-Core) or similar

RAM: 8 GB RAM

Operating system: RedHat 5.6 64-bit, RedHat 6.0 64-bit, SUSE Linux Enterprise 11

(with current patch level)

Please ensure that no services allowing unsecured remote access to the system are installed. In

addition, the application of an IDS (Intrusion Detection System) is recommended to identify any

intrusion into the system and to react appropriately.


10

2 First Steps

The OpenLimit V3 Server is delivered as an RPM installation package. The product is divided in

three different RPM packages:

Main package

OpenLimit-Middleware-V3Version-3-Server-1.2.1.xxx.-

<SoftwareVersion>.<RPMPaketNummer>.x86_64.rpm.

Maintenance packages, that can be updated individually

OpenLimit-Middleware-Version-3-Server_Database-

<SoftwareVersion>.<RPMPaketNummer>.x86_64.rpm

OpenLimit-Middleware-Version-3-Server_CertCRL-


The following chapters describe the installation, uninstallation, update and downgrade of the

OpenLimit V3 Server. To carry out these actions, root user rights are required.

In this document the installation path /home/olsc/v3server/bin is specified for the

OpenLimit V3 Server.

2.1 Installation of the OpenLimit V3 Server

The V3 Server will be installed with the following command:

cd <file path to the three RPM packages (main / maintenance

packages)>

rpm -i OpenLimit-Middleware-Version-3-Server-

<SoftwareVersion>.<RPMPackageNumber>.x86_64.rpm





The packages depend on each other, that is why all modules have to be installed on one line during

the first installation.

The installation leads to the following modifications on the system:

A group and a user olsc is created

Files are unpacked into the folder /home/olsc/v3server/bin

An init.d script and logrotate.d configuration are created

The init.d script is registered with the operating system in order to start the

V3 Server automatically when the system is started

If the operating system is secured with SELinux, please refer to Section 2.7 on installation and

operation of the V3 Server with SELinux.


11

2.2 Uninstallation of the V3 Server

The V3 Server will be uninstalled with the following command:

rpm -e OpenLimit-Middleware-Version-3-Server OpenLimit-

Middleware-Version-3-Server_Database OpenLimit-Middleware-

Version-3-Server_CertCRL

The files of the OpenLimit V3 Server (in /home/olsc/v3server/bin) are deleted, with a

few exceptions. Some specific files will remain in the system:

Configuration files of the V3 Server in /home/olsc/v3server/bin which

have been changed by the customer will be marked in situ with .rpmsave and

retained.

Log/ diagnostic files remain in /home/olsc/v3server/bin/log/ or

/home/olsc/v3server/bin/diag/

The hidden user folder /home/olsc/.olsc/ will be preserved. This is where

the bcuser.db, which holds the certificates and certificate options imported

with the AdminTool, is stored.

Dependent packages will also be uninstalled

These remaining files can be stored and reused for a new installation. If the remaining files are

not required anymore, the command userdel -r -f olsc can be executed. This deletes

the user olsc together with the group and the complete directory /home/olsc.

2.3 Update

Maintenance packages can be updated through the following command:

rpm -Uvh OpenLimit-Middleware-V3-Server_Database-


or

rpm -Uvh OpenLimit-Middleware-Version-3-Server_CertCRL-

<SoftwareVersion>.<rpmPackageNumber>.x86_64.rpm

The main package can be updated through the following command:

rpm -Uvh OpenLimit-Middleware-Version-3-Server-







12

2.4 Downgrade of Maintenance Packages

Maintenance packages can be downgraded through the following command:

rpm –Uvh –oldpackage OpenLimit-Middleware-V3-Server_Database-

<Major.Minor.LowerRevision>.<LowerRpmPackageNumber>.x86_64.rpm

or

rpm –Uvh –oldpackage OpenLimit-Middleware-V3-Server_CertCRL-

<Major.Minor.LowerRevision>.<LowerRpmPackageNumber>.x86_64.rpm

2.5 General Restrictions

The installation of multiple V3 Servers on a single host via RPM mechanisms is not supported.

This is true for the installation, update and downgrade equally.

The maintenance packages can only be installed together with the corresponding main package

(of the same major-minor-software version.).

Example:

Maintenance package 1.3.1 can be installed together with main package 1.3.0, but not with main

package 1.4.x or 1.2.x.

2.6 General Information for the Operation of the V3 Server

The V3 Server starts together with the operating system. To start the V3 Server manually,

please use the following command:

/etc/init.d/v3server start

Similarly, the V3 Server is stopped when the operating system is shutdown. To stop the V3

Server manually, please use the following command:

/etc/init.d/v3server stop

The status of the V3 Server, quick help and version information can be queried as follows:

/etc/init.d/v3server status

/etc/init.d/v3server help

/etc/init.d/v3server version

During installation, a user account named olsc is created. This account is a service identifier

(without login option) that does not provide a shell.

2.6.1 Manual Stop of the V3 Server

The V3 Server has been started in the interactive mode via the command siqService with

the option –i. By pressing the key “q“ the server is stopped.


13

In addition, siqService can be stopped with the common Linux command killall. For

this purpose please use the following command:

killall -15 siqService

When using killall the signal 15 is transmitted to the process by means of the process

name. This way there is enough time for the process to stop regularly. In contrast, the signal 9

(killall -9 siqService) stops the process immediately. Here there is no time left for

the process for clean-up operations.

Please note that the manual stop via killall -15 may take some time. Using this command all

remaining requests are processed by the software before it is stopped.

2.7 Details on Using the OpenLimit V3 Server with SELinux

If SELinux is activated on your operating system, then you must be aware of some additional issues

during the installation and use of the V3 Server. Installation and operation of the V3 Server with

SELinux were checked in the profile targeted in the mode enforcing of an unaltered SELinux

installation. In other SELinux profiles and modes, other/further steps may have to be performed.

During installation of the V3 Server, a new system user ‘olsc’ is entered. For this reason, SELinux

must be changed into the ‘permissive’ mode or temporarily stopped for installation of the V3 Server.

After the V3 Server is installed, a login account for the new user ‘olsc’ must be set up under SELinux.

The purpose of this is to allow under SELinux the commands which control the V3 Server. The

command with which the SELinux user ‘olsc’ is set up is as follows:

semanage login -a -s user_u olsc


14

3 General Information

The OpenLimit V3 Server is designed for the use of X.509 Version 3 (RFC 3280) certificates

(including in relation to XML signatures) and can verify electronic signatures that have been

created with these certificates or with the corresponding key pair. The software does not

support other certificate types or key containers (e.g. PGP).

Most important for the application of certificates are the guidelines in the specification

Common PKI 2.0 (http://www.common-pki.org/uploads/media/Common-PKI_v2.0.pdf), especially

concerning the encoding of certificates in ASN.1 format. Due to the fact that certificates use

cryptographic primitives it is important to mention at this point which algorithms and

processes are supported within certificates.

The software supports the following hash processes within certificates:

SHA-1 (no longer suitable for QES)

SHA-224

SHA-256

SHA-384

SHA-512

RIPEMD-160 (no longer suitable for QES)

The following signature processes are supported within certificates:

RSA from 1024 to 4096 bits

DSA key (sha1DSA)

ECDSA with NIST and Brainpool curves

When using certificates, a distinction is made between advanced, qualified and accredited

certificates. This distinction is a decisive factor for the legal certainty of the electronic

signature of the respective document.

In Europe the legal basis is defined in the following legal text:

Directive 1999/93/EC

In Germany the legal basis is defined in the following legal texts:

Signature Act

Digital Signature Ordinance

For current versions of these three texts, please visit the following website:

http://www.bundesnetzagentur.de/DE/Sachgebiete/QES/Rechtsgrundlagen/Rechtsgrundlagen_node.html

http://www.common-pki.org/uploads/media/Common-PKI_v2.0.pdf

http://www.bundesnetzagentur.de/DE/Sachgebiete/QES/Rechtsgrundlagen/Rechtsgrundlagen_node.html


15

3.1 Certificate Qualities

Please see the German Signature Act (reference see 3 General ) in particular §2 and §7.

3.1.1 Advanced Certificates

Advanced certificates can be created by everyone and applied for various purposes

(encryption, signature, authentication etc.). However, advanced certificates are not suitable to

unequivocally guarantee signature authenticity, because the private key applied may not be as

secure as it is the case with qualified certificates, for example.

3.1.2 Qualified Certificates

Qualified certificates1 are characterized by the fact that they are issued by a registered or

accredited certification service provider (CSP). These certification service providers are

verified separately by the Federal Network Agency and have to guarantee, amongst others, that

the issued key pair for the respective certificate is unambiguous and can be allocated to a

natural person without doubt. Similarly, qualified certificates have to meet the requirements of

the Federal Network Agency concerning the quality of applied cryptographic algorithms (hash

and signature algorithms). The assigned certificate must have been signed by the certification

service provider with a qualified electronic signature. It can exclusively be used for signing and

it must be indicated that it is a qualified certificate (cf. SigG profile in Common PKI).

3.1.3 Accredited Certificates

A certification service provider is considered accredited, if its trust center received a

confirmation by the Federal Network Agency based on regular inspections by the Federal Office

for Information Security (BSI) or other accredited inspection authorities. As a result the

accredited certification service provider receives a qualified certificate from the Federal

Network Agency – the root authority for qualified certificates with provider accreditation in

Germany. A signature certificate signed with this qualified certificate is colloquially called an

accredited certificate.

Corresponding to the certificate qualities, the qualities of the corresponding signatures

emerge. This means:

With advanced certificates advanced signatures are created

With qualified certificates qualified signatures are created

With accredited certificates accredited signatures are created

1 Qualified certificates also include accredited certificates, which are discussed later


16

Please note that electronic signatures that have been created with a qualified or accredited

certificate underlie the German Signature Act, unlike advanced certificates or certificates of

other countries2. In Germany, certificate verification is carried out according to the chain

model, as determined in the Signature Act, whereas all other certificates (advanced or from

abroad) are verified according to the hybrid model3 (modified shell model).

The main difference between chain model and hybrid model is that with the chain model the

publisher certificate may already be expired at the time the private key of the end-user

certificate is used. With the chain model the sole decisive factor is that the publisher certificate

was valid and not expired at the time of end-user certificate creation. Regarding the hybrid

model it is assumed that all certificates of the verified chain were valid at the time the private

key of the end-user certificate was used. For further explanations concerning validity models,

please see chapter 7.1.5 Validity Model for Signature Verification and visit the web page of the

Federal Network Agency (http://www.bundesnetzagentur.de).

3.2 Security Compatibility and Suitable Algorithms

The OpenLimit V3 Server features two mechanisms to identify suitability and quality of

certificates and signatures.

3.2.1 Trusted List

Applying a trusted list signed by the manufacturer, the certificates of registered and accredited

certification service providers are transmitted to the product. Signatures, based on this trusted

list, which can be traced back to a registered or accredited root are tested against the

algorithm catalog included in this product. The number of qualified and accredited certificates

in this product is only determined through the manufacturer’s trusted list.

A trust base update is delivered as an rpm archive. It consists of a configuration database

(“bcsystem.db”) for the OpenLimit V3 Server and the corresponding signature file

(“bcsystem.db.sig”) to protect its integrity.

2 This concept of accreditation of a certification service provider is only used in Germany. In other (European) countries this

differentiation does not exist or the operation of a certification service is not subject to the same strict regulations as in

Germany.

3 Generally, when speaking of “signature validation” the “modified shell model” or the “hybrid model” is meant. This model

differs from the original shell model by taking the “assumed signing time” as the verification time. With the original shell

model technical signatures (e.g. regarding SSL authentication) were generally verified using the current time (“now time”).

http://www.bundesnetzagentur.de/


17

3.2.2 Algorithm Catalogs

The reliability of a qualified electronic signature primarily depends on the strength of the

underlying cryptographic algorithms. In the so-called algorithm catalog, an “overview of the

suitability of algorithms for qualified electronic signatures according to the German Signature

Act“, algorithms are listed, that are considered suitable for qualified electronic signatures at

least for the coming years4. This overview of algorithms and the appropriate parameters that

are considered suitable for

the creation of signature keys,

the hash of data to be signed or

the creation and verification of qualified electronic signatures

as well as the suitability expiration date are published by the Federal Network Agency in the

German Federal Gazette as well as under:

http://www.bundesnetzagentur.de/cln_1931/DE/Sachgebiete/QES/Veroeffentlichungen/Algorithm

en/algorithmen_node.html

Suitability is redefined annually and when required.

An algorithm catalog update is delivered as a ZIP archive. It consists of several configuration

files (“algcat_*.cfg“) for the V3 Server and the appropriate signature files

(“algcat_*.cfg.sig“) to protect the integrity of the respective configuration file. A

downloaded update has to be unpacked in the folder bin/Data and, in doing so, the existing

files need to be overwritten. The update will take effect after the software has been restarted.

Signatures with algorithms, losing evidentiary value according to the algorithm catalog – which

are in other words become “weak” – need to be renewed in good time before expiration, i. e.

signed data needs to be signed again with a conclusive algorithm.

3.3 Communication Model of the OpenLimit V3 Server

The following figure gives an overview about the external interfaces of the OpenLimit V3

Server. This information is of special importance for administrators to carry out – if necessary –

configurations on the firewall or to administrate the product concerning the application of

proxy configurations in a correct manner.

Please ensure that the communication of the OpenLimit V3 Server does not clash with the settings of

an existing firewall and be negatively impacted upon as a result!

4 Currently the Bundesnetzagentur intends to determine the suitability of algorithms for a period of 7 years

http://www.bundesnetzagentur.de/cln_1931/DE/Sachgebiete/QES/Veroeffentlichungen/Algorithmen/algorithmen_node.html

http://www.bundesnetzagentur.de/cln_1931/DE/Sachgebiete/QES/Veroeffentlichungen/Algorithmen/algorithmen_node.html


18

3.3.1 Overview

Figure 1: Overview of communication interfaces

3.3.2 SDK Interface

The SDK interface of the OpenLimit V3 Server is a SOAP-based interface and runs via port 18080.

Via this port, the functionality of the OpenLimit V3 Server is accessible for SDK clients from the

outside. Please note that the availability of the OpenLimit V3 Server depends on the

configuration of the SOAPHost and SOAPPort in the configuration file siqSEMKSrv_svr.cfg

(or 4.2.6 siqSEMKSrv_svr.cfg (/home/olsc/v3server/bin)). The modification of SOAPHost and

SOAPPort is described in chapter 5.3.11 Binding the V3 Server to a Network Address

(SOAPHost, SOAPPort).

3.3.3 Timestamp (RFC 3161)

Timestamps serve as proof of data existence at a certain point in time. This point in time is

allotted by a Time Stamping Authority (TSA). According to the German Signature Act, TSAs are

certification service providers authorized to issue qualified timestamps and therefore make

reliable statements that data existed at a certain point in time.

Timestamps are requested and retrieved via the HTTP protocol (usually port 80), i.e., the use of

a HTTP proxy server via Java options (5.1.6 Proxy Configuration) is possible as well.

A timestamp can also be requested with the help of SSL (HTTPs). In this case communication is

effected (usually) via port 443.

Basically the time stamping service provider used defines on which port the TSA to be used will

be available. Therefore it cannot be assumed that the Time Stamping Authority can always be

reached via port 80. Rather, it is important which Time Stamping Authority you would like to


19

use and then decide which firewall and proxy software settings need to be configured.

According to RFC 2560 the OCSP protocol is not absolutely bound to the HTTP protocol.

3.3.4 OCSP Response (RFC 2560)

An OCSP response (online certificate status) provides information about the validity status of a

certificate. According to RFC 2560 it must be retrieved from one of the following awarding

agencies:

Certification Service Provider (CSP) of the certificate

a third-party provider trusted by the CSP

a third-party provider, specifically authorized by the CSP to deliver online validity

status for this certificate

OCSP responses are requested and retrieved via the HTTP protocol, i.e. the use of a HTTP proxy

server via Java options (5.1.6 Proxy Configuration) is possible as well.

Usually the OCSP responder URL is encoded in the certificate. That means that the OpenLimit V3

Server analyzes the URL encoded in the certificate and transmits the OCSP request to the OCSP

service. Basically the OpenLimit V3 Server uses the HTTP protocol for this transmission. Usually

the certification service providers offer their service via port 80. However, it is permitted to

provide the OCSP service on other ports. An inappropriate configuration of the firewall or proxy

software can be the reason for unsuccessful OCSP-based signature verifications, because a

request transmitted via an “exotic port“ may not have been processed any further or may not

have been allowed through.

3.3.5 Certificate Revocation List (CRL) (RFC 3280)

A revocation list is a list with a timestamp, which identifies revoked certificates at a certain

point in time and is available at a public access point. Each revoked certificate is identified in

the certificate revocation list by its serial number. Similar to OCSP responses certificate

revocation list retrieval is affected via the address specified by a certification service provider.

However, as certificate revocation lists are periodically updated, a time delay between

revocation and signature creation may occur. That is why a signature created with a revoked

certificate is considered valid until the certificate revocation list is updated.

Certificate revocation list updates are requested and retrieved via the HTTP protocol, i.e. the

use of an HTTP proxy server via Java options (5.1.6 Proxy Configuration) is possible as well.

Certificate revocation lists can also be retrieved with the help of the LDAP protocol (port 389).

When processing certificates that require certificate revocation list retrieval via LDAP, your

firewall needs to be configured accordingly.


20

4 Delivery State

4.1 Trusted Lists

Trusted lists are delivered together with the OpenLimit V3 Server and can be updated

afterwards (see also 2.3 Update). Therefore, the configuration database of the OpenLimit V3

Server is exchanged. Manually imported certificates remain unaffected.

4.2 Configuration Files

4.2.1 bootsvr.cfg (/home/olsc/v3server/bin)

[Java]

Library = jvm/lib/amd64/server/libjvm.so

[JavaOptions]

-Xmx768m

-XX:ThreadStackSize=2048

-Xrs

-XX:+UseParNewGC

-server

-Dfile.encoding="UTF-8"

-Djava.awt.headless=true

## HTTP proxy settings

#-Dhttp.proxyHost=192.168.1.1

#-Dhttp.proxyPort=3128

#-Dhttps.proxyHost=192.168.1.1

#-Dhttps.proxyPort=3128

#-Dhttp.proxyUser=mustermann

#-Dhttp.proxyPassword=geheim

[Kernel]

Library = siqSEMk_Srv_LE_siglog.ols

LogModule = siqLogger.ols

DiagModule = siqDiag.ols

4.2.2 siqCRL.cfg (/home/olsc/v3server/bin)

#[Deutsche Telekom Root CA 2]

#URL=http://pki.telesec.de/cgi-bin/service/af_DownloadARL.crl?-

crl_format=X_509&-issuer=DT_ROOT_CA_2


21

4.2.3 siqDiag.cfg (/home/olsc/v3server/bin)

[Diagnosis]

DataDir = diag

FileNameTemplate = dgInfo_

Interval = 300 # seconds

StartInterval = 60 # seconds

Permission = 640

[Ignore]

#systemInfo

procInfo

moduleList

#jobsInfo

netOCSP

netCRL

netTSP

4.2.4 siqOCSP.cfg (/home/olsc/v3server/bin)

[Common]

DigestAlgName="SHA-1"

[OPENLiMiT_CA]

Pattern="OPENLiMiT"

URL="http://localhost:8080/ocsp/ocsp"


[TeleSec_PKS_SigG]

Pattern="TeleSec PKS SigG"

URL="http://pks.telesec.de/ocspr"


[QuoVadis]

Pattern="QuoVadis"

URL="http://ocsp.quovadisoffshore.com"


4.2.5 siqPolicies.cfg (/home/olsc/v3server/bin)

#############################

# Cache settings #

#############################


22

[RevocationValues_CachingInterval]

# in minutes

Policy="0"

[CertificateChain_CachingInterval]

# in minutes

Policy="0"

#############################

# OCSP settings #

#############################

[Timeout_OCSP_Cache]

# in milliseconds

Policy="900000"

[Timeout_OCSP]

# in milliseconds

Policy="9000"

[Timeout_OCSP_Retry]

# in milliseconds

Policy=4000 # 60000 maximum value

[FailedOCSPRequestAttempts]

# repeat not more than

Policy="3"

[FailedOCSPRequestSleepInterval]

# wait in milliseconds

Policy="50"

#############################

# CRL settings #

#############################

[Timeout_CRL]

# either sequential processing

#Policy="-1"

# or in milliseconds

Policy="60000"

[FailedCRLRequestAttempts]



23

Policy="3"

[FailedCRLRequestSleepInterval]


Policy="50"

#############################

# Timestamping settings #

#############################

[Timeout_TSP]

# in milliseconds

Policy="30000"

[FailedTSPRequestAttempts]


Policy="3"

[FailedTSPRequestSleepInterval]


Policy="50"

#############################

# SIGNER settings #

#############################

[SignerInfo_SigningCertificate]

Policy="SHA-256"

#############################

# CADES settings #

#############################

[CADES_Format]

# THIS IS FOR TESTING ONLY! DO NOT SWITCH ON !!!

#Policy="CADES_BES"

#Policy="CADES_EPES"

#Policy="CADES_T"

#Policy="CADES_XLONG"

#Policy="CADES_X_TYPE1"

#Policy="CADES_XLONG_TYPE1"

#Policy="CADES_X_TYPE2"

#Policy="CADES_XLONG_TYPE2"


24

#Policy="CADES_C"

#Policy="CADES_A"

[SignerInfo_CompleteReferences]

Policy="SHA-256"

#[SignerInfo_TimeReference]

#Policy="081208121942Z"

4.2.6 siqSEMKSrv_svr.cfg (/home/olsc/v3server/bin)

[Kernel]

Mode = Server

JARDirectory = "ext"

TIMESTAMP = 20110509000000

BUILD_NO = 1

OEM = "OpenLimit SignCubes AG"

MaxTimeLockWait = 100000 # 10* 10 * 1000 ms

CfgFileJobMgr = "jobmgr.cfg" # handled internally

MultiJobMgr = 4 # internal, do not touch

#Settings required for signature verification

[Verification]

RevocationCheck = AUTO

VerificationModel = DEFAULT

#Optional settings for OCSP handling

#ErrorOnUnusedEmbeddedOCSP

#UseEmbeddedOCSPIfOld

#Settings for ArchiveCutoffPeriod in (years)

ArchiveCutoffPeriod_accredited = 30

ArchiveCutoffPeriod_qualified = 5

ArchiveCutoffPeriod_advanced = 0

#AcceptNullKeyUsage=true

InputFileSizeLimit = 50 # MiB, size limit for files other than

binary file (detached or hash) and pdf

PDFSizeLimit = 50 # MiB, maximum size 50MiB, size limit for pdf

(data buffer and file)

# WebService

[ECARD]

Library = siqeCardAPI_svr.ols

EscapeString_0A = " "

ENABLED = true


25

KeepAlive = "yes"

SOAPHost = 127.0.0.1

SOAPPort = 18080

BackLog = 100

RetryCreate = 10

RetryCreateWait = 5000

MaxHTTPMsgSize = 2097152 # kiB == 2GiB

SOAP_MONITOR_WAIT_INTERVAL = 2500 # ms

4.2.7 siqService.cfgLog (/home/olsc/v3server/bin)

[Common]

LogLevel=INFO,FATAL,ERROR,WARN,HINT

Format=DateTime,Thread,LogModule,FileName,Line,LogLevel,LogMsg

[Logger]

File=log/siqService.log

Permission=640

## do not use logrotate.d configuration and

## the settings found below at the same time

#BackUp=3

#Overwrite

#MaxFileSize=100m

##

[Ignore]

siqeCardAPI_svr.ols

siqRNG.ols

The configuration file shown above can be utilized immediately. You may use this as basic

configuration and alter it to meet your needs.

4.2.8 siqTSP.cfg (/home/olsc/v3server/bin)

[HTTPS D-Trust]

URL="https://time.d-trust.net"

TrustManagerClass="com.openlimit.tsp.trust.TrustAllManager" #

TrustAllManager

#TrustManagerClass="com.openlimit.tsp.trust.OLTrustManager" #

OLTrustManager


26

NoRevocationCheck=false # optional parameter for

OLTrustManager


27

5 Configuration

In the following chapter the configuration options for the OpenLimit V3 Server are described.

Please note that in case of misconfiguration the application may not work properly anymore.

5.1 bootsvr.cfg

In case you want to edit bootsrv.cfg, please go to

/home/olsc/v3server/bin/bootsrv.cfg . This configuration file includes the section

[JavaOptions] that can be configured. Applied and common Java options are described in

the following chapters.

5.1.1 Specify the Available Java Heap Memory (-Xmx)

The amount of available memory for Java can be specified. To do so, please adapt the option –

Xmx768m. It is entered in bytes and has to be a multiple of 1024.

The default value is 768m and should not be any lower. The m stands for megabyte. This means

if you just change the numerical value a multiple of 1024 bytes is already guaranteed and you

can enter any value (higher than 768) you like. Of course this value must not exceed the

physically available RAM of your system.

The preconfigured value is considered sufficient for the software even at high workload and

must normally not be increased. It is absolutely not recommended that the value fall below the

preset value due to the fact that negative side effects, for instance software crash because of

lack of memory, cannot then be ruled out.

5.1.2 Protection of Java (-Xrs)

The option -Xrs protects the ongoing Java distribution to the extent that no thread dump

(snapshot of the status of all Java threads) can be created.

In addition, less signals of the operating system are analyzed, which leads to a higher

compatibility with UNIX systems (also therefore RedHat or SLES).

This option must not be removed or modified!

5.1.3 Available Memory for Java Threads (-XX)

The option –XX is a Java option to set the memory size for each running thread of the JVM

(Java Virtual Machine) used. If the selected size is too small it may cause a crash of the Java

distribution.



28

5.1.4 File Encoding to Be Used (-Dfile.encoding)

The option –Dfile.encoding is a Java option to set the file encoding to be used.


5.1.5 Available Memory for Java Threads (-Djava.awt.headless)

The option –Djava.awt.headless specifies if the application should run “traditionally” or

just “headless“ (without graphical user interface). Due to the fact that it is a server application,

the value should be kept at true.


5.1.6 Proxy Configuration (-Dhttp)

The OpenLimit V3 Server can retrieve or download data from the Internet. This includes for

example:

Certificate revocation lists (CRLs)

Online validity information (OCSP responses)

Timestamps

If HTTP(S) communication within the local infrastructure is transmitted via a proxy, the HTTP(S)

proxy data needs to be processed by the OpenLimit V3 Server. The proxy settings are added as

options to the OpenLimit V3 Server Java runtime environment.

For an overview of Java options for the HTTP(S) proxy, please see the following table:

Java HTTP(S) proxy option Example

-Dhttp.proxyHost=<ProxyHostURL> -Dhttp.proxyHost=proxy.bsp.de

-Dhttp.proxyPort=<ProxyPortNumber> -Dhttp.proxyPort=3128

-Dhttps.proxyHost=<ProxyHostURL> -Dhttps.proxyHost=proxy.bsp.de

-Dhttps.proxyPort=<ProxyPortNummer> -Dhttps.proxyPort=3129

-Dhttp.proxyUser=<User> -Dhttp.proxyUser=JoeBloggs

-Dhttp.proxyPassword=<UserPassword> -Dhttp.proxyPassword=secret

Table 1: Example for Java HTTP(S) proxy options

Please note that you may use different proxy servers for HTTP and HTTPS communication. However,

for authentication the same authentication settings (from Dhttp.proxyUser and

Dhttp.proxyPassword) will be used.


29

The proxy settings in the bootsrv.cfg are commented out by default and can easily be

commented in and adapted depending on requirements.

5.1.7 Further Java Options

Please note that in case of modifications of the settings described in the section

[JavaOptions], Java’s own mechanisms for JVM configuration have to be used. Please

inform yourself about further possible settings and correct application with the help of Java

documentation.

For a documentation concerning the use of Java tools (java (Runtime), javac (Compiler), …) please

see: http://download.oracle.com/javase/6/docs/technotes/tools/index.html

For information concerning the use of Java options, please see:

http://download.oracle.com/javase/6/docs/technotes/tools/windows/java.html

5.2 siqDiag.cfg

The diagnosis functionality enables you to gather and save miscellaneous key figures during

operation of the software. For this purpose, the module siqDiag.ols and the corresponding

configuration file siqDiag.cfg are available.

If you wish to edit the siqDiag.cfg, you can find it under

/home/olsc/v3server/bin/siqDiag.cfg .

Please be aware that the diagnosis functionality is activated in the configuration file

bootsrv.cfg (see 5.1 bootsvr.cfg) by the following entry:

[Kernel]

Library = siqSEMk_Srv_LE.ols

LogModule = siqLogger.ols

DiagModule = siqDiag.ols

This entry must not be modified or removed!

5.2.1 Enabling the Diagnosis Functionality

In order to enable the diagnosis functionality you will have to apply the following settings in

the section [Diagnosis] of the siqDiag.cfg file.

In order to disable the diagnosis functionality, just set the value of Interval to 0 (see

Determining the Diagnostic Interval (Interval)).

Determining the Directory for the Diagnostic Output Files (DataDir)

The entry DataDir determines the directory the diagnostic output files will be saved to. The

specified path may be relative to the directory /home/olsc/v3server/bin or absolute,

http://download.oracle.com/javase/6/docs/technotes/tools/index.html

http://download.oracle.com/javase/6/docs/technotes/tools/windows/java.html


30

but it has to be existent and writable. With every diagnostic cycle the respective diagnostic

output files will be overwritten in the configured DataDir directory. Other diagnostic output

files found in the stated directory and which begin with another FileNameTemplate will be

left untouched. The default value is diag.

DataDir = diag

Determining the Prefix for Diagnostic Output Files (FileNameTemplate)

The entry FileNameTemplate indicates the prefix that is used to save the diagnostic

output files. Indication of the prefix is optional. The default value is dgInfo_.

FileNameTemplate = dgInfo_

Please note that existing diagnostic output files with the same prefix will be overwritten during a

new diagnostic cycle! It may be necessary therefore to change the prefix.

The output files’ names are formed as follows: prefix+module name

This means by default the naming will be e.g.: dgInfo_jobsInfo.log

The diagnostic output files for java network times are an exception to this rule. Their module

name is determined by their respective java-module name (OCSP, CRL, TSP):

dgInfo_netOCSP

dgInfo_netCRL

dgInfo_netTSP

Determining the Diagnostic Interval (Interval)

The value specified for Interval determines the timespan (in seconds) between diagnostic

cycles. The shortest possible interval (which means, the highest frequency) is 5 (seconds) while

the longest interval allowed is 86400 (seconds, which means once a day). A value outside this

time range will be set to the minimum or the maximum (except for 0). If the specified value is

0, the diagnose functionality is disabled. The default value is 300.

Interval = 300

Determining the Start Interval (StartInterval)

The value specified for StartInterval determines the number of seconds elapsing before

the first diagnostic information is queried and the corresponding diagnostic output files are

created. The shortest possible delay that may be specified is 30 (seconds) while the longest

delay allowed is 86400 (seconds, which means one day). A value outside this span will be set

to the minimum or the maximum (except for 0). If the specified value is 0, the default value will

be used. The default value is 60.

StartInterval = 60


31

Determine Permissions for Diagnostic Output Files (Permission)

The option Permission allows you to determine the file permissions the diagnostic output

files are created with. This parameter is optional. If no value is determined the permissions of

the user (that runs the software) are used. If group permissions are determined they will be

applied to the folder (e.g. 664 for files will apply 775 for the appointed folder). The default

value is 640.

Permission = 640

5.2.2 Determining the Diagnostic Scope

In order to ignore specific information for the diagnosis feature, you may specify the following

information in the section [Ignore] in the file siqDiag.cfg. To ignore an information

source, it must be uncommented in the section [Ignore], i.e. the hash (#) for the entry must

be removed.

Please note that a filter entry has to be made without the suffix “.log”.

netOCSP

If this entry is active, it provides information on the network times from Java regarding OCSP

requests, including information on the times from the past 24 hours (at most) from the time of

the first query:

URL

Number of successful requests

Number of unsuccessful requests

The minimum, maximum and average duration of each request are indicated too.

netCRL

If this entry is active, it provides information on the network times from Java regarding CRL


the first query:

URL




netTSP

If this entry is active, it provides information on the network times from Java regarding TSP


the first query:

URL



32



jobsInfo

If this entry is active, it provides statistics on executed jobs. At present, the following

information is released:

Job times

Job count

The minimum, maximum and average duration of job types are indicated too.

procInfo

If this entry is active, it provides information on the current status of the internal thread

management.

moduleList

If this entry is active, it provides a list of loaded modules with respective module information,

where available.

systemInfo

If this entry is active, it provides general system information:

Uptime

Internal memory

Hard drive space

Operating system information

Beyond these diagnoses further information will be indicated on stderr in the event of a

programmed termination (e.g. because of a detection of internal resource bottlenecks or

inconsistent statuses). This may help find the cause of a termination.

5.2.3 Rotation of Diagnostic Log Files

The log rotation of diagnostic output files is described in chapter 5.8.5 Log rotation.

5.3 siqSEMKSrv_svr.cfg

5.3.1 Settings That Must Not Be Modified

Section [Kernel]

This whole section is used for basic configuration of the OpenLimit V3 Server.

Option Library

The option specifies the module for use of the WebService (SOAP) interface.


33

Option EscapeString_0A

This option determines the string which is sent for the character 0x0A.

Option ENABLED

The option specifies if the WebService interface is used.

Option SOAP_MONITOR_WAIT_INTERVAL

This option is used for WebService internal mechanisms.

Section [Archives]

This section describes the JAR archives used

Option PDFSizeLimit

This option specifies the maximum size of a PDF file that is to be processed.

5.3.2 Determining the VerificationModel

With the VerificationModel option in the [Verification] section, you can indicate

the validity model to be used when verifying signatures:

HYBRID Use of the hybrid model (modified shell model)

CHAIN Use of the chain model

DEFAULT Auto-configuration of the validity model used based on the type5 of

certificate used

For more information on this, please see Validity Model for Signature Verification

5.3.3 Changing the Order of the Revocation Check

The revocation check order (RevocationCheck) can be modified. According to the OpenLimit V3

Server default settings in delivery state, at first an OCSP response is requested. If this is not

possible, it is verified against certificate revocation lists .

To change these settings, please edit the file siqSEMKSrv_svr.cfg. This configuration file

includes the section [Verification]. Please adapt the value of the entry RevocationCheck

there.

#Settings required for signature verification

[Verification]

RevocationCheck=AUTO

The following values can be entered:

RevocationCheck value Description

AUTO At first an OCSP request is triggered. If this is not possible,

5 In accordance with the German Signature Act, qualified certificates are defined using the TrustBase provided by

OpenLimit and verified based on the chain model. All other signatures are verified based on the hybrid model.


34

it is verified against certificate revocation lists afterwards.

OCSP Here, an OCSP request is triggered.

CRL Here, verification is performed against a certificate revocation list (CRL).

OFFLINE Online revocation check is not performed.

Table 2: Values for the parameter RevocationCheck

5.3.4 Determining the Archiving Period for Retaining Revocation Information

The option ArchiveCutoffPeriod is the number of years the revocation information

provides information about revoked certificates. This setting can be indicated for the server

globally via the configuration file. If an OCSP response contains an ArchiveCutoff

extension, this takes priority over the configuration setting. The default value is 0 years. It

must be ensured that the entries for the archiving period correspond to the actual data of the

issuer of the revocation information. A change has to be justified. The configured values can be

found in the XML verification protocol.

The different entries for ArchiveCutoffPeriod represent the different types of digital

signatures (accredited, qualified, advanced). The default values are “30”, “5”, “0”.

#Settings for ArchiveCutoffPeriod in (years)

ArchiveCutoffPeriod_accredited = 30

ArchiveCutoffPeriod_qualified = 5

ArchiveCutoffPeriod_advanced = 0

5.3.5 Certificate Key Usability Settings (KeyUsage)

With the configuration setting AcceptNullKeyUsage it can be indicated whether or not all

key usages are allowed with a certificate which does not contain any keyUsage extension.

The default setting is set restrictively to false and corresponds to the specification of the

common PKI 2.0 standard. If the configuration setting is changed to true, the RFC 3280

specification is adopted and, in the event that the ‘key usage’ extension is absent, all key

usages will be allowed.

5.3.6 Setting the Maximum File Size for Signature Information

The option InputFileSize sets the maximum size for a file containing signature

information. This may be a detached or attached CMS signature, a timestamp, an evidence

record or an XML signature. Binary data in a file not containing any signature information are


35

not captured by this value6. Signature data must be loaded into the main memory and are

structurally processed. For this reason, the memory requirement for this kind of data is high.

Signature data are usually significantly smaller than the default value of 50 MiB. The related

configuration parameter PDFSizeLimit may not exceed the value of 50 MiB and should not

be changed.7

5.3.7 Keep the Socket for the WebService Alive (KeepAlive)

The KeepAlive option offers the possibility of reusing a socket even if communication via

this socket has been stopped before, provided the client and the server are using this function

and the socket has not been explicitly closed. To support this function, please set the value for

KeepAlive to “yes”:

KeepAlive = “yes”

The value “no” means that a new socket will be opened for each new communication.

5.3.8 Collecting Requests That Are Currently Not Processable (BackLog)

The option BackLog allows one to specify the size of the queue that the requests are held in,

to be processed one after another. The default value is 100.

BackLog = 100

5.3.9 Retry Start-Up (RetryCreate, RetryCreateWait)

It is possible that the OpenLimit V3 Server cannot be started due to the fact that the

SOAPPort used is not available. Therefore the number of retries to start the OpenLimit V3

Server can be specified via option RetryCreate. For the number of retries a value between

1 and 10 (default) can be entered.

RetryCreate = 10

In this context the option RetryCreateWait can be modified as well. This defines the time

in milliseconds between the retries. The release of the SOAP port can vary in length depending

on the system and the environment. The default value is 5000, i.e. five seconds.

RetryCreateWait = 5000

6 The detached signature data or the hash data in a file can, depending on the file system, be of any size (64bit). The

data are not loaded into the main memory. Only data in files containing the structure information of a signature,

timestamp or evidence record are captured by InputFileSizeLimit.

7 PDFSizeLimit relates both to the file size as well as to the size of the committed buffer.


36

5.3.10 Maximum HTTP Message Size (MaxHTTPMsgSize)

The option MaxHTTPMsgSize allows the specification of the maximum size of the entire http

message that can be used for communication with the WebService. The default value (in kB) is set at

2 GB.

MaxHTTPMsgSize = 2097152

5.3.11 Binding the V3 Server to a Network Address (SOAPHost, SOAPPort)

In case the OpenLimit V3 Server should be bound to a specific network address, the SOAPHost

of the OpenLimit V3 Server needs to be configured. To do so, please edit the entry SOAPHost

in the section [ECARD]. If you change the SOAPPort, it must be adapted in the connected

application (SDK Client) as well. Even operating two OpenLimit V3 Servers on one system would

be possible with the configuration of the parameter SoapHost – provided that it matches

your system performance. Please note the configuration of the connected application.

#Settings required to load the trustbase

[ECARD]

Library = siqeCardAPI_svr.ols

ENABLED = true

KeepAlive = “yes”

SOAPHost = 0.0.0.0

SOAPPort = 18080

SOAPHost value Description

127.0.0.1 Local configuration to run the OpenLimit V3 Server in an isolated environment.

Specified IP address

(e.g. 192.168.0.2) Network address to connect the OpenLimit V3 Server.

0.0.0.0 The OpenLimit V3 Server connects with all available network addresses (network interface cards).

Table 3 Possible SOAPHost values

5.3.12 Using External OCSP Responses during a Signature Verification

The OpenLimit V3 Server is able to verify a signature using already existing OCSP information.

In this case the OCSP information is either passed on as a parameter upon invocation of the

signature verification or it is already part of the CMS container that is to be verified. This OCSP

information has to match the signature certificate to be verified and it has to contain


37

information about the validity of this certificate. Furthermore, the OCSP information must not

be obtained before the moment of signature creation.

The configuration file siqSEMkSrv_svr.cfg contains two parameters

(ErrorOnUnusedEmbeddedOCSP and UseEmbeddedOCSPIfOld) in the section

[Verification], which affect the product’s behavior:

The parameter ErrorOnUnusedEmbeddedOCSP (without further details)

may be found in the section [Verification]. If the OCSP information does

not match the signature certificate, the OpenLimit V3 Server reacts with the

following error message:

SIQ_E_UNUSEDPARAMETER_OCSP_EMBEDDED.

If the parameter ErrorOnUnusedEmbeddedOCSP does not exist, this error

message will not appear.

The parameter UseEmbeddedOCSPIfOld (without further details) may

be found in the section [Verification]8. This parameter works as follows:

existing OCSP information is used. Use this parameter if you want to force the use

of existing OCSP information. Please note that the use of outdated OCSP

information cannot lead to a positive verification result, as this parameter will

prevent the regeneration of existing OCSP information.

5.4 siqPolicies.cfg

In the configuration file siqPolicies.cfg policies can be defined, that are applied in

different fields of OpenLimit V3 Server operation.

5.4.1 Options that must not be modified

Cache policies:

The Policy entries in the sections

[RevocationValues_CachingInterval] and

[CertificateChain_CachingInterval] are relevant for internal

processing.

CAdES policies:

The Policy entries in the sections [CADES_Format] and

[SignerInfo_CompleteReferences] are relevant for internal

processing.

Policies for signature certificates:

The Policy entry in the section [SignerInfo_SigningCertificate] is

relevant for signature certificate verification.

8 Product behavior with regard to revocation lists will not be affected by this parameter.


38

5.4.2 Policies for OCSP Response Retrieval

For OCSP response retrieval, three options can be set.

The timeout when retrieving an OCSP message can be changed in the section

[Timeout_OCSP] via the entry Policy. The value is specified in milliseconds and is

“9000” by default.

Policy=“9000”

The number of attempts to obtain an OCSP response can be specified in the section

[FailedOCSPRequestAttempts] via the entry Policy. The default value is “3”.

Policy=“3”

The time between unsuccessful attempts to obtain an OCSP response can be changed in the

section [FailedOCSPRequestSleepInterval] via the entry Policy. The value is

specified in milliseconds and is “50” by default.

Policy=“50”

The time that a valid OCSP response remains in the cache can be changed in the section

[Timeout_OCSP_Cache] via the entry Policy. The value is specified in milliseconds and

is “900000” (15 minutes) by default.

Policy=“900000”

If a retrieved OCSP response contains a timestamp that is older than the time of signature

creation, it will be rejected as being invalid. Via the Policy entry in the

[Timeout_OCSP_Retry], one can indicate for how long it should be reattempted to obtain

a valid OCSP response.

This error situation occurs if the time settings are incorrect: Either the time of the OCSP

responder is in the past or the signature creation time9 is in the future. The value is specified in

milliseconds and is “4000” (four seconds) by default. The maximum value is “60000” (one

minute).

Policy=“4000”

5.4.3 Certificate Revocation List (CRL) Policies

Three options can be set for certificate revocation list retrieval.

The timeout for obtaining certificate revocation lists can be changed in the section

[Timeout_CRL] via the entry Policy. The value is specified in milliseconds and is

“60000” by default.

9 The signature creation time can originate, for example, in an OCSP response of another provider or in the signature

creation time of the document itself.


39

Policy=“60000”

The number of attempts at obtaining a certificate revocation list can be changed in the section

[FailedCRLRequestAttempts] via the entry Policy. The value is “3” by default.

Policy=“3”

The time between unsuccessful attempts at obtaining a certificate revocation list can be

changed in the section [FailedCRLRequestSleepInterval] via the entry Policy.

The value is specified in milliseconds and is “50” by default.

Policy=“50”

5.4.4 Timestamp Policies

Three options can be set for timestamp retrieval.

The timeout for obtaining timestamps can be changed in the section [Timeout_TSP] via

the entry Policy. The value is specified in milliseconds and is “30000” by default.

Policy=“30000”

The number of attempts at obtaining a timestamp can be changed in the section

[FailedTSPRequestAttempts] via the entry Policy. The value is “3” by default.

Policy=“3”

The time between unsuccessful attempts at obtaining a timestamp can be changed in the

section [FailedTSPRequestSleepInterval] via the entry Policy. The value is

specified in milliseconds and is “50” by default.

Policy=“50”

5.5 siqCRL.cfg

In the configuration file siqCRL.cfg the revocation list distribution point (CDP) for X.509

certificates can be determined. If an alternative CDP is configured, the original CDP within the

certificate is entirely ignored.

If a revocation list (CRL) cannot be downloaded from the alternative CDP, the V3 Server will

attempt to load a suitable revocation list from its certificate manager. If a certificate merely

contains information on an OCSP responder, a CDP can still be conf igured.

The matching of certificates to a CDP is realized via the distinguished names of the certificate

issuer (issuer DN).

The entry in the siqCRL.cfg consists of two lines and has to look as follows:

[<Issuer DN (complete or parts of it)>]

URL=<URL of the alternative CDP>


40

The entries in the siqCRL.cfg will be compared to the character string of the Issuer DN from

each certificate. If an issuer DN from the configuration file finds itself in the issuer DN of the

certificate, the certificate will be allocated the corresponding CDP.

Example:

The issuer DN [O=Global Company] is present entirely in certificate no. 1 but only

partially in certificate no. 2. The CDP will therefore only be assigned to certificate no. 1.

Certificate no. 1: CN=CA Global 1, O=Global Company GmbH, C=DE

Certificate no. 2: CN=CA Global 1, O=Global Holding AG, C=DE

Entries in the siqCRL.cfg may be deactivated (commented out) by adding a hash (#) in

front of the line.

5.5.1 Formatting of Issuer DN

Case-sensitive

The elements (attributes) of the issuer DN are ordered from specific to general

attribute types

Attribute type and value are separated by an equal sign (=) without blank space

(e.g. CN=CA Global 1)

Attributes are separated by commas with a blank space after (e.g. O=Global

Holding AG, C=DE)

If special characters (= + ; # ,) are present within the attribute’s value, the

value is framed by quotation marks (e.g. CN=“CA Global #1“)

In order to use international characters in the configured issuer DN, the

siqCRL.cfg file has to be saved with UTF-8 encoding without Byte Order Marks

(BOM).

Example:

[CN=“CA Global #1“, O=Global Company GmbH, C=DE]

5.5.2 Formatting of a CDP URL

The CDP URL is stated without quotation marks

Blank spaces or character representation in URL encoding are allowed in the URL

The typical application logs (HTTP and LDAP) may be used for the CDP URL

Examples:

URL=http://crl.global-company-gmbh.de/crl%201.crl

URL=http://crl.global-company-gmbh.de/crl 1.crl

URL=ldap://directory.global-company-gmbh.de/CN=CA Global

1,O=Global Holding AG,C=DE?crl

URL=ldap://directory.global-company-

gmbh.de/CN=CA%20Global%201,O=Global%20Holding%20AG,C=DE?crl


41

5.5.3 Determining the Issuer DN of a Certificate

The issuer DN of a certificate can be viewed by using the option –getCertInfo –

issuerDN with the V3 Server AdminTool (see also 6 Configuration via the AdminTool).

The Issuer DN can then be copied to the siqCRL.cfg without further editing.

5.6 OCSP

OCSP requests are obtained via the address included in the certificate. For the required proxy

settings, please see chapter 5.1.6 Proxy Configuration or the Java documentation for the

corresponding connection protocol.

5.6.1 siqOCSP.cfg

A Pattern (here: “Example Issuer”) representing a substring of the Issuer Common

Name in the certificate can be specified under a freely definable (but unique) section headline

(here [Example_CA]). The section is used via the pattern. The address entered under URL

describes the full URL which should be taken as a replacement or as new for the CA.

DigestAlgName describes the hash algorithm which should be used for the message imprint

(if omitted: the ‘default’ algorithm can be found under [Common]). Possible hash algorithm

names are (SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, RIPEMD-160).

Example:

[Example_CA]

Pattern="Example Issuer"

URL="http://ocsp.pca.example.de/OCSP-Server/OCSP"

DigestAlgName=SHA-1

The entry in siqOCSP.cfg has priority over the value included in the certificate due to the

fact that modifications to the address (including spelling mistakes) can be tracked.

5.6.2 OCSP Cache

The OCSP cache is a mechanism to improve the processing speed of verifications of the online

validity status of certificates (OCSP responses). To reach this aim, recently requested OCSP

responses are held available10. This way the number of further OCSP requests for certificates

that already have an OCSP response are significantly reduced.

This mechanism is implemented in a way that if an OCSP response is requested , it is verified if a

suitable OCSP response for this certificate is already present in the OCSP cache. A usable OCSP

10 If the OCSP information contains the status code “UNKNOWN”, the configuration parameter

Timeout_OCSP_Cache determines the time the OCSP information is kept in the OCSP cache.


42

response is present if the signature for which the certificate to be evaluated was used is older

than the existing OCSP response for that certificate. If this is not the case, a new request shall

be made and the response stored in the OCSP cache.

If a suitable OCSP response is available for the certificate, it is used for certificate evaluation.

The following case describes a suitable OCSP response:

The signature for which the certificate to be evaluated was used is older than the

available OCSP response for that certificate.

If there is no suitable OCSP response, a new OCSP response is requested and used for evaluation.

5.7 Retrieval of Timestamps

5.7.1 General

The OpenLimit V3 Server retrieves timestamps from timestamp provider (TSP) through the TSP

Manager along with the TSP modules. Every single one of the TSP modules is responsible for

processing one URL of a TSP. If a URL is handed over to the TSP manager that does not match a

TSP module this URL will be handed over to the generic TSP module (GenericTSPModule)

This module allows HTTP connections as well as HTTPS connections - alternatively with the use

of proxy servers, if the system properties http.proxyUser and http.proxyPassword

are specified.

Every supported TSP is characterized by the following parameters:

Parameter Description

URL URL, for which the following settings apply.

NoRevocationCheck

[true/false]

Only for OLTrustManager. If this is true, no revocation

information will be checked. Generally it is not needed to validate

the revocation information of SSL connections for timestamp

requests, since the timestamp itself can be validated. So the

recommended value is true. Only if the highest safety

precautions, even for SSL connections, have to be met, should the

value be set to false.

TrustManagerClass Fully qualified name of the class, which shall validate the server

certificates.

Table 4: Parameters for TSP Modules


43

5.7.2 The TSP Module GenericTSPModule

The TSP module GenericTSPModule is able to establish an HTTP connection as well as an

HTTPS connection. The specific settings for particular timestamp providers are handed to the

GenericTSPModule through the settings determined in the configuration file

siqTSP.cfg.

Based on the URL transferred, the GenericTSPModule decides whether to establish an

HTTP or HTTPS connection. Default values will become active if no alternative values have been

provided via the configuration properties.

5.7.3 siqTSP.cfg

The default content of the configuration file siqTSP.cfg for the GenericTSPModule:

##############################################

### OpenLimit SignCubes 2003 - 2012 (C) ###

### TSP responder configuration file ###

##############################################

### SSL/TSL TSP responders with Trust Manager settings ###

## Available Trust Managers ##

# TrustAllManager -> SSL server certificate not verified

# OLTrustManager -> V3 Server Certificate Manager

# used (only certificates in V3 Server are trusted)

[HTTPS D-Trust]

URL="https://time.d-trust.net"

# TrustAllManager

TrustManagerClass="com.openlimit.tsp.trust.TrustAllManager"

# OLTrustManager

#TrustManagerClass="com.openlimit.tsp.trust.OLTrustManager"

NoRevocationCheck=false # optional parameter for

# OLTrustManager

5.7.4 The Trustmanager in Detail

The Trustmanager OLTrustManager uses the certificate store of the OpenLimit V3 Server.

Organizing of the OpenLimit V3 Server certificates is done through the AdminTool.


44

The Trustmanager TrustAllManager allows every connection, without any check being

performed. The validity of retrieved timestamps is not affected by this setting, since every

timestamp is signed individually and can be validated.

5.8 Logging

Logging can be activated per module or executable file of the OpenLimit V3 Server. The

following logging features can be specified:

Log level

Formatting of the log entries

Logging output destination (console or file)

Modules to be excluded from logging

When you are logging and want to record all processes that are executed during OpenLimit V3

Server operation, please activate logging at the top level. The top level is the executable file

siqService, which starts the OpenLimit V3 Server.

Otherwise the amount of logging can be specifically limited if logging is only activated for the

appropriate modules.

If logging is activated as described in the following sections but cannot be executed due to

misconfiguration (e.g. missing write permissions) the software writes a message in SYSLOG and is

automatically shut down. When configuring the logging, please ensure that only correct parameters

are used and that the application has the necessary rights.

In the event that no further information can be written in the indicated log file, messages on this

status are stored in the SYSLOG. The software remains operative but the actual log message is

rejected.

5.8.1 Activate Logging

According to the included configuration file, logging is activated by default (see 4.2.7

siqService.cfgLog (/home/olsc/v3server/bin)).

Logging can be customized by creating a separate configuration file for the desired module or

executable file. Please ensure that the file name includes the program name of the module or

executable file to be logged. The configuration file and the module or executable file to be

logged must be in the same directory. Due to the fact that the configuration file name

determines the desired module to be logged, the file name has to meet the set naming

convention.

The configuration file name consists of the complete name of the module or executable file to

be logged followed by the fixed designation “.cfgLog“. Please see the following table for

examples:


45

Name of the File to be Logged Name of the Configuration File

Executable File siqService siqService.cfgLog

Table 5: Configuration file name

5.8.2 Order of Processing Log Configuration Files

At first, possible configuration files are read out at module level. If a cfgLog file is found for

a module, messages are logged for this module on the basis of this configuration. In this case

the search for a logging configuration at the executable file level does not proceed. Therefore

messages about this module are not displayed in the log of the executable parent file.

In case a cfgLog file cannot be found for a module, a configuration in the executable parent

file will be sought. If such a configuration file exists, messages of the module are collected at

the executable file level.

5.8.3 General Processing Instructions for Configuration Files

Please follow the important general processing instructions concerning the configuration files

for logging:

Please note that all entries are case-sensitive.

Right: LogLevel=ALL

Wrong: loglevel=all

Except for file paths (written in quotation marks), no spaces are allowed between

configuration values.

Right: LogLevel=INFO,WARN

Wrong: LogLevel=INFO, WARN

5.8.4 Details About the Individual Configuration Sections

Section: [Common]

The section [Common] specifies the formatting of log entries and the included data.

ATTENTION: It is absolutely necessary to configure this section. Otherwise no log data is

generated.

Attribute: LogLevel

The corresponding messages displayed in the log file have to be listed separated

by commas. The following log levels can be set (in order of priority):


46

LogLevel Parameters Description

ALL Includes all further log levels

FATAL Displays fatal errors

ERROR Displays errors

WARN Displays warnings (the process keeps running)

DEBUG Displays debug Information (including internal processes)

INFO Displays information

TRACE Displays common trace data (e.g. access to and leaving a function )

HINT Information on content errors (no need for action for administrators)

Table 6: (Logging) Possible LogLevel parameters

Note: The log level of the OpenLimit V3 Server can be changed during operation with the help of

the Admin Tool. See section 6.2.7 for more information.

Attribute: Format

The format specifies the structure of a log line. Data to be logged for each log line

is listed, separated by commas. The order of listed data stays the same for

logging. The following formats are possible:

Format parameters Examples for logging output

DateTime (19.02.2011 14:21:30.468)

Thread t.....464d Tmain (Linux-Thread ID and

internal V3 Server ID)

LogModule m[siqService]

FileName siqInitFini.hpp

Line 33:

LogLevel [DEBUG]

LogMsg Module logging initialized - pLogger

0x5552f0

Table 7: (Logging) Possible format parameters


47

Section: [Logger]

In the section [Logger] it is defined where log output is sent to or written. The attributes

Console and File can be used at the same time or as a single entry.

ATTENTION: It is absolutely necessary to configure this section. Otherwise no log data is generated.

Attribute: Console

By configuring the attribute Console, log entries can diverted to the standard

output (stdout) or standard error output (stderr). In RedHat / SLES, stdout

and stderr are displayed as pre-settings on the console.

Attribute: File

Via the attribute File the path to a log file is indicated. The file path is written

in quotation marks and therefore spaces within the file path are possible. Further

setting possibilities, e.g. maximum log file size, are configured in the separate

section [File].

Section: [File]

The access permission for the log file to be created can be edited by adding the option

Permission in the section [File].

e.g.: Permission=640

To ensure that a single log file does not use unlimited disk space, this section also specifies at

which time a log file is overwritten with a new one and if the old files are archived in the

process.

Please note: The following configuration options are deacitivated by default. Normally the

logrotation framework of the operating system is used (see Section 5.8.5 Log rotation).

Attribute: MaxFileSize

Specifies the maximum log file size before it is overwritten with a new one.

Supported units are megabyte (m) and kilobyte (k). MaxFileSize can be

configured separately or in combination with Overwrite and BackUp.

Attribute: Overwrite

With every reboot of the OpenLimit V3 Server the log file is newly created.

Overwrite can be entered separately or in combination with MaxFileSize and

BackUp.

Attribute: BackUp

If MaxFileSize and/or Overwrite are included in the configuration,

automatic archiving of old log files can be additionally specified via the attribute

BackUp. Optionally, the attribute BackUp in combination with a specified

number can be used to limit the number of back up files.

Please note: The BackUp, if indicated, is not only created with every reboot but also when the

specified maximum size is reached.

Files to be archived are renamed according to a certain pattern:


48

<Complete file name of the log file>_<Date: YYYYMMDD><Time: hhmmss>.log11

Log file Archived log file

siqService.log siqService.log_20100527120156.log

Table 8: Renaming log file as an archive file

Example:

[File]

Permission=640 # octal values only

#Possible values for file backend

#MaxFileSize=<size>m or <size>k # max file size in KiB or MiB

#Overwrite # overwrite log file on startup

#BackUp # backup log file with

#

#Used values

MaxFileSize=100m

Overwrite

BackUp=5

Section: [Ignore]

All listed modules are excluded from logging. In this section the individual modules are entered

one per line with their full file name.

Example:

[Ignore]

#Special section to exclude some modules from being logged

#List excluded modules with full file name one per line

siqSvcBootLoader.ols

siqSEMk_Srv.ols

5.8.5 Log rotation

The log rotation of the V3 Server can be configured in two ways: to a reduced extent using the

on-board tools of the V3 Server or using the logrotate framework of the operating system.

After installation of the V3 Server the logrotate framework of the operating system is set as

default. The configuration can be found in /etc/logrotate.d/olsc_v3server. General

11 Y = year, M = month, D = day; h = hour, m = minute, s = second


49

information about the operating system’s logrotate framework can be retrieved through the

command man logrotate. This framework allows the administrator to adjust the

configuration to his needs in a wide variety of ways.

The V3 Server’s own logrotate settings are deactivated by default. A hybrid configuration of

both log rotation mechanisms (operating systems and V3 Server) together is not supported.

The V3 Server’s own logrotate settings can be found commented out under

/home/olsc/v3server/bin/siqService.cfgLog. For further information about

this configuration file please see Section 5.8.4 Details About the Individual Configuration

Sections in the Section: [File].

This preconfigured logrotate configuration contains two sections. One section configures the

rotation of regular log files and the other section regulates the rotation of files with diagnostic

information of the V3 Server.


50

Preconfigured Settings of the logrotate.d Configuration

An explanation of the most important options in the logrotate.d configuration

(/etc/logrotate.d/olsc_v3server) is given below:

Logrotate Parameters Description

#daily

In the logrotate framework, the timings are daily, weekly and

monthly.

By default, no timing is preset (commented out ‘daily’), i.e. the timing

from the cron job setting of the logrotate daemon is adopted. The

cron job timing is usually set to ‘daily’ on the systems. Please be

aware that in the case of very heavy data traffic, a very large number

of log messages will be generated in the event of an error. For this

reason, please adapt the timing of the cron jobs accordingly.

size 200M A logrotate is only performed if the log file reaches a file size of 200

MB.

rotate 3 The amount of log rotations before a log file is deleted irreversibly.

create 640 olsc

olsc The file permissions of rotated log files are retained.

lastaction

The script commands between lastaction and endscript

will be performed after a successful log rotation.

In this case the script commands clean up the files that the V3 Server

redirects the standard error messages to, which are placed in

/home/olsc/v3server/bin/log. These files can be

identified by the prefix stderr_.12

Table 9: (Logging) Possible logrotate parameters

12 Empty files (except the current one) are deleted by the lastaction script commands. Files with standard error

messages are marked with TOBECHECKED_ in the file name and retained for examination by the administrator.


51

6 Configuration via the AdminTool

The AdminTool is provided for certificate administration and its functions are described in the

following. The AdminTool can be found here:

~olsc/v3server/bin/ext/OLSC_SOL_AdminTool.jar. If you are not using the

AdminTool from root, please be sure to check Section 2.1 Installation of the OpenLimit V3

Server.

The AdminTool offers several functions (6.2 AdminTool Functions):

Certificate import

Certificate deletion

Manual storage of imported certificates

Display of certificate information

Display of quality information

These functions can be combined with options (see 6.3 AdminTool Options).

Please be aware that all certificates imported with the AdminTool are retained even after

uninstallation or re-installation of the OpenLimit V3 Server. In order to reset to the factory settings

the directory “.olsc” has to be deleted.

6.1 Important Information

Using the AdminTool requires at least a Java environment version 1.6.

Please note that the AdminTool should always only be started once, so that administrative tasks are

not carried out in parallel.

6.2 AdminTool Functions

6.2.1 Importing a Certificate

Below is an example of an invocation:

java -jar OLSC_SOL_AdminTool.jar -importCertV3 –cert <fileName>

–trustLevel <trustLevel>

Only imported certificates can be used. In case the CA or root certificate for the appropriate

signature certificate is missing, the certificate chain cannot be created and signature

verification will not be possible (please see 7.2.1 SIQ_E_VRF_INCOMPLETE (e1002000)). The

certificate is read from the hard disk during import and cached in the V3 Server RAM. If the

command -saveTrustBase is not executed afterwards, certificates are not stored before

the V3 Server is terminated. The certificate to be imported must be encoded in the format ASN.1


52

DER. To assign a security status during import, please use the option –trustLevel (see

example above). For further information concerning the option parameters, please see 6.3.2

Option -trustlevel.

6.2.2 Deleting a Certificate


java -jar OLSC_SOL_AdminTool.jar -removeCertV3 -cert <fileName>

Alternatively, the certificate’s SearchKey13 can also be specified if you wish to delete a

certificate:

java -jar OLSC_SOL_AdminTool.jar -removeCertV3 –skey <skey>

The command -removeCertV3 transmits a request to the OpenLimit V3 Server to internally

delete the certificate named <fileName> or <skey>.

At first, the trust level is set at NEUTRAL for the running OpenLimit V3 Server instance. The

certificate is deleted from the main storage only after the OpenLimit V3 Server is closed. Persistence

is induced via -saveTrustBase or regular shutdown of the OpenLimit V3 Server. During batch

operation an unlimited number of certificates can be deleted and then the deletion permanently

stored in the database via -saveTrustBase.

6.2.3 Manual Storage of Imported Certificates


java -jar OLSC_SOL_AdminTool.jar -saveTrustBase

Using this command all existing certificates in the RAM are permanently stored by the

OpenLimit V3 Server in an internal database and will be available again after restarting the

OpenLimit V3 Server. This allows manual storage independent of the automatic storage of the

database during shutdown of the OpenLimit V3 Server.

6.2.4 Getting Information About a Specific Certificate

Below are two examples of an invocation:

java -jar OLSC_SOL_AdminTool.jar -getCertInfo –cert <fileName>

13 The searchKey is contained within the XML output of the –listCertV3 invocation as a value of the

attribute val from CertMgrData/SearchKey.


53

or

java -jar OLSC_SOL_AdminTool.jar -getCertInfo –skey <skey>

This command displays all certificate parameters (see list below)14. Optionally, individual

certificate parameters may be displayed using the parameters shown in the table:


-version Version of the certificate

-subjectDN Subject DN of the certificate

-issuerDN Issuer DN of the certificate

-quality Quality of the certificate

-validuntil Date until the certificate is valid

-validfrom Date from when the certificate is valid

-serial Serial number of the certificate

-db Status of the certificate in the certificate database

Table 10: Parameters of the command -getCertInfo

6.2.5 Displaying Information About All Available OpenLimit V3 Server Certificates


java -jar OLSC_SOL_AdminTool.jar -listCertV3 –filename <fileName>

Using this command an XML data stream of the OpenLimit V3 Server is written in the file

<fileName>15. This file includes information about all certificates contained within the

OpenLimit V3 Server16.

14 If it is not already known, the indicated certificate is imported implicitly with the truststatus NEUTRAL.

15 If the file already exists it must first be deleted, since the command does not completely delete the already existing

data.


54

In order to reduce the number of certificates, e.g. certificates issued by a particular issuer,

additional parameters can be specified. Examples of additional parameters are shown below:

-issuerDN 'Trust, Inc.' -db CTL

These parameters deliver all certificates whose issuer name contains ‘Trust, Inc.’ and whose

status in the certificate database is CTL.

List of parameters for limiting the number of certificates:


-subjectDN

Indicates part of the name of the holder (subject),

which is being searched for. The search will be

performed in common name, organization and

organizational unit.

-subjectDNCountry Contains the country name component of the holder

(subject).

-issuerDN

Indicates part of the name of the issuer, which is

being searched for. The search will be performed in

common-name, organization and organizational-

unit.

-issuerDNCountry Contains the country name component of the issuer.

-db

Indicates the status of the certificate in the

database. The valid values are NONE, SYSTEM, CTL,

USER, TOUSER, FROMUSER_IMPORT,

FROMUSER_REMOVE17

-trustlevel Indicates the trust status which can accept the

values TRUSTED, NOT_TRUSTED and NEUTRAL.

16 In order to synchronize both the information that is persistently held and the information held in the main memory,

–saveTrustBase has to be invoked first.

17 The values indicate the status of a certificate in the database. CTL indicates root certificates trusted by the

manufacturer, SYSTEM indicates other certificates delivered by the manufacturer, NONE indicates a temporarily

imported certificate. The other status values designate certificates imported and saved by the user (USER) a nd those

whose status has not yet been saved (TOUSER, FROMUSER_IMPORT, FROMUSER_REMOVE).


55

-persistency Indicates the persistency status which can accept

the values PERSISTENT and TEMP.

-validOn

Indicates the validity of the certificate at a certain

point in time, format yyyy-MM-dd or yyyy/MM/dd, as

well as nYears or nMonths or nDays or TODAY (with

n representing a whole number).

-invalidOn

Indicates the invalidity of the certificate at a certain

point in time, format yyyy-MM-dd or yyyy/MM/dd, as

well as nYears or nMonths or nDays or TODAY (with

n representing a whole number).

In addition, there are the operators OR and AND, as well as brackets, with the help of which

complex expressions on the restriction of the certificate quantity can be shown. Example:

-validOn TODAY and ( -issuerDN AddTrust or -issuerDN NoTrust )

Arguments containing blank spaces must be included within inverted commas.

6.2.6 Displaying Quality Information About the Indicated Certificate


java -jar OLSC_SOL_AdminTool.jar -checkCertQuality –cert <fileName>

This command displays the quality of the certificate named <fileName>. The certificate used

must be encoded in the format ASN.1 DER.

Possible certificate qualities include:

Output Certificate Quality

advanced Advanced certificate

qualified Qualified certificate

accredited Accredited certificate

Table 11: Possible outputs of –checkCertQuality


56

6.2.7 Changing the Log Level of the OpenLimit V3 Servers

With this invocation, the set log level can be changed during operation of the OpenLimit V3

Server (the log level is explained in section 5.8).

Example:

java -jar OLSC_SOL_AdminTool.jar –setConfigV3 –confFile

siqService.cfgLog –confSection Common –confParam LogLevel –

confValue FATAL,ERROR,HINT

In this example, the log level is set to the value FATAL, ERROR, HINT. The parameters -

confFile, -confSection and –confParam must be used with the indicated parameters,

as shown in the example. The value for the parameter –confValue is variable and can

contain values from Table 6: (Logging) Possible LogLevel parameters

6.3 AdminTool Options

6.3.1 Options -h -? -help -–help

Each option displays a help text. This help text includes all available actions and the associated

compulsory parameters as well as all optional parameters. At the end of the help text sample

invocations for some important actions are listed.

For all invocations the optional parameters -kernelAddress and –kernelPort may be

used.

Otherwise the following default values are applied internally:

Parameters Default Values

-kernelAddress localhost

-kernelPort 18080

Table 12: Default values for optional parameters

6.3.2 Option -trustlevel

Using the option -trustlevel the AdminTool instructs that a security status be assigned to

the transmitted certificate. For this optional parameter the following values are permitted:


57

Parameters Common Use

TRUSTED or 0 Usually used for root certificates.

NOT_TRUSTED or 1 Usually used for untrusted certificates.

NEUTRAL or 2 Usually applied if trust level is not relevant or the certificate is only d for required for certificate chain creation.

Table 13: Possible values for –trustLevel

Please note that the trust level of certificates considered “trusted” by publishers of trusted lists

cannot be changed. Moreover please note that the status NEUTRAL is an initial status used for

certificate import. If the certificate status is NOT_TRUSTED or TRUSTED it cannot be changed

into NEUTRAL. To change trust level into NEUTRAL once again, the certificate has to be removed

and reimported.

6.3.3 Option -kernelAddress <kernel_adress>

The option -kernelAddress specifies the TCP/IP address for communication with the

OpenLimit V3 Server. If this option is not set, the address localhost is used.

6.3.4 Option -kernelPort <kernel_port>

The option -kernelPort specifies the port for AdminTool and OpenLimit V3 Server

communication. If a kernel port is not indicated, port 18080 is used for communication.


58

7 Electronic Signature Verification

7.1 Introduction

The OpenLimit V3 Server is designed to verify signatures in CMS- (RFC 5652) or PKCS #7- and

XML-format18 (based on X.509 certificates). Thereby already existing electronic signatures in the

following container formats are processed:

The signature exists as a detached signature to the original document (CMS,PKCS

or PDF format)

Signature and document are encoded in a connected data container (CMS, PKCS

or PDF format)

The signature is part of a PDF document and embedded in the document as a PDF

signature (PDF format)

The signature exists as a detached, enveloped or enveloping XML signature (XML

format)

The CMS or PKCS#7 formats includes the structure of so called SignerInfos. That means that a

container can contain several electronic signatures that refer to the same original document .

In this context it is important to have a closer look at PDF documents. According to the PDF/A

standard a PDF document can contain an embedded signature in PKCS#7 or CMS format. In this

case the number of valid SignerInfos for each embedded signature is exactly 1. For more

detailed information concerning the use of electronic documents in PDF documents, please

click on the following link (Tech Note 0006, Digital Signatures in PDF/A):

http://www.pdfa.org/wp-content/uploads/2011/08/tn0006_digital_signatures_in_pdfa-1_2008-03-14.pdf

This is different with the XML format. Here, every single signature is tagged by the element

<Signature> which conforms to the SignerInfo mentioned above. An XML signature can be

created in three different ways:

Detached (http://www.w3.org/TR/xmldsig-core/#def-SignatureDetached),

Enveloped (http://www.w3.org/TR/xmldsig-core/#def-SignatureEnveloped),

Enveloping (http://www.w3.org/TR/xmldsig-core/#def-SignatureEnveloping).

Electronic signature verification via the OpenLimit V3 Server is described below. Please note

that verification is described in general. For more detailed information, please see the

appropriate standards.

18 XML signatures according to http://www.w3.org/TR/xmldsig-core/ with support from XAdES timestamps

(http://www.w3.org/TR/XAdES/)

http://www.w3.org/TR/xmldsig-core/#def-SignatureDetached

http://www.w3.org/TR/xmldsig-core/#def-SignatureEnveloped

http://www.w3.org/TR/xmldsig-core/#def-SignatureEnveloping

http://www.w3.org/TR/xmldsig-core/

http://www.w3.org/TR/XAdES/


59

7.1.1 Verification of Document Type and Check for Available Signatures

The first step is to determine document type and available signatures . In the case of PDF

signatures the document needs to be checked for possible embedded signatures. In addition all

processed documents (including PDF documents) are checked for existing detached CMS

containers and it is analyzed if the document itself has been transmitted to the software as a

CMS container.

7.1.2 Verification of SignedAttributes and Correlation with the Document

CMS signatures contain so-called SignedAttributes that include amongst others the hash

value of the original document and a reference to the signature certificate used. The

correctness of the hash value in relation to the original document is technically verified.

7.1.3 XML – Verification of the SignedInfo and Correlation with the Document

The SignedAttributes conforms to the XML element SignedInfo (see section 7.1.2

Verification of SignedAttributes and Correlation with the Document).

7.1.4 Certificate Chain Structure and Technical Signature Verification

The signature certificate used is determined based on the signature container, and the

technical signature of the container or document is verified. Furthermore, based on the

signature certificate, efforts are made to build up the certificate chain to the root certificate.

7.1.5 Validity Model for Signature Verification

The certificates used for creating a signature must have been valid (neither revoked nor

expired) at the point of signature creation. The validity model used (hybrid or chain model)

determines which point in time is used to verify the signature. Verifying the validity of the

certificates involves checking their validity period as well as evaluating their status

information – in respect of the points in time specified by validity model (see also 3.1 Certificate

Qualities).

When applying the German signature law the verification of qualified signatures has to be

executed using the chain model. Advanced signatures on the other hand have to be verified

according to the modified shell model (HXBRID) in accordance with X.509.

In the OpenLimit V3 Server, you can specify the validity model to be used in the verification of

signatures in the configuration file siqSEMkSrv_svr.cfg in the parameter

VerificationModel as follows:

HYBRID Use of the hybrid model (modified shell model)


60

CHAIN Use the chain model

DEFAULT Auto configuration of the validity

model used based on the type19 of certificates used.

Validation of Used Certificates

The certificate chain is verified according to the preset validation policy. Normally, the

software tries to verify certificate validity with the help of an OCSP response. The trust status

of the root certificate is determined as well during the validation of the root certificate. An

unknown or untrusted root certificate leads to unsuccessful signature verification!

If it is not possible to obtain an OCSP response, the software will attempt to fall back on

certificate revocation lists, if this is intended by the validation policy (see 5.3.3 Changing the

Order of the Revocation Check)

Please note that availability of revocation information depends on the service provider used.

Interruption of the service can have a negative influence on the signature verification result

(see 7.2.6 SIQ_E_VRF_CERTIFICATE (a1002005)).

7.1.6 Verification of Algorithm Security Compatibility

Finally, security-related suitability of participating algorithms is verified. Therefore the

software makes use of the included algorithm catalogs to generate a final verification

statement concerning the validity of the electronic signature (see 3.2.2 Algorithm Catalogs).

The OpenLimit V3 Server requires the request of the signature verification result explicitly at

the programmable interface (SDK). The received verification result is the accumulated result of

all individual verifications performed. Basically the worst determined partial result is returned

at the interface. This means, for example, that a certificate whose validity cannot be

conclusively determined will result in the problem with the certificate being signaled as a

signature verification result if otherwise all the other sub-verification results are positive.

However, the problem of finding a week algorithm (e.g. an obsolete hash algorithm has been

used after expiration of security compatibility) is more serious when it comes to signature

verification as cryptographic security of the verified signature is in question. Sometimes a

signature cannot be found or verified. The following are the main reasons for this:

In the case of an embedded PDF signature the document has been destroyed to

such an extent that the catalog entry for the signature has been corrupted or

deleted from the document. Thus the signature in the PDF document may not be

found.

The signature container is structurally so heavily corrupted and therefore can no

longer be identified and processed as a signature container.

19 Qualified certificates are determined via the Trustbase provided by OpenLimit and are verified in accordance with

the chain model. All other signatures are verified in accordance with the hybrid model.


61

The software does not support the signature type or encoding used.

For more detailed information concerning these problem cases, please contact the support

service provider if necessary. Please see the requirements of the support service provider.

7.2 Verification Results (Importance of Return Values)

The verification result is returned as a combined value and represents the worst value of the

verification details. A document can contain one or more signatures. The verification result

represents the verification of all signatures in a document. This summary is included in every

verification protocol of a verified document.

The order of return values is of special importance. Once a status is reached, it cannot be

improved.

To receive a positive signature verification result, the certificates in the OpenLimit V3 Server must

have a valid and complete certificate chain. That means, the appropriate root certificate must be

included in a trusted list known to the OpenLimit V3 Server.

7.2.1 SIQ_E_VRF_INCOMPLETE (e1002000)

SIQ_E_VRF_INCOMPLETE is always returned if verification does not lead to a binding

statement due to the fact that available information is not sufficient for status information.

The following cases lead to SIQ_E_VRF_INCOMPLETE:

The trust status for the signature certificate cannot be determined (certificate

chain does not contain a trusted CA or root certificate)

The certificate chain could not be created, i.e. the certificate publisher is

unknown

Use of algorithms or formats that are not supported by the software

There are many different reasons for such a verification result when analyzing a

file. A frequent cause is an unknown root certificate or both an unknown root and

CA certificate. This can be identified if the XML data stream contains a reference

to the original signature certificate during signature verification but the

reference to a CA or root certificate is missing. These situations are typical for

CMS containers that include no further certificates except for the signature

certificate or that are based on a root instance unknown in the configuration of

the product.

Sometimes unknown algorithms have been used for signature creation. This can

be recognized from the verification data stream as well because in this case

information about the executed verification of cryptographic checksums or

signatures is missing.

Result: No positive signature verification result.


62

7.2.2 SIQ_E_VRF_NOSIGNATURES (e1002001)

If there is no verifiable signature during signature verification,

SIQ_E_VRF_NOSIGNATURES is returned. This verification result means that there in fact

are no available signatures or the signatures included in the document could not be processed

by the software.

This problem can occur if the document is damaged (e.g. a PDF document structurally damaged

to such an extent that the signature cannot be found) or the kind of signature encoding is

unknown to the software. Formats such as PGP signatures in base64 encoding, for example,

cannot be processed for verification by the V3 Server.

Result: Signature verification has not been performed.

7.2.3 SIQ_E_VRF_WRONGMESSAGEDIGEST (e1002002)

The following cases lead to SIQ_E_VRF_WRONGMESSAGEDIGEST:

The calculated data hash value and the hash value included in the

signedAtttributes of the signature are not equal

During timestamp verification the MessageImprint (reference to the

document, the timestamp was provided for) cannot be verified (for example

because the timestamp does not belong to the document or the hash

algorithm is unknown).

Regarding XML-signatures, references could not be resolved or found (e.g.

when external references are used, since they are not supported).

The cryptographic check finished with a positive result, but by the time of

signing the utilized algorithm was already estimated as weak.

In the event that the electronic signature has directly been computed on the data (e.g. PKCS #7

without signedAttributes) and the calculated hash value differs from the hash value

included in the signature, SIQ_E_VRF_WRONGSIGNATURE is returned.

Result: The signature is not valid.

In the case of detached signature files the reason may be that the signature and the apparently

associated document do not belong together.

7.2.4 SIQ_E_VRF_WRONGSIGNATURE (e1002003)

The following cases lead to SIQ_E_VRF_WRONGSIGNATURE:

The cryptographic signature could not be calculated with the public key of the

signature certificate

A signature already uses invalid algorithms at signature creation time



63

Indeed, if the referenced signature certificate is missing or a certificate chain to a trust anchor

cannot be created, the status SIQ_E_VRF_INCOMPLETE is displayed.

7.2.5 SIQ_E_VRF_WRONGCERTIFICATE (e1002004)

SIQ_E_VRF_WRONGCERTIFICATE is always returned if the signature has been created

with the key indicated in the certificate but the certificate itself should not have been used.

The following cases lead to SIQ_E_VRF_WRONGCERTIFICATE:

The signature has been created outside the validity period of the signature

certificate

Signature certificate was revoked at signature creation time

The certificate was not suitable for signing (certificate usage)

A CA or root certificate was revoked or the application is not explicitly allowed

according to the verification policy

This error code indicates that the used signature certificate is not suitable for

signature creation. This is for instance the case with certificates that are created

with tools such as OpenSSL and do not have the required attributes for signature

creation.


7.2.6 SIQ_E_VRF_CERTIFICATE (a1002005)

The following cases lead to SIQ_E_VRF_CERTIFICATE:

The cryptographic signature was correctly verified by using the public key of the

signature certificate and the certificates used for the signing process are

trustworthy. However, there are erroneous statuses or verification information is

missing (certificate revocation lists and OCSP)

In this case, the availability of required online connections for validity or

revocation information retrieval must be checked. If this error code is still

permanently displayed, it can be caused by the fact that one of the certificates

includes a wrong URL for requesting OCSP responses or certificate revocation list

retrieval. In this case, the OpenLimit V3 Server configuration needs to be

modified, as there is no automatism available to avoid this situation.

Basically the signature verification result should be “better“ than

SIQ_E_VRF_CERTIFICATE, as this code only guarantees a successful

technical verification (i.e. the verification of hash values and technical

signatures) but provides no information concerning signature validity.

Result: The signature is technically correct. The validity could not be determined.


64

7.2.7 SIQ_E_VRF_WEAKALGORITHM (a1002006)

The following cases lead to SIQ_E_VRF_WEAKALGORITHM:

A hash or signature algorithm used for signing does not meet current verification

requirements according to the internal algorithm catalog

In contrast to code E_WARNING this error code is evaluated as an error. Algorithms declared

as broken can generally get the status SIQ_E_VRF_WEAKALGORITHM. The signature is no

longer trustworthy as the technical security of the verified signature is in question.


7.2.8 SIQ_E_VRF_INFORMATION (61002FF0)

The following case leads to SIQ_E_VRF_INFORMATION:

Verification on the basis of a special verification policy was executed with a

positive verification result but a final statement cannot be made. This is the case

with valid/current certificate revocation lists that have been published prior to

signing time without an automatic OCSP verification.

A common situation leading to this message is the use of certificate revocation

lists published prior to signature creation time. In this case it is important that

the software can retrieve current certificate revocation lists from the internet for

successful signature verification.

A special situation arises when revocation lists are sometimes published, which

no longer include a “Next Update” field. When signatures which use such

revocation lists are verified and no OCSP responses are available, the verification

result of such signatures cannot be any better.

Details concerning the actual verification process need to be checked – similar to

the other problem cases – with the help of the generated XML data stream.

Result: The signature is technically correct. The validity could not be determined.

7.2.9 SIQ_E_VRF_SUCCESS (21002FFF)

The following case leads to SIQ_E_VRF_SUCCESS:

Based on the applied verification policy a complete and successful verification

could be carried out.

Result: The signature is valid.


65

8 Information on Technical Questions

8.1 Which Hash Algorithms Are Supported?

The following algorithms are supported:

SHA-1 (no longer suitable for QES)

SHA-224

SHA-256

SHA-384

SHA-512

RIPEMD-160 (no longer suitable for QES)

8.2 Which Signature Types Are Supported?

8.2.1 Signature Container

CMS (Cryptographic Message Syntax)

PKCS #7 (Public Key Cryptographic Syntax Part 7)

XML-DSig

8.2.2 Technical Signatures

RSA from 1024 to 4096 bits

DSA key (sha1DSA)

ECDSA with NIST and Brainpool curves

8.2.3 Padding Schemes

PSS Padding20

PKCS #1 Version 1.5

DIN-Sig-Padding

20 Not for XML signatures


66

8.3 Error Handling

Common error situations that may occur when using the product are described below.

Error Situation Cause and Hints How to Behave

When starting siqService the error message “No authorization” is displayed

Please ensure that siqService access authorization is set at executable

Firewall blocks V3 Server port

Port TCP/18080 on the host must be available from outside.

The OpenLimit V3 Server does not verify some documents although Adobe Acrobat is able to do so.

Please note that during the verification of signed PDF documents that have been manipulated the signature may not be recognized. You may receive a message that the file does not include a verifiable signature although Acrobat, for instance, can perform verification. This is caused by the application of different verification mechanisms.

The V3 Server was deactivated during start-up.

Please evaluate SDK interface return values and check for manipulation (SIQ_E_MSU (e100F000)). In the event of manipulation, please compare the installed distribution with the delivered version. If the two versions differ, please install the software again.

Table 14: Common errors

For further error messages and detailed descriptions, please see document

“OpenLimit_V3_return values”.

8.3.1 Support

If you have problems you cannot solve, please contact the OpenLimit support team:

Phone: +49 900 147 8877

https://www.openlimit.com/en/support/service.html

https://www.openlimit.com/en/support/service.html

manual openlimit middleware version 3 server ... -...

Documents