Open Source für das E-Government

MOA: Serversignatur (SS) und Signaturprüfung (SP), V 1.2

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. Klassenbibliothek

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.

Folgende Software ist Voraussetzung für die Basisinstallation des Webservices:

• J2SE 1.3.1 SDK oder J2SE 1.4.2 SDK oder J2SE 5.0 SDK
• Apache Tomcat 4.1.18 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 Log4j als Logging Toolkit.

2.1.2 Installation

2.1.2.1 Vorbereitung

Die folgenden Schritte dienen der Vorbereitung der Installation.

Installation von J2SE SDK

Installieren Sie J2SE 1.3.1 SDK oder J2SE 1.4.2 SDK oder J2SE 5.0 SDK in ein beliebiges Verzeichnis. Wir empfehlen die Installation von J2SE 5.0 SDK. Das Wurzelverzeichnis der J2SE SDK Installation wird im weiteren Verlauf als $JAVA_HOME bezeichnet.

Installation von Apache Tomcat 4.1

Installieren Sie Apache Tomcat 4.1.18 oder höher in ein Verzeichnis, das keine Leerzeichen im Pfadnamen enthält. Wir empfehlen die Installation von Apache Tomcat 4.1.31. Verwenden Sie bitte die zu Ihrem J2SE SDK 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-1.2.x.zip in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als $MOA_SPSS_INST bezeichnet.

Installation der mitgelieferten Krypographiebibliotheken

Die Installation der mitgelieferten Kryptographiebibliotheken des IAIK ist abhängig vom eingesetzten J2SE SDK:

J2SE 1.3.1 SDK

Kopieren Sie alle Dateien aus dem Verzeichnis $MOA_SPSS_INST/ext13 in das Verzeichnis $JAVA_HOME/jre/lib/ext.

J2SE 1.4.2 SDK oder JSE 5.0 SDK

Kopieren Sie alle Dateien aus dem Verzeichnis $MOA_SPSS_INST/ext14 in das Verzeichnis $JAVA_HOME/jre/lib/ext. Zusätzlich müssen Sie die Rechtedateien Ihres J2SE 1.4.2 SDK bzw. J2SE 5.0 SDK austauschen. Laden Sie dazu die Unlimited Strength Jurisdiction Policy Files von der J2SE 1.4.2 SDK Downloadseite bzw. J2SE 5.0 SDK Downloadseite und 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, die jedoch einiges an Ballast enthält und viele Ports offen lässt.

2.1.2.2.1 Konfiguration des HTTP Connectors

Die Datei $MOA_SPSS_INST/tomcat/server.xml enthält eine minimale Tomcat-Konfiguration, die ausschließlich den Connector für HTTP auf Port 8080 freischaltet. Durch kopieren dieser Datei nach $CATALINA_HOME/conf/server.xml kann Tomcat mit dieser Konfiguration gestartet werden. 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 ZertiServer-Zertifikat enthält. Sie können diesen Keystore z.B. mit keytool erstellen, einem Programm, das Ihrem J2SE SDK 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.7 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.
• Wird Tomcat unter J2SE 1.4.x SDK oder J2SE 5.0 SDK betrieben, muss die Datei xalan.jar aus dem Verzeichnis $MOA_SPSS_INST/endorsed14 in das Tomcat-Verzeichnis $CATALINA_HOME/common/endorsed kopiert werden (diese repräsentiert die XSLT/XPath Bibliothek Xalan-J-2.5.1). Ist die Datei dort bereits vorhanden, muss sie überschrieben 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.
  • log4j.configuration: URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-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

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 des eingesetzten J2SE SDK) und CATALINA_HOME (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden.

Nun kann Tomcat aus seinem Basisverzeichnis mit

bin/catalina.sh start

bin/catalina.sh stop

2.1.2.4.3 Prüfen des erfolgreichen Starts

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

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.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 Apache

2.2.1.2 Microsoft Internet Information Server

2.2.2 Datenbank

2.2.2.1 PostgreSQL

2.2.2.2 Oracle

2.2.3 Hardware Security Module (HSM)

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.

Folgende Software ist Voraussetzung für die Basisinstallation der Klassenbibliothek:

• J2SE 1.3.1 JRE oder J2SE 1.4.2 JRE

Die MOA SP/SS Klassenbibliothek verwendet Log4j als Logging Toolkit.

3.2.1 Installation

3.2 Erweiterungsmöglichkeiten

3.2.1 Datenbank

3.2.1.1 PostgreSQL

3.2.1.2 Oracle

3.2.2 Hardware Security Module (HSM)

A Referenzierte Software

Auf folgende Software-Pakete wird in diesem Handbuch verwiesen: