<

| Dokumentation |

MOA: Serversignatur (SS) und Signaturprüfung (SP)

Installation

# Inhalt

1. Übersicht

2. Webservice

   1. Basisinstallation
      1. Einführung
      2. Installation
         1. Vorbereitung
         2. Konfiguration von Apache Tomcat
            1. Konfiguration des HTTP Connectors
            2. Konfiguration des HTTPS Connectors
            3. Einrichten des MOA SP/SS Administrators
         3. Einsatz des MOA SP/SS Webservices in Tomcat
         4. Starten und Stoppen von Tomcat
            1. Unter Windows
            2. Unter Unix
            3. Prüfen des erfolgreichen Starts
         5. Änderung der Konfiguration im laufenden Betrieb
      3. Logging
         1. Format der Log-Meldungen
         2. Wichtige Log-Meldungen
   2. Erweiterungsmöglichkeiten
      1. Vorgeschalteter Webserver
         1. Microsoft Internet Information Server (MS IIS)
            1. Konfiguration von mod_jk im MS IIS
            2. Konfiguration von Tomcat
            3. Konfiguration von SSL
         2. Apache
            1. Konfiguration von mod_jk im Apache
            2. Konfiguration von Tomcat
            3. Konfiguration von SSL mit mod_SSL
      2. Datenbank
         1. PostgreSQL
            1. Anlegen eines Benutzers und einer Datenbank für MOA SP/SS
            2. Archivierung von CRLs
            3. Logging
         2. Andere Datenbanken
3. Klassenbibliothek
   1. Basisinstallation
      1. Einführung
      2. Vorbereitung
      3. Verwendung
      4. Logging
   2. Erweiterungsmöglichkeiten

1. Referenzierte Software

# 1 Übersicht

Die Module Signaturprüfung (SP) und Serversignatur (SS) sind als plattformunabhängige Module ausgelegt, die entweder als Webservice über HTTP bzw. HTTPS oder als Klassenbibliothek über ein API angesprochen werden können. Dieses Handbuch beschreibt die Installation der beiden Module als Webservice oder als Klassenbibliothek, sowie die Einrichtung der Systemumgebung.

# 2 Webservice

Dieser Abschnitt beschreibt die Installation von MOA SP/SS als Webservice. Im ersten Unterkapitel wird eine minimale Basisinstallation beschrieben. Das zweite Unterkapitel zeigt eine Reihe von optionalen Erweiterungsmöglichkeiten auf.

## 2.1 Basisinstallation

### 2.1.1 Einführung

Die Basisinstallation des Webservices stellt einerseits die minimalen Anforderungen für den Betrieb von MOA SP/SS als Webservices dar, andererseits dient sie als Ausgangspunkt für optionale Erweiterungsmöglichkeiten.

Die Mindestanforderungen für die Basisinstallation sind:

- Java SE / OpenJDK 7 oder höher
- Apache Tomcat 7 oder höher

Wir empfehlen jedoch jeweils aktuelle Version zu verwenden:

- Java SE / OpenJDK 8 (neuestes Update) oder Jave SE / OpenJDK 11
- Apache Tomcat 8.5 oder höher

In diesem Betriebs-Szenario wird das MOA SP/SS Webservice in Tomcat zum Einsatz gebracht. Tomcat fungiert gleichzeitig als HTTP- und HTTPS-Endpunkt für das MOA SP/SS Webservice. Beide Protokolle werden direkt in Tomcat konfiguriert. Das MOA SP/SS Webservice verwendet LogBack als Logging Toolkit.

### 2.1.2 Installation

#### 2.1.2.1 Vorbereitung

Die folgenden Schritte dienen der Vorbereitung der Installation.

Installation von Java SE
  Installieren Sie Java SE in ein beliebiges Verzeichnis. Das Wurzelverzeichnis der Java SE Installation wird im weiteren Verlauf als `$JAVA_HOME` bezeichnet.
Installation von Apache Tomcat
  Installieren Sie Apache Tomcat in ein Verzeichnis, das keine Leerzeichen im Pfadnamen enthält. Verwenden Sie bitte die zu Ihrer Java SE passende Distribution von Tomcat. Das Wurzelverzeichnis der Tomcat-Installation wird im weiteren Verlauf als `$CATALINA_HOME` bezeichnet.
Entpacken der MOA SP/SS Webservice Distribution
  Entpacken Sie die Datei `moa-spss-3.1.x.zip` in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als `$MOA_SPSS_INST` bezeichnet.
Installation der Kryptographiebibliotheken von SIC/IAIK

  Kopieren Sie alle Dateien aus dem Verzeichnis `$MOA_SPSS_INST/ext` in das Verzeichnis `$JAVA_HOME/jre/lib/ext`. Zusätzlich müssen Sie die Rechtedateien Ihrer Java SE austauschen. Laden Sie dazu die passenden Unlimited Strength Jurisdiction Policy Files von der Java SE Downloadseite und achten Sie darauf die für ihre verwendete Java SE Installation richtige Version zu nehmen. Anschließend folgen Sie der darin enthaltenen Installationsanweisung.

#### 2.1.2.2 Konfiguration von Apache Tomcat

Die zentrale Konfigurations-Datei von Tomcat ist `$CATALINA_HOME/conf/server.xml`. Tomcat wird grundsätzlich mit einer funktionierenden Default-Konfiguration ausgeliefert.

##### 2.1.2.2.1 Konfiguration des HTTP Connectors

Die Tomcat Default-Konfiguration schaltet ausschließlich den Connector für HTTP auf Port 8080 frei. Wir empfehlen diese Konfiguration nur für Fälle, in denen das MOA SP/SS Webservice in einer abgeschlossenen Netzwerkumgebung betrieben wird.

##### 2.1.2.2.2 Konfiguration des HTTPS Connectors

Wird das MOA SP/SS Webservice in einer nicht abgeschlossenen Umgebung (z.B. Erreichbarkeit über das Internet) betrieben, ist die gegenseitige Identitätsfeststellung von Kunde und Webservice essentiell:

- Nutzt ein Kunde MOA SP, ist es für ihn wichtig, die Identität des Webservice eindeutig feststellen zu können, denn er vertraut dem Webservice ja die Prüfung einer elektronischen Signatur an.
- Nutzt ein Kunde MOA SS, ist es für ihn wesentlich, dass nur er Zugriff auf die für ihn vom Webservice verwalteten privaten Schlüssel hat, um elektronische Signaturen zu erstellen. Das Webservice muss also die Identität des Kunden prüfen.

Beide Identitätsprüfungen können mit hoher Qualität vorgenommen werden, wenn die Erreichbarkeit des Webservice auf SSL mit Server- (für MOA SP) bzw. Client- und Serverauthentisierung (für MOA SS) eingeschränkt wird.

Für die dazu notwendige Konfiguration kann die im vorigen Abschnitt besprochene minimale Tomcat-Konfiguration als Ausgangspunkt verwendet werden: Zunächst ist der HTTP Connector abzuschalten (auszukommentieren). Anschließend ist der HTTPS Connector zu konfigurieren. Das Dokument Tomcat SSL Configuration HOW-TO gibt einen guten Überblick dazu. Grob zusammengefasst sind folgende Schritte durchzuführen:

- Erstellung eines Server-Keystores, der den privaten Schlüssel sowie das zugehörige Zertifikat des Webservices enthält, mit dem es sich bei Aufbau einer SSL-Verbindung gegenüber dem Kunden ausweist sowie das dazugehörige Server-Zertifikat enthält. Sie können diesen Keystore z.B. mit `keytool` erstellen, einem Programm, das Ihrer Java SE beiliegt.
- Erstellung eines Client-Keystores, der die Zertifikate aller Kunden des Webservices enthält. Nur Kunden des Webservices, die sich beim Aufbau einer SSL-Verbindung gegenüber dem Webservice mit einem im Client-Keystore enthaltenen Zertifikat ausweisen, erhalten grundsätzlich Zugriff zu den Diensten des Webservices (für die Konfiguration, welcher Kunde welche Schlüssel von MOA SS verwenden darf, siehe Abschnitt 2.2.3 des Konfigurationshandbuchs). Auch dieser Keystore kann z.B. mit `keytool` erstellt werden. Dieser Keystore ist optional und braucht nur erstellt zu werden, wenn sich die Kunden gegenüber dem Webservice authentisieren müssen.
- Konfiguration des HTTPS Connectors in `$CATALINA_HOME/conf/server.xml`.

Die Konfiguration des HTTPS Connectors kann entfallen, wenn Tomcat ein Webserver vorgeschaltet ist, und dieser die SSL-Kommunikation mit dem Kunden übernimmt (siehe Abschnitt 2.2.1).

##### 2.1.2.2.3 Einrichten des MOA SP/SS Administrators

Das MOA SP/SS Webservice kann remote durch den Aufruf einer speziellen URL des Webservices dazu veranlasst werden, seine Konfiguration neu einzulesen (vergleiche Abschnitt 2.1.2.5). Der Zugriff auf diese URL ist durch eine Passwort-Abfrage geschützt, und kann nur von Tomcat-Benutzern aufgerufen werden, denen die Tomcat-Benutzer-Rolle `moa-admin` zugeordnet wurde.

Um diese Benutzer-Rolle und einen oder mehrere Benutzer einzurichten, müssen in der Datei `$CATALINA_HOME/conf/tomcat-users.xml` unter dem Element `<tomcat-users>` sinngemäß folgende Einträge hinzugefügt werden:

    <role rolename="moa-admin"/>
    <user username="moa-chief" password="openSesam" roles="moa-admin"/>

Soll der Aufruf dieser URL niemandem ermöglicht werden, sind die oben beschriebenen Einträge einfach nicht vorzunehmen.

#### 2.1.2.3 Einsatz des MOA SP/SS Webservices in Tomcat

Um das MOA SP/SS Webservice in Tomcat für den Einsatz vorzubereiten, sind folgende Schritte notwendig:

- Die Datei `$MOA_SPSS_INST/moa-spss.war` enthält das einsatzfertige MOA SP/SS Webarchiv und muss ins Verzeichnis `$CATALINA_HOME/webapps` kopiert werden. Dort wird sie beim ersten Start von Tomcat automatisch ins Verzeichnis `$CATALINA_HOME/webapps/moa-spss` entpackt.
- Die zentrale Konfigurationsdatei für MOA SP/SS und die zugehörigen Profil-Verzeichnisse müssen in ein beliebiges Verzeichnis im Dateisystem kopiert werden (z.B. `$CATALINA_HOME/conf/moa-spss`). Eine funktionsfähige Konfiguration, die als Ausgangspunkt für die Konfiguration des MOA SP/SS Webservices dienen kann, finden Sie hier.
- Die Dateien `xalan.jar`, `xercesImpl.jar, serializer.jar` und `xml-apis.jar` aus dem Verzeichnis `$MOA_SPSS_INST/endorsed` müssen in das Tomcat-Verzeichnis `$CATALINA_HOME/endorsed` (bzw. `$CATALINA_HOME/common/endorsed` bis Apache Tomcat Version 5.5) kopiert werden. Sind gleichnamige Dateien dort bereits vorhanden, müssen sie überschrieben werden. Die ggf. in diesem Verzeichnis vorhandene Datei `xmlParserAPIs.jar` muss gelöscht werden. Sollte das Verzeichnis `endorsed` nicht vorhanden sein, dann muss dieses zuerst erstellt werden.
- Folgende System Properties können gesetzt werden (wird beim Starten von Tomcat der Java Virtual Machine in der Umgebungsvariablen `CATALINA_OPTS` in der Form `-D<name>=<wert>` übergeben):
  - `moa.spss.server.configuration`: Pfad und Name der zentralen Konfigurationsdatei für MOA SP/SS. Eine beispielhafte Konfigurationsdatei finden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter `WEB-INF/conf` enthaltene Default-Konfiguration herangezogen.
  - `iaik.esi.sva.configuration.location`: Pfad und Name der Konfigurationsdatei für die extendet PDF Validierung von MOA SP/SS. Eine beispielhafte Konfigurationsdatei finden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert.
  - `logback.configurationFile`: URL der LogBack Konfigurationsdatei. Eine beispielhafte LogBack-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter `WEB-INF/classes` enthaltene Default-Konfiguration herangezogen.
  - `moa.node.id`: Frei wählbarer Name des Rechner-Knotens, auf dem MOA SP/SS läuft. Der Name des Knotens wird bei Log-Ausgaben von MOA SP/SS angeführt und dient zur Unterscheidung mehrerer gleichzeitig betriebener MOA SP/SS Webservice-Instanzen.
  - `javax.net.ssl.trustStore`: Pfad und Dateiname des Truststores für vertrauenswürdige SSL Client-Zertifikate (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Ein relativer Pfad werden relativ zum Startverzeichnis der Java Virtual Machine interpretiert.
  - `javax.net.ssl.trustStorePassword`: Passwort für den Truststore (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll).
  - `javax.net.ssl.trustStoreType`: Truststore-Typ (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Je nach verwendetem Keystore-Typ muss `jks` (Java Key Store) oder `pkcs12` (PKCS#12-Datei) angegeben werden.

#### 2.1.2.4 Starten und Stoppen von Tomcat

##### 2.1.2.4.1 Unter Windows

Das Verzeichnis `$MOA_SPSS_INST/tomcat/win32` enthält Script-Dateien zum Starten und Stoppen von Tomcat. Vor der erstmaligen Verwendung der Scripts müssen in den ersten Zeilen die Umgebungsvariablen `JAVA_HOME` (Basisverzeichnis der eingesetzten Java SE) und `CATALINA_HOME` (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden. Evtl. müssen Sie auch noch die in den Script-Dateien gesetzten, in Abschnitt 2.1.2.3 besprochenen System Properties anpassen.

##### 2.1.2.4.2 Unter Unix

Zunächst müssen die in Abschnitt 2.1.2.3 besprochenen System Properties mit Hilfe der Umgebungsvariablen `CATALINA_OPTS` gesetzt sein. Die Datei `$MOA_SPSS_INST/tomcat/unix/moa-env.sh` enthält ein Beispiel dafür. Weiters müssen noch die Umgebungsvariablen `JAVA_HOME` (Basisverzeichnis der eingesetzten Java SE) und `CATALINA_HOME` (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden.

Nun kann Tomcat aus seinem Basisverzeichnis mit

    bin/catalina.sh start

gestartet werden. Das Stoppen von Tomcat erfolgt analog mit

    bin/catalina.sh stop

##### 2.1.2.4.3 Prüfen des erfolgreichen Starts

Ein erfolgreicher Start des MOA SP/SS Webservices ist an folgender Log-Meldung ersichtlich:

    INFO | 18 10:09:45,155 | main | TID=startup NID=<null> MSG=MOA Konfiguration erfolgreich geladen

Bei leichten Fehlern in der Konfiguration geben `WARN` Log-Meldungen unmittelbar davor Aufschluss über fehlerhafte Konfigurations-Einträge. Nach dem Starten von Tomcat steht das MOA SP/SS Webservice für die Server-Signatur und Signatur-Prüfung unter den Endpunkten

    http://<host>:<port>/moa-spss/services/SignatureCreation

bzw.

    http://<host>:<port>/moa-spss/services/SignatureVerification

zur Verfügung. Die Verfügbarkeit des Services können Sie einfach überprüfen, indem Sie die Endpunkte mit einem Web-Browser aufgerufen; dies sollte nach erfolgreichem Start zur Anzeige einer Informationsseite führen.

Konnte das MOA SP/SS Webservice nicht ordnungsgemäß gestartet werden, führt das zu folgender Log-Meldung:

    FATAL | 18 10:17:03,475 | main | TID=startup NID=<null>
      MSG=Fehler beim Lesen der MOA Konfiguration: das Service steht nicht zur Verfügung

In diesem Fall geben die `WARN` bzw. `ERROR` Log-Meldungen unmittelbar davor Aufschluss über den genaueren Grund.

#### 2.1.2.5 Änderung der Konfiguration im laufenden Betrieb

Sie können die Konfiguration für MOA SP/SS im laufenden Betrieb aktualisieren, in dem Sie mittels eines Web-Browsers folgende URL aufrufen:

     http://<host>:<port>/moa-spss/ConfigurationUpdate

Damit dies funktioniert, muss in der Konfiguration von Tomcat ein spezieller Benutzer sowie eine spezielle Benutzerrolle eingerichtet werden (vergleiche Abschnitt 2.1.2.2.3).

### 2.1.3 Logging

Das MOA SP/SS Webservice verwendet LogBack für die Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. LogBack bietet zahlreiche Konfigurationsmöglichkeiten, die ausführlich im LogBack Handbuch beschrieben sind. Unter anderem gibt es die Möglichkeit, folgende Einstellungen vorzunehmen:

- Das verwendete Log-Level (`DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`);

- Name und maximale Größe der Log-Datei(en);

- Das Aussehen der Log-Einträge.

Das MOA SP/SS Webservice verwendet folgende Log-Hierarchien:

- `moa.spss.server` für alle Log-Meldungen aus dem MOA/SPSS Webservice;

- `iaik.server` für alle Log-Meldungen aus den SIC/IAIK Kryptographie-Modulen.

Eine für MOA SP/SS passende Konfigurationsdatei für LogBack finden Sie hier. Wird diese Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen sowohl in die Konsole, als auch in die Datei `moa-spss.log` geschrieben.

#### 2.1.3.1 Format der Log-Meldungen

Anhand einer konkreten Log-Meldung wird das Format der MOA SP/SS Log-Meldungen erläutert:

    INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=node1
      MSG=Starte neue Transaktion: TID=1049225059594-100, Service=SignatureVerification

Der Wert `INFO` besagt, dass die Log-Meldung im Log-Level `INFO` entstanden ist. Folgende Log-Levels existieren:

- `DEBUG`: Log-Meldungen im Log-Level `DEBUG` geben Auskunft über die innere Arbeitsweise des Systems. Sie sind hauptsächlich für Entwickler interessant.

- `INFO`: Diese Log-Meldungen geben Status-Informationen über den Ablauf des Webservices, wie z.B. über das Einlangen einer neuen Anfrage.

- `WARN`: Bei der Ausführung einer Anfrage sind leichte Fehler aufgetreten. Der Ablauf des Webservices ist nicht weiter beeinträchtigt.

- `ERROR`: Die Ausführung einer Anfrage musste abgebrochen werden. Das Webservice ist davon nicht beeinträchtigt.

- `FATAL`: Es ist ein Fehler aufgetreten, der den weiteren Betrieb des Webservices nicht mehr erlaubt.

Der nächste Wert `01 21:25:26,540` gibt den Zeitpunkt an, zu dem die Log-Meldung generiert wurde (in diesem Fall den 1. Tag im aktuellen Monat, sowie die genaue Uhrzeit).

Der Wert `Thread-3` bezeichnet den Thread, von dem die Anfrage bearbeitet wird.

Der Wert von `TID` gibt die für jede Anfrage eindeutige Transaktions-ID an. Log-Meldungen, die bei der Abarbeitung dieser Anfrage geschrieben werden, enthalten alle einen Hinweis auf die entsprechende Transaktions-ID.

Der Wert von `NID` gibt den Rechner-Knoten an, auf dem das MOA SP/SS Webservice läuft (bei `NID=<null>` ist dieser Wert nicht konfiguriert, vergleiche Abschnitt 2.1.2.3).

Der Rest der Zeile einer Log-Meldung ist der eigentliche Text, mit dem das System bestimmte Informationen anzeigt. Im Fehlerfall ist häufig ein Java Stack-Trace angefügt, der eine genauere Ursachen-Forschung ermöglicht.

#### 2.1.3.2 Wichtige Log-Meldungen

Neben den im Abschnitt 2.1.2.4.3 beschriebenen Log-Meldungen, die anzeigen, ob das Service ordnungsgemäß gestartet wurde, geben nachfolgenden Log-Meldungen Aufschluss über die Abarbeitung von Anfragen.

Die Entgegennahme einer Anfrage wird angezeigt durch:

    INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=<null>
      MSG=Starte neue Transaktion: TID=1049225059594-100, Service=SignatureVerification
    INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=<null>
      MSG=Aufruf von Adresse=127.0.0.1
    INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=<null>
      MSG=Client-Zertifikat nicht verfügbar

Die dritte Log-Meldung besagt, dass für die Abarbeitung dieser Anfrage kein Client-Zertifikat verfügbar ist (entweder, weil die Anfrage über HTTP eingelangt ist, oder weil die SSL Client-Authentisierung nicht eingeschaltet ist). Bei erfolgreicher SSL Client-Authentisierung, gibt beispielsweise folgende Log-Meldung Informationen über das Client-Zertifikat aus:

    INFO | 12 13:58:08,772 | Thread-10 | TID=1045054687159-2 NID=<null>
      MSG=Client-Zertifikat: Subject=CN=Testuser, OU=MOA, O=BRZ, L=Vienna, ST=Vienna, C=AT,
      Serial=1.039.104.204, Issuer=CN=TestCA, OU=MOA, O=BRZ, L=Vienna, ST=Vienna, C=AT

Eine erfolgreich abgearbeitete Anfrage wird angezeigt durch:

    INFO | 01 21:25:53,168 | Thread-3 | TID=1049225059594-106 NID=<null>
      MSG=Anfrage erfolgreich abgearbeitet

Ein Fehler beim Abarbeiten der Anfrage wird angezeigt durch:

    INFO | 01 21:25:27,642 | Thread-3 | TID=1049225059594-100 NID=<null>
      MSG=Fehler beim Abarbeiten der Anfrage

In diesem Fall gibt der mitgeloggte Stacktrace Auskunft über die Art des Fehlers. Der Aufrufer des MOA SP/SS Webservices bekommt einen Fehlercode sowie eine kurze Beschreibung des Fehlers als Antwort zurück.

Die tatsächlich übertragenen Anfragen bzw. Antworten werden aus Effizienzgründen nur im Log-Level `DEBUG` angezeigt.

## 2.2 Erweiterungsmöglichkeiten

Ausgehend von der Basisinstallation können die optionalen Erweiterungen, die in den nachfolgenden Abschnitten beschrieben werden, unabhängig und in beliebiger Kombination aufgesetzt werden.

### 2.2.1 Vorgeschalteter Webserver

#### 2.2.1.1 Microsoft Internet Information Server (MS IIS)

Den MOA SP/SS Webservices kann optional ein MS IIS vorgeschaltet sein. In diesem Fall übernimmt der MS IIS die HTTP- bzw. HTTPS-Kommunikation mit dem Aufrufer des Webservices. Die Kommunikation zwischen MS IIS und dem in Tomcat eingerichteten MOA SP/SS Webservice wird durch mod_jk durchgeführt. Die angeführten Konfigurationsschritte gehen von einer MS IIS Standard-Installation aus.

##### 2.2.1.1.1 Konfiguration von mod_jk im MS IIS

Für die Kommunikation des MS IIS mit dem im Tomcat eingerichteten MOA SP/SS Webservice wird das ISAPI-Modul von mod_jk im MS IIS installiert und konfiguriert. Eine detaillierte Installations- und Konfigurationsanleitung gibt das mod_jk IIS HowTo. Beispiele für `workers.properties` und `uriworkermap.properties` Dateien liegen im Verzeichnis `$MOA_SPSS_INST/tomcat` bei.

##### 2.2.1.1.2 Konfiguration von Tomcat

Damit Tomcat die Aufrufe entgegennehmen kann, die von MS IIS mittels mod_jk weiterleitet werden, muss in `$CATALINA_HOME/conf/server.xml` der AJP Connector aktiviert werden. Im Gegenzug können die Konnektoren für HTTP und HTTPS deaktiviert werden. Das geschieht am einfachsten durch Ein- bzw. Auskommentieren der entsprechenden `Connector` Konfigurations-Elemente in dieser Datei.

##### 2.2.1.1.3 Konfiguration von SSL

Die Dokumentation zum Einrichten von SSL auf dem MS IIS steht nach Installation des IIS unter http://localhost/iisHelp/ oder aber auch auf den Webseiten von Mircrosoft zur Verfügung.

#### 2.2.1.2 Apache

Den MOA SP/SS Webservices kann ein Apache Webserver vorgeschaltet sein. Das Prinzip funktioniert wie bei MS IIS, auch hier wird mod_jk für die Kommunikation zwischen Webserver und Tomcat eingesetzt. Die angeführten Konfigurationsschritte gehen von einer Standard-Installation des Apache Webservers aus.

##### 2.2.1.2.1 Konfiguration von mod_jk im Apache

Um das MOA-SPSS Webservice hinter einem Apache Webserver zu betreiben, ist die Konfiguration des Apache-Moduls mod_jk erforderlich. Eine detaillierte Installations- und Konfigurationsanleitung gibt das mod_jk Apache HowTo. Ein Beispiel für eine `workers.properties` Datei liegt im Verzeichnis `$MOA_SPSS_INST/tomcat` bei.

Um das MOA SP/SS Webservice dem Apache Webserver bekannt zu machen, sind zumindest folgende Einträge im globalen Kontext der Apache-Konfigurationsdatei notwendig:

    LoadModule jk_module /usr/lib/apache/mod_jk.so
    AddModule jk_module
    JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
    JkWorkersFile conf/workers.properties
    JkMount /moa-spss/* moaworker

Die Pfad- und Dateinamen können je nach existierender Apache Installation geringfügig variieren.

##### 2.2.1.2.2 Konfiguration von Tomcat

Die Konfiguration von Tomcat ist analog zu Abschnitt 2.2.1.1.2 durchzuführen.

##### 2.2.1.2.2 Konfiguration von SSL mit mod_SSL

Apache kann in Verbindung mit mod_SSL als SSL-Endpunkt für das MOA SP/SS Webservice fungieren. In diesem Fall entfällt die SSL-Konfiguration in Tomcat, da Apache und Tomcat auch im Fall von SSL Daten via mod_jk austauschen. Eine detaillierte Installations- und Konfigurationsanleitung enthält die Online-Dokumentation von mod_SSL.

Bei der Verwendung von Client-Authentisierung muss darauf geachtet werden, dass mod_ssl die HTTP-Header mit den Informationen über das Client-Zertifikat exportiert. Dies wird durch Angabe der folgenden Option in der Apache-Konfiguration erreicht:

    SSLOptions +ExportCertData +StdEnvVars

Je nach vorhandener SSL-Konfiguration des Apache Webservers kann diese Option im globalen Kontext, im Kontext des Virtual Hosts oder im Kontext eines Verzeichnisses spezifiziert werden.

### 2.2.2 Datenbank

Die MOA SP/SS Module können eine Datenbank zum Archivieren von Certificate Revocation Lists (CRLs), sowie zum Abspeichern von Log-Meldungen verwenden. In beiden Fällen wird eine installierte und konfigurierte Datenbank vorausgesetzt.

#### 2.2.2.1 PostgreSQL

Eine detaillierte Übersicht über die Installation und Konfiguration von PostgreSQL gibt die Online-Dokumentation.

Bitte beachten Sie: Eine Möglichkeit, PostgreSQL unter MS Windows zu installieren, besteht darin, Cygwin mit dem PostgreSQL-Package zu installieren. Alternative Installationsvarianten werden in der PostgreSQL Dokumentation angeführt.

##### 2.2.2.1.1 Anlegen eines Benutzers und einer Datenbank für MOA SP/SS

Damit die MOA SP/SS Module eine Verbindung zu PostgreSQL aufbauen kann, müssen der Name eines PostgreSQL-Benutzers und einer PostgreSQL-Datenbank bekannt sein. Sollten diese nicht vorhanden sein, kann mit folgenden Kommandos ein Benutzer namens `moa` und eine Datenbank namens `moadb` angelegt werden:

    createuser -U postgres -d -A -P moa
    createdb -U moa moadb

Da die MOA SP/SS Module über JDBC mit der Datenbank kommunizieren, ist in der Folge die Angabe einer JDBC-URL notwendig, welche die Verbindungsparameter enthält. Wurden der Benutzer und die Datenbank wie im obigen Beispiel angelegt, ist folgende JDBC-URL anzugeben (Annahme: als Passwort für den Benutzer moa wurde moapass gewählt):

     jdbc:postgresql://host/moadb?user=moa&password=moapass

Die Zeichen `jdbc:postgresql://` sind unveränderliche Bestandteile einer PostgreSQL JDBC-URL. `host` gibt den Rechner an, auf dem PostgreSQL läuft. `moadb` identifiziert den Namen der Datenbank. Über die Parameter `user=` und `pass=` werden Benutzername und Passwort für den DB-User bekanntgegeben.

##### 2.2.2.1.2 Archivierung von CRLs

Zum Archivieren von CRLs müssen in der MOA SP/SS Konfigurationsdatei die Kinder des Elements `cfg:MOAConfiguration/cfg:SignatureVerification/cfg:CertificateValidation/cfg:RevocationChecking/cfg:Archiving` entsprechend konfiguriert werden:

- `cfg:EnableArchiving` muss auf den Wert `true` gesetzt sein;
- `cfg:ArchiveDuration` muss als nichtnegative Ganzzahl die maximale Archivierungsdauer in Tagen enthalten;
- `cfg:Archive` muss genau ein Element `cfg:DatabaseArchive` enthalten, das wiederum aus zwei Elementen bestehen muss:
  - `cfg:JDBCURL` muss eine gültige JDBC-URL enthalten, mit der auf die Datenbank zur Archivierung zugegriffen werden kann (Hinweis: da es sich hierbei um einen Eintrag in eine XML-Datei handelt, muss das Zeichen `&` in der in Abschnitt 2.2.2.1.1 gezeigten JDBC-URL durch die Zeichenfolge `&amp;` ersetzt werden.);
  - `cfg:JDBCDriverClassName` muss den vollständig qualifizierten Java-Klassennamen des JDBC-Treibers enthalten.

Vergleiche auch Abschnitt 2.3.1.3.4 im Konfigurationshandbuch.

##### 2.2.2.1.3 Logging

Für das Logging in eine PostgreSQL Datenbank mittels LogBack muss zunächst eine Tabelle für die Log-Meldungen angelegt werden. Dies kann mit folgendem SQL-Statement erreicht werden:

     create table spss_log (log_time timestamp, log_level varchar(5), log_msg text);

Damit LogBack die Log-Meldungen in diese Datenbanktabelle schreibt, muss die LogBack-Konfiguration adaptiert werden. Die mit MOA SP/SS mitgelieferte, beispielhafte LogBack-Konfiguration enthält bereits die notwendigen Einträge für das Logging in eine PostgreSQL Datenbank, die jedoch standardmäßig ausgeschaltet sind.

Wie beim Caching von CRLs ist auch hier die Angabe einer JDBC-URL notwendig, damit die MOA SP/SS Module eine Verbindung zur Datenbank aufnehmen können.

Bitte beachten Sie: Bei Tests hat sich das Logging in eine Datenbank mit LogBack als Performance-Engpass herausgestellt. Es wird deshalb empfohlen, dieses Feature mit Bedacht einzusetzen.

#### 2.2.2.2 Andere Datenbanken

Über die generische Anbindung JDBC können auch andere Datenbanken für die Archivierung von CRLs bzw. für die Speicherung der Log-Meldungen eingesetzt werden. Hinweise zu bestimmten Datenbanken finden Sie in den FAQ.

Die in Abschnitt 2.2.2.1 gemachten Angaben zu Archivierung von CRLs bzw. zur Speicherung von Log-Meldungen gelten sinngemäß.

### 2.2.3 Hardware Security Module (HSM)

MOA SS kann für die Erstellung von Signaturen auf die Dienste eines HSM zurückgreifen. Voraussetzung dafür ist, dass für das HSM eine Implementierung der Schnittstelle PCKS#11 (PKCS#11-Bibliothek) angeboten wird.

Für die Einbindung des HSM in MOA SS müssen zunächst die Bibliotheken aus `$MOA_SPSS_INST/pkcs11` in ein beliebiges Verzeichnis kopiert werden, welches dann in den Libray-Pfad des jeweiligen Betriebssystems aufgenommen werden muss (Windows: Umgebungsvariable `PATH`; Linux: Umgebungsvariable `LD_LIBRARY_PATH`).

Der Name der für das HSM spezifischen PKCS#11-Bibliothek muss in der Konfigurationsdatei eingetragen werden (vergleiche Abschnitt 2.2.1.1 des Konfigurationshandbuchs).

# 3 Klassenbibliothek

Dieser Abschnitt beschreibt die Verwendung von MOA SP/SS als Klassenbibliothek. Im ersten Unterkapitel wird eine minimale Basisinstallation beschrieben. Das zweite Unterkapitel zeigt eine Reihe von optionalen Erweiterungsmöglichkeiten auf.

## 3.1 Basisinstallation

### 3.1.1 Einführung

Die Basisinstallation der Klassenbibliothek stellt einerseits die minimalen Anforderungen für den Einsatz von MOA SP/SS als Klassenbibliothek dar, andererseits dient sie als Ausgangspunkt für optionale Erweiterungsmöglichkeiten.

Die Mindestanforderungen für die Basisinstallation sind:

- Java SE 8 oder höher

Wir empfehlen jedoch jeweils aktuelle Version zu verwenden:

- Java SE Update SE 11 (neuestes Update)

### 3.1.2 Vorbereitung

Die folgenden Schritte dienen der Vorbereitung der Installation.

Installation von Java SE
  Installieren Sie Java SE in ein beliebiges Verzeichnis. Das Wurzelverzeichnis der Java SE Installation wird im weiteren Verlauf als `$JAVA_HOME` bezeichnet.
Entpacken der MOA SP/SS Klassenbibliotheks-Distribution
  Entpacken Sie die Datei `moa-spss-3.0.x-lib.zip` in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als `$MOA_SPSS_INST` bezeichnet.
Installation der Kryptographiebibliotheken von SIC/IAIK

  Kopieren Sie alle Dateien aus dem Verzeichnis `$MOA_SPSS_INST/ext` in das Verzeichnis `$JAVA_HOME/jre/lib/ext`. Zusätzlich müssen Sie die Rechtedateien Ihrer Java SE austauschen. Laden Sie dazu die passenden Unlimited Strength Jurisdiction Policy Files von der Java SE Downloadseite und achten Sie darauf die für ihre verwendete Java SE Installation richtige Version zu nehmen. Anschließend folgen Sie der darin enthaltenen Installationsanweisung.