Module für Online-Applikationen
 
Projekt moa 

MOA-SP/SS

Basis-Installation
    (Webservice)

Basis-Installation (Webservice)

Vorbereitung

Installation des JDK
Installieren Sie das JDK 1.3.1 oder JDK 1.4.1 in ein beliebiges Verzeichnis. Das Wurzelverzeichnis der JDK-Installation wird im weiteren Verlauf als $JAVA_HOME bezeichnet.

Installation von Tomcat
Installieren Sie Tomcat in ein Verzeichnis, das keine Leerzeichen im Pfadnamen enthält. Das Wurzelverzeichnis der Tomcat-Installation wird im weiteren Verlauf als $CATALINA_HOME bezeichnet. Hinweis: Tomcat wird in einer Distribution für JDKs ab Version 1.2 und in einer Distribution speziell für JDK 1.4 ausgeliefert. Installieren Sie die zur Version Ihres JDK passende Tomcat-Version.

Entpacken des MOA SP/SS Webservices
Entpacken Sie die Datei moa-spss-1.0.x.zip in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als $MOA_SPSS_INST bezeichnet.

Installation der IAIK JCE und JSSE im JDK 1.3.1
Da Java in der Version 1.3.1 ohne Unterstützung für Kryptographie und SSL ausgeliefert wird, muss dies manuell nachträglich installiert werden. Für den Betrieb des MOA SP/SS Webservices ist es deshalb notwendig, die Dateien aus dem Verzeichnis $MOA_SPSS_INST/ext13 in das Verzeichnis $JAVA_HOME/jre/lib/ext zu kopieren.

Installation der IAIK JCE im JDK 1.4.1
Um die mit MOA SP/SS ausgelieferte IAIK JCE im JDK 1.4.1 zu installieren, müssen die Dateien aus dem Verzeichnis $MOA_SPSS_INST/ext14 in das Verzeichnis $JAVA_HOME/jre/lib/ext kopiert werden. Zusätzlich müssen die sogenannten "Unlimited Strength Jurisdiction Policy Files 1.4.1" heruntergeladen, entpackt und ins Verzeichnis $JAVA_HOME/jre/lib/security kopiert werden. Der Download für diese Dateien findet sich am unteren Ende der Download-Seite für das JDK 1.4.1 in der Sektion "Other Downloads".

 

Konfiguration von Tomcat

Minimale Konfiguration
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. Die Datei $MOA_SPSS_INST/tomcat/server.xml enthält eine minimale Tomcat-Konfiguration, die ausschließlich den Connector für HTTP freischaltet. Durch kopieren dieser Datei nach $CATALINA_HOME/conf/server.xml kann Tomcat mit dieser Konfiguration gestartet werden.

SSL
Ein sicherer Betrieb des MOA SP/SS Webservices setzt voraus, dass für die Übertragung der Daten SSL verwendet wird. Das Dokument Tomcat SSL Configuration HOW-TO gibt einen guten Überblick über die Konfiguration von SSL in Tomcat. Da das JDK bereits im Abschnitt "Vorbereitung" auf SSL vorbereitet wurde, sind an dieser Stelle nur noch folgende Schritte notwendig:
  • Erstellung eines Server-Keystores, welches den privaten Schlüssel des Servers sowie das Server-Zertifikat enthält, z.B. mit dem Java Keytool.
  • Erstellung eines Keystores mit vertrauenswürdigen Client-Zertifikaten, z.B. mit dem Java Keytool (nur, wenn SSL Client-Authentisierung verwendet werden soll)
  • Konfiguration des SSL-Connectors in $CATALINA_HOME/conf/server.xml (optional mit Client-Authentisierung)
Die Konfiguration von SSL im Tomcat kann entfallen, wenn Tomcat ein Webserver vorgeschaltet ist, der die SSL-Kommunikation mit dem Aufrufer des Webservices übernimmt.


MOA Administrator
Der Aufruf der URL für die dynamische Konfiguration des MOA SP/SS Webservices ist durch eine Passwort-Abfrage geschützt, und kann nur von Benutzern aufgerufen werden, die der Benutzer-Rolle moa-admin zugeordnet werden können.
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" password="moa" roles="moa-admin"/>

 

Deployment des MOA SP/SS Webservices in Tomcat

Um das MOA SP/SS Webservice in Tomcat für den Ablauf 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 Verzeichnis $CATALINA_HOME/webapps kopiert werden. Dort wird sie beim ersten Start von Tomcat automatisch ins Verzeichnis $CATALINA_HOME/webapps/ moa-spss entpackt.
  • Die MOA SP/SS Konfigurationsdatei und zugehörige Profil-Verzeichnisse müssen in ein beliebiges Verzeichnis im Filesystem kopiert werden (z.B. $CATALINA_HOME/ conf/moa).
    In $MOA_SPSS_INST/conf befindet sich eine funktionsfähige Konfiguration, die als Ausgangspunkt für die Konfiguration des MOA SP/SS Webservices dienen kann.
  • Wird Tomcat unter JDK 1.3.1 betrieben, müssen die Dateien aus dem Verzeichnis $MOA_SPSS_INST/endorsed13 in das Tomcat-Verzeichnis $CATALINA_HOME/common/endorsed kopiert werden. Folgende Libraries sind für das Deployment im endorsed Verzeichnis vorgesehen:
    • Xerces-J-2.0.2 (bestehend aus xercesImpl.jar und xmlParserAPIs.jar).
    Eventuell vorhandene Dateien mit dem gleichen Namen müssen ersetzt werden.
  • Wird Tomcat unter JDK 1.4.1 betrieben, müssen die Dateien aus dem Verzeichnis $MOA_SPSS_INST/endorsed14 in das Tomcat-Verzeichnis $CATALINA_HOME/common/endorsed kopiert werden. Folgende Libraries sind für das Deployment im endorsed Verzeichnis vorgesehen:
    • Xerces-J-2.0.2 (bestehend aus xercesImpl.jar und xmlParserAPIs.jar).
    • Xalan-J-2.2.0 (bestehend aus xalan.jar.jar und bsf.jar).
    Eventuell vorhandene Dateien mit dem gleichen Namen müssen ersetzt werden.
  • Folgende Java System-Properties können optional gesetzt sein:
    • moa.spss.server.configuration=Name der MOA SP/SS Konfigurationsdatei. Eine beispielhafte MOA SP/SS Konfiguration ist in $MOA_SPSS_INST/conf/moa-spss/ MOA-SPSSConfiguration.xml enthalten. Ist diese System-Property nicht gesetzt, wird automatisch eine im Web-Archive unter WEB-INF/conf enthaltene Default-Konfiguration herangezogen.
    • log4j.configuration=URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration ist in $MOA_SPSS_INST/conf/moa-spss/log4j.properties enthalten. Ist diese System-Property nicht gesetzt, wird automatisch eine im Web-Archive unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen.
    • moa.node.id=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. Der Name des Knotens ist frei wählbar.
    • javax.net.ssl.trustStore=Dateiname des Truststores für vertrauenswürdige SSL Client-Zertifikate (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Relative Dateinamen werden zum Verzeichnis, von dem Tomcat gestartet wird, aufgelöst.
    • 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 ist "jks" oder "pkcs12" üblich.
    Diese Java System-Properties werden Tomcat über die Umgebungsvariable CATALINA_OPTS mitgeteilt. Die Dateien $MOA_SPSS_INST/tomcat/moa-env.bat und
    $MOA_SPSS_INST/tomcat/moa-env.sh enthalten Beispiele zum Setzen dieser Umgebungsvariablen unter Windows bzw. Unix/Linux.

 

Starten und Stoppen von Tomcat

Nach dem Deployment und der Konfiguration kann Tomcat aus seinem Wurzelverzeichnis mit 
    bin\catalina start (unter Windows) oder 
    bin/catalina.sh start (unter Unix/Linux)
gestartet werden. Das Stoppen von Tomcat erfolgt analog mit 
    bin\catalina stop  (unter Windows) oder 
    bin/catalina.sh stop (unter Unix/Linux)
Ein erfolgreicher Startvorgang 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 kann einfach überprüft werden, indem der Endpunkt mit einem Web-Browser aufgerufen wird und zu einer Anzeige einer Informationsseite führt.

Dynamische Konfigurations-Updates können durch den Aufruf der URL http://host:port/moa-spss/ConfigurationUpdate (z.B. durch Eingabe in einem Browser) durchgeführt werden.
Konnte das MOA-SPSS Webservice nicht ordnungsgemäß konfiguriert und gestartet werden, geht das aus der Log-Meldung hervor: 
    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.

 

Logging

Das MOA SP/SS Webservice verwendet Jakarta Log4j für die Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. Log4j bietet zahlreiche Konfigurationsmöglichkeiten, die ausführlich im Log4j 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-SPSS 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 IAIK Kryptographie-Modulen
Als Ausgangspunkt für die Logging-Konfiguration liegt die Datei $MOA_SPSS_INST/conf/moa-spss/log4j.properties bei. 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.

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., dass eine neue Anfrage eingelangt ist.
  • WARN: Bei der Ausführung einer Operation sind leichte Fehler aufgetreten. Der Ablauf des Webservices ist nicht weiter beeinträchtigt.
  • ERROR: Die Ausführung einer Operation 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, an 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 Tomcat Worker-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).
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.

Wichtige Log-Meldungen
Neben den im Abschnitt "Starten und Stoppen von Tomcat" 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 3. 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.



© 2003