Open Source
für das E-Government
|
Open Source
für das E-Government |
MOA: Serversignatur (SS) und Signaturprüfung (SP), V 1.2
Installation
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.
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.
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:
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.
Die folgenden Schritte dienen der Vorbereitung der Installation.
$JAVA_HOME bezeichnet. $CATALINA_HOME bezeichnet.moa-spss-1.2.x.zip in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als $MOA_SPSS_INST bezeichnet. Die Installation der mitgelieferten Kryptographiebibliotheken des IAIK ist abhängig vom eingesetzten J2SE SDK:
$MOA_SPSS_INST/ext13 in das Verzeichnis $JAVA_HOME/jre/lib/ext.$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. 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 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.
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:
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:
keytool erstellen, einem Programm, das Ihrem J2SE SDK beiliegt.keytool erstellt werden. Dieser Keystore ist optional und braucht nur erstellt zu werden, wenn sich die Kunden gegenüber dem Webservice authentisieren müssen. $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).
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.
Um das MOA SP/SS Webservice in Tomcat für den Einsatz vorzubereiten, sind folgende Schritte notwendig:
$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. $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. 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.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.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 des eingesetzten J2SE SDK) 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.
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 startgestartet werden. Das Stoppen von Tomcat erfolgt analog mit
bin/catalina.sh stop
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>In diesem Fall geben die
MSG=Fehler beim Lesen der MOA Konfiguration: das Service steht nicht zur Verfügung
WARN bzw. ERROR Log-Meldungen unmittelbar davor Aufschluss über den genaueren Grund.
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).
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 Jakarta 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 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 IAIK Kryptographie-Modulen.
Eine für MOA SP/SS passende Konfigurationsdatei für Log4j 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.
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.
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.
Ausgehend von der Basisinstallation können die optionalen Erweiterungen, die in den nachfolgenden Abschnitten beschrieben werden, unabhängig und in beliebiger Kombination aufgesetzt werden.
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.
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:
Die MOA SP/SS Klassenbibliothek verwendet Log4j als Logging Toolkit.
Auf folgende Software-Pakete wird in diesem Handbuch verwiesen:
| Name | Beschreibung |
|---|---|
| Apache Tomcat 4.1.x | Servlet-Container des Apache Jakarta Projekts in der Version 4.1.x |
| J2SE 1.3.1 SDK/JRE | Java 2 Standard Edition in der Version 1.3.1 (Software Development Kit bzw. Java Runtime Environment) |
| J2SE 1.4.2 SDK/JRE | Java 2 Standard Edition in der Version 1.4.2 (Software Development Kit bzw. Java Runtime Environment) |
| J2SE 5.0 SDK/JRE | Java 2 Standard Edition in der Version 5.0 (Software Development Kit bzw. Java Runtime Environment) |
| Jakarta Log4J | Logging Framework des Apache Jakarta Projekts |