<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> <title>MOA SL - Betriebshandbuch</title> <link rel="stylesheet" href="../common/MOA.css" type="text/css"> </head> <body style="color: rgb(0, 0, 0); background-color: white;" alink="#cc9966" link="#990000" vlink="#666666"> <table class="logoTable" border="0" cellpadding="10" cellspacing="0" width="100%"> <tbody> <tr> <td class="logoTitle" align="center" width="267"><img src="../common/LogoBKA.png" alt="Logo BKA" align="left" height="37" width="267"></td> <td class="logoTitle" align="center">Open Source<br> für das E-Government</td> <td class="logoTitle" align="center" width="123"><img src="../common/LogoMoa4c.jpg" alt="Logo MOA" align="right" height="138" width="123"></td> </tr> </tbody> </table> <hr> <p class="title"><a href="../index.html">MOA: Serverseitige Signaturprüfung (SL), V 1.1</a></p> <p class="subtitle">Betriebshandbuch</p> <hr> <h1>Inhalt</h1> <ol> <li> <p><a href="#%FCbersicht">Übersicht</a></p> </li> <li><a href="#installation">Installation</a> <ol> <li><a href="#installation_einf%FChrung">Einführung</a></li> <li><a href="#installation_vorbereitung">Vorbereitung</a></li> <li><a href="#installation_tomcatconfig">Konfiguration von Apache Tomcat</a> <ol> <li><a href="#installation_tomcatconfig_httpconn">Konfiguration des HTTP Connectors</a></li> <li><a href="#installation_tomcatconfig_httpsconn">Konfiguration des HTTPS Connectors</a></li> </ol> </li> <li><a href="#installation_deploy">Einsatz des MOA SL Webservices in Tomcat</a></li> <li><a href="#installation_tomcatstartstop">Starten und Stoppen von Tomcat</a> <ol> <li><a href="#installation_tomcatstartstop_windows">Unter Windows</a></li> <li><a href="#installation_tomcatstartstop_unix">Unter Unix</a></li> <li><a href="#installation_tomcatstartstop_logging">Logging</a> <ol> <li><a href="#webservice_basisinstallation_logging_format">Format der Log-Meldungen</a> </li> </ol> </li> <li><a href="#installation_tomcatstartstop_verify">Prüfen des erfolgreichen Starts</a></li> </ol> </li> </ol> </li> <li><a href="#konfiguration">Konfiguration</a> <ol> <li><a href="#konfiguration_konfigurationsdatei">Zentrale Konfigurationsdatei</a> <ol> <li><a href="#konfiguration_konfigurationsdatei_schemata">XML-Schemata für Request- und Response-Validierung</a></li> <li><a href="#konfiguration_konfigurationsdatei_arbeitsverzeichnis">Arbeitsverzeichnis</a></li> <li><a href="#konfiguration_konfigurationsdatei_moasp">Parameter der verwendeten MOA SP Installation</a></li> <li><a href="#konfiguration_konfigurationsdatei_umfang">Umfang der Prüfberichtseite</a></li> <li><a href="#konfiguration_konfigurationsdatei_umschreiben">Parameter für das Umschreiben der Links in der Prüfberichtseite</a></li> </ol> </li> <li><a href="#konfiguration_layout">Layout des Prüfberichts</a> </li> </ol> </li> <li><a href="#testapp">Durchlaufen der Testapplikation</a> </li> </ol> <hr> <h1><a name="übersicht" id="übersicht"></a>1 Übersicht</h1> <p> Das Modul<span class="term"> Serverseitige Signaturprüfung</span> (MOA SL) ist als plattformunabhängiges Modul ausgelegt, das als Webservice über HTTP bzw. HTTPS angesprochen werden kann. </p> <p>Dieses Handbuch beschreibt einerseits die Installation des Moduls, andererseits werden die Konfigurationsmöglichkeiten dargestellt. Für eine funktionale Beschreibung des Moduls siehe <a href="../system/system.html">Systemhandbuch</a>. </p> <h1><a name="installation" id="installation"></a>2 Installation</h1> <h2><a name="installation_einführung" id="installation_einführung"></a>2.1 Einführung </h2> <p>Das MOA SL Webservice wurde plattformunabhänig konzipiert und in Java entwickelt. Es benötigt als Ablaufumgebung eine Java 2 Standard Edition (J2SE SDK, Version <a href="http://java.sun.com/j2se/1.4.2/">1.4.2</a> oder <a href="http://java.sun.com/j2se/1.5.0/">5.0</a>) sowie einen Java Servlet Container, der die <a href="http://java.sun.com/products/servlet/reference/api/index.html">Java Servlet Specification</a> in der Version 2.3 erfüllt.</p> <p>In diesem Betriebshandbuch wird davon ausgegangen, dass MOA SL <a href="http://jakarta.apache.org/tomcat/index.html">Apache Tomcat</a> (Version 4.1 oder höher) als Servlet Container verwendet. Die Verwendung eines anderen Servlet Containers ist grundsätzlich möglich, wurde aber nicht getestet und ist auch nicht Gegenstand dieses Betriebshandbuchs. </p> <p>Weiters wird davon ausgegangen, dass Apache Tomcat gleichzeitig als HTTP- bzw. HTTPS-Endpunkt für das MOA SL Webservice dient, d.h. beide Protokolle werden direkt in Tomcat konfiguriert. Die Verwendung eines vor Apache Tomcat geschalteten Webservers ist grundsätzlich möglich. So werden etwa als Teil des Apache Tomcat Projekts <a href="http://tomcat.apache.org/connectors-doc/">Module</a> zur Verbindung mit einem vorgeschalteten Microsoft Internet Information Server oder mit einem vorgeschalteten Apache Webserver angeboten. Die Beschreibung der möglichen Vorschaltungen ist jedoch nicht Teil dieses Betriebshandbuchs. </p> <p>Das MOA SL Webservice nimmt Signaturprüfungsrequests für XML-Signaturen entsprechend der Spezifikation des Security-Layers zur österreichischen Bürgerkarte in den Versionen 1.1 und 1.2 entgegen. Für die Durchführung der Signaturprüfung bedient sich MOA SL des Moduls MOA Signaturprüfung (SP). Für den Betrieb von MOA SL ist daher die Verfügbarkeit einer Webservice-Installation von MOA SP in der Version 1.2 oder höher Voraussetzung. </p> <p>Als Logging Toolkit verwendet das MOA SL Webservice <a href="http://logging.apache.org/log4j/">Apache Log4j</a>. </p> <h2><a name="installation_vorbereitung" id="installation_vorbereitung"></a>2.2 Vorbereitung</h2> <p>Die folgenden Schritte dienen der Vorbereitung der Installation.</p> <dl> <dt>Installation von J2SE SDK</dt> <dd>Installieren Sie <a href="http://java.sun.com/j2se/1.4.2/">J2SE 1.4.2 SDK</a> oder <a href="http://java.sun.com/j2se/1.5.0/">J2SE 5.0 SDK</a> in ein beliebiges Verzeichnis. Das Wurzelverzeichnis der J2SE SDK Installation wird im weiteren Verlauf als <code>$JAVA_HOME</code> bezeichnet. </dd> <dt>Installation von Apache Tomcat</dt> <dd> Installieren Sie <a href="http://jakarta.apache.org/tomcat/index.html">Apache Tomcat</a> 4.1.31 oder höher in ein Verzeichnis, das keine Leerzeichen im Pfadnamen enthält. Verwenden Sie bitte die zu Ihrem J2SE SDK passende Distribution von Tomcat. Das Wurzelverzeichnis der Tomcat-Installation wird im weiteren Verlauf als <code>$CATALINA_HOME</code> bezeichnet.</dd> <dt>Installation von MOA SP </dt> <dd>Installieren Sie das <a href="http://www.cio.gv.at/onlineservices/basicmodules/moa-spss/">Kombinationsmodul MOA SPSS</a> Version 1.3 oder höher entsprechend seiner Installationsanleitung. Sie benötigen die Webservice-Schnittstelle von MOA SP. Es ist ausreichend, mittels entsprechender Konfigurationseinstellungen ausschließlich MOA SP zu aktivieren; MOA SS kann deaktiviert bleiben. Wenn Sie sowohl für MOA SPSS als auch für MOA SL Apache Tomcat als Servlet Container verwenden möchten, empfehlen wir, MOA SPSS und MOA SL in jeweils eigenständigen Instanzen von Apache Tomcat zu betreiben. </dd> <dt>Entpacken der MOA SL Distribution</dt> <dd> Entpacken Sie die Datei <code>moa-sl-1.1.x.zip</code> in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als <code>$MOA_SL_INST</code> bezeichnet. </dd> </dl> <h2><a name="installation_tomcatconfig" id="installation_tomcatconfig"></a>2.3 Konfiguration von Apache Tomcat</h2> <p> Die zentrale Konfigurations-Datei von Tomcat ist <code>$CATALINA_HOME/conf/server.xml</code>. Tomcat wird grundsätzlich mit einer funktionierenden Default-Konfiguration ausgeliefert, die jedoch einiges an Ballast enthält und viele Ports offen lässt. </p> <h3><a name="installation_tomcatconfig_httpconn" id="installation_tomcatconfig_httpconn"></a>2.3.1 Konfiguration des HTTP Connectors</h3> <p> Die Datei <code>$MOA_SL_INST/conf/tomcat/server.xml</code> enthält eine minimale Tomcat-Konfiguration, die ausschließlich den Connector für HTTP auf Port 8080 freischaltet. Durch kopieren dieser Datei nach <code>$CATALINA_HOME/conf/server.xml</code> kann Tomcat mit dieser Konfiguration gestartet werden. Wir empfehlen diese Konfiguration nur für Fälle, in denen das MOA SL Webservice in einer abgeschlossenen Netzwerkumgebung betrieben wird. </p> <h3><a name="installation_tomcatconfig_httpsconn" id="installation_tomcatconfig_httpsconn"></a>2.3.2 Konfiguration des HTTPS Connectors</h3> <p>Wird das MOA SL Webservice in einer nicht abgeschlossenen Umgebung (z.B. Erreichbarkeit über das Internet) betrieben, ist es für den Benutzer von MOA SL essentiell, die Identität des Webservice eindeutig feststellen zu können, denn er vertraut dem Webservice ja die Prüfung einer elektronischen Signatur an. Diese Identitätsprüfung kann mit hoher Qualität vorgenommen werden, wenn die Erreichbarkeit des Webservice auf HTTPS mit Serverauthentisierung eingeschränkt wird. </p> <p>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 <a href="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/ssl-howto.html">Tomcat SSL Configuration HOW-TO </a> gibt einen guten Überblick dazu. Grob zusammengefasst sind folgende Schritte durchzuführen: </p> <ul> <li>Erstellung eines <span class="term">Server-Keystores</span>, 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. Sie können diesen Keystore z.B. mit <code>keytool</code> erstellen, einem Programm, das Ihrem J2SE SDK beiliegt.</li> <li>Erstellung eines <span class="term">Client-Keystores</span>, der die Zertifikate aller Kunden des Webservices enthält. Nur Kunden des MOA SL Webservices, die sich beim Aufbau einer SSL-Verbindung gegenüber dem Webservice mit einem im <span class="term">Client-Keystore</span> enthaltenen Zertifikat ausweisen, erhalten Zugriff zu den Diensten des MOA SL Webservices. Auch dieser Keystore kann z.B. mit <code>keytool</code> erstellt werden. Dieser Keystore ist optional und braucht nur erstellt zu werden, wenn sich die Kunden gegenüber dem MOA SL Webservice authentisieren müssen. </li> <li>Konfiguration des HTTPS Connectors in <code>$CATALINA_HOME/conf/server.xml</code>.</li> </ul> <p>Die Konfiguration des HTTPS Connectors kann entfallen, wenn Tomcat ein Webserver vorgeschaltet ist, und dieser die SSL-Kommunikation mit dem Kunden übernimmt (siehe <a href="#installation_einf%FChrung">Abschnitt 2.1</a>).</p> <h2><a name="installation_deploy" id="installation_deploy"></a>2.4 Einsatz des MOA SL Webservices in Tomcat</h2> <p> Um das MOA SL Webservice in Tomcat für den Einsatz vorzubereiten, sind folgende Schritte notwendig:</p> <ul> <li>Die Datei <code>$MOA_SL_INST/moa-sl.war</code> enthält das einsatzfertige MOA SL Webarchiv und muss ins Verzeichnis <code>$CATALINA_HOME/webapps</code> kopiert werden. Dort wird sie beim ersten Start von Tomcat automatisch ins Verzeichnis <code>$CATALINA_HOME/webapps/moa-sl</code> entpackt. </li> <li>Die zentrale Konfigurationsdatei für MOA SL muss in ein beliebiges Verzeichnis im Dateisystem kopiert werden (z.B. <code>$CATALINA_HOME/conf/moa-sl/</code>). Eine funktionsfähige Konfiguration, die als Ausgangspunkt für die Konfiguration des MOA SL Webservices dienen kann, finden Sie unter <code>$MOA_SL_INST/conf/moa-sl/moa-sl.properties</code>. </li> <li>Die Dateien <code>xalan.jar</code>, <code>xercesImpl.jar</code> und <code>xmlParserAPIs.jar</code> aus dem Verzeichnis <code>$MOA_SL_INST/endorsed14</code> müssen in das Tomcat-Verzeichnis <code>$CATALINA_HOME/common/endorsed</code> kopiert werden. Sind gleichnamige Dateien dort bereits vorhanden, müssen sie überschrieben werden. Die ggf. in diesem Verzeichnis vorhandene Datei <code>xml-apis.jar</code> muss gelöscht werden.</li> <li>Folgende <span class="term">System Properties</span> für die <span class="term">Java Virtual Machine</span> müssen bzw. können gesetzt werden. Am einfachsten können diese <span class="term">System Properties</span> beim Starten von Tomcat in der Umgebungsvariablen <code>CATALINA_OPTS</code> in der Form <code>-D<name>=<wert></code> übergeben werden. <ul> <li id="klein"><code>at.gv.egovernment.moa.spss.slinterface.PropertiesLocation</code>: Pfad und Name der zentralen Konfigurationsdatei für MOA SL. Eine beispielhafte Konfigurationsdatei finden Sie unter <code>$MOA_SL_INST/conf/moa-sl/moa-sl.properties</code>. Wird ein relativer Pfad angegeben, wird zuerst versucht, diesen relativ zum Wurzelverzeichnis der Webapplikation (also <code>$CATALINA_HOME/webapps/moa-sl</code>) zu interpretieren. Klappt das nicht, wird dann versucht, den relativen Pfad relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> zu interpretieren. Diese <span class="term">System Property</span> muss jedenfalls gesetzt werden.</li> <li id="klein"><code>log4j.configuration</code>: URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration finden Sie unter <code>$MOA_SL_INST/conf/log4j/log4j.properties</code>. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter <code>WEB-INF/classes</code> enthaltene Default-Konfiguration herangezogen.</li> <li id="klein"><code>javax.net.ssl.trustStore</code>: Pfad und Dateiname des <span class="term">Truststores</span> für vertrauenswürdige SSL Client-Zertifikate (optional; nur wenn kein Webserver vor Tomcat geschalten wird und SSL Client-Authentisierung durchgeführt werden soll). Ein relativer Pfad werden relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert.</li> <li id="klein"><code>javax.net.ssl.trustStorePassword</code>: Passwort für den <span class="term">Truststore</span> (optional; nur wenn kein Webserver vor Tomcat geschalten wird und SSL Client-Authentisierung durchgeführt werden soll). </li> <li id="klein"><code>javax.net.ssl.trustStoreType</code>: Truststore-Typ (optional; nur wenn kein Webserver vor Tomcat geschalten wird und SSL Client-Authentisierung durchgeführt werden soll). Je nach verwendetem Keystore-Typ muss <code>jks</code> (<span class="term">Java Key Store</span>) oder <code>pkcs12</code> (PKCS#12-Datei) angegeben werden.</li> </ul> </li> </ul> <h2><a name="installation_tomcatstartstop" id="installation_tomcatstartstop"></a>2.5 Starten und Stoppen von Tomcat</h2> <h3><a name="installation_tomcatstartstop_windows" id="installation_tomcatstartstop_windows"></a>2.5.1 Unter Windows</h3> <p>Das Verzeichnis <code>$MOA_SL_INST/conf/tomcat/win32</code> enthält Script-Dateien zum Starten und Stoppen von Tomcat. Vor der erstmaligen Verwendung der Scripts müssen in den ersten Zeilen die Umgebungsvariablen <code>JAVA_HOME</code> (Basisverzeichnis des eingesetzten J2SE SDK) und <code>CATALINA_HOME</code> (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden. Evtl. müssen Sie auch noch die in den Script-Dateien gesetzten, in <a href="#installation_deploy">Abschnitt 2.4</a> besprochenen <span class="term">System Properties</span> anpassen. </p> <h3><a name="installation_tomcatstartstop_unix" id="installation_tomcatstartstop_unix"></a>2.5.2 Unter Unix</h3> <p>Zunächst müssen die in <a href="#installation_deploy">Abschnitt 2.4</a> besprochenen <span class="term">System Properties</span> mit Hilfe der Umgebungsvariablen <code>CATALINA_OPTS</code> gesetzt werden. Die Datei <code>$MOA_SL_INST/tomcat/unix/moa-env.sh</code> enthält ein Beispiel dafür. Weiters müssen noch die Umgebungsvariablen <code>JAVA_HOME</code> (Basisverzeichnis des eingesetzten J2SE SDK) und <code>CATALINA_HOME</code> (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden.</p> <p>Nun kann Tomcat aus seinem Basisverzeichnis mit </p> <pre>bin/catalina.sh start</pre> gestartet werden. Das Stoppen von Tomcat erfolgt analog mit <pre>bin/catalina.sh stop</pre> <h3><a name="installation_tomcatstartstop_logging" id="installation_tomcatstartstop_logging"></a>2.5.3 Logging </h3> <p>Das MOA SL Webservice verwendet <a href="http://logging.apache.org/log4j/">Apache Log4j</a> für die Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. Log4j bietet zahlreiche Konfigurationsmöglichkeiten, die ausführlich im <a href="http://logging.apache.org/log4j/">Apache Log4j</a> Handbuch beschrieben sind. Unter anderem gibt es die Möglichkeit, folgende Einstellungen vorzunehmen: </p> <ul> <li id="klein"> <p>Das verwendete Log-Level (<code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, <code>FATAL</code>);</p> </li> <li id="klein"> <p>Name und maximale Größe der Log-Datei(en);</p> </li> <li id="klein"> <p>Das Aussehen der Log-Einträge.</p> </li> </ul> <p>Das MOA SL Webservice verwendet für alle Logeinträge die Log-Hierarchie <code>slinterface</code>. Für die einzelnen Pakete des MOA SL Webservices werden davon abgeleitete Sub-Hierarchien eingesetzt, z.B. <code>slinterface.xmlparser</code>, <code>slinterface.beans</code> oder <code>slinterface.filters</code>.</p> <p>Eine für MOA SL passende Konfigurationsdatei für Log4j finden Sie unter <code>$MOA_SL_INST/conf/log4j/log4j.properties</code>. Wird diese Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen sowohl in die Konsole, als auch in die Datei <code>$CATALINA_HOME/logs/moa-sl.log</code> geschrieben. </p> <h4><a name="webservice_basisinstallation_logging_format" id="webservice_basisinstallation_logging_format"></a>2.5.3.1 Format der Log-Meldungen</h4> <p> Anhand einer konkreten Log-Meldung wird das Format der MOA SL Log-Meldungen erläutert: </p> <pre>INFO | 10 15:58:45,531 | slinterface.listeners | main | <br> Web application initialization succeeded..</pre> <p> Der Wert <code>INFO</code> besagt, dass die Log-Meldung im Log-Level <code>INFO</code> entstanden ist. Folgende Log-Levels existieren:</p> <ul> <li> <p><code>DEBUG</code>: Log-Meldungen im Log-Level <code>DEBUG</code> geben Auskunft über die innere Arbeitsweise des Systems. Sie sind hauptsächlich für Entwickler interessant.</p> </li> <li> <p><code>INFO</code>: Diese Log-Meldungen geben Status-Informationen über den Ablauf des Webservices, wie z.B. über das Einlangen einer neuen Anfrage.</p> </li> <li> <p><code>WARN</code>: Bei der Ausführung einer Anfrage sind leichte Fehler aufgetreten. Der Ablauf des Webservices ist nicht weiter beeinträchtigt.</p> </li> <li> <p><code>ERROR</code>: Die Ausführung einer Anfrage musste abgebrochen werden. Das Webservice ist davon nicht beeinträchtigt. </p> </li> <li> <p><code>FATAL</code>: Es ist ein Fehler aufgetreten, der den weiteren Betrieb des Webservices nicht mehr erlaubt.</p> </li> </ul> <p>Der nächste Wert <code>10 15:58:45,531</code> gibt den Zeitpunkt an, zu dem die Log-Meldung generiert wurde (in diesem Fall den 10. Tag im aktuellen Monat, sowie die genaue Uhrzeit). </p> <p>Der Wert <code>slinterface.listeners</code> gibt die Log-Hierarchie an, aus der die Log-Meldung stammt. </p> <p>Der Wert <code>main</code> bezeichnet den Thread, aus der die Log-Meldung stammt. </p> <p>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.</p> <h3><a name="installation_tomcatstartstop_verify" id="installation_tomcatstartstop_verify"></a>2.5.4 Prüfen des erfolgreichen Starts </h3> <p>Ein erfolgreicher Start des MOA SL Webservices ist an folgender Log-Meldung ersichtlich: </p> <pre>INFO | 10 15:58:45,531 | slinterface.listeners | main | <br> Web application initialization succeeded..</pre> <p>Konnte das MOA SL Webservice nicht ordnungsgemäß gestartet werden, führt das zu folgender Log-Meldung:</p> <pre>FATAL | 18 10:17:03,475 | main | TID=startup NID=<null> <br> Web application initialization failed.<br></pre> <p>In diesem Fall geben die<code> </code>Log-Meldungen unmittelbar davor Aufschluss über den genaueren Grund. </p> <p>Fehlermeldungen während der Initialisierung des XML-Parsers, die wie nachfolgend dargestellt aussehen, können ignoriert werden. Sie resultieren aus einem Bug im eingesetzten XML-Parser Apache Xerces in der Version 2.6.2. </p> <pre>[Error] xhtml-attribs-1.xsd:<em>xx</em>:<em>xx</em>: src-attribute_group.3: <br> Circular definitions detected for attribute group '<em>xxx</em>'. <br> Recursively following attribute group references eventually leads back to itself.<br>[Error] xhtml-attribs-1.xsd:<em>xx</em>:<em>xx</em>: src-redefine.7.2.1: <br> No attributeGroup in the redefined schema has a name matching '<em>xx</em>'.</pre> <h1><a name="konfiguration" id="konfiguration"></a>3 Konfiguration</h1> <h2><a name="konfiguration_konfigurationsdatei" id="konfiguration_konfigurationsdatei"></a>3.1 Zentrale Konfigurationsdatei</h2> <p>Alle Konfigurationsparameter von MOA SL mit Ausnahme des Layouts für den Prüfbericht (siehe Abschnitt <a href="#konfiguration_layout">3.2</a>) sind in einer zentralen Konfigurationsdatei zusammengefasst. Eine beispielhafte Konfigurationsdatei finden Sie unter <code>$MOA_SL_INST/conf/moa-sl/moa-sl.properties</code>. Für Hinweise, wie Sie dem MOA SL Webservice mitteilen, welche Konfigurationsdatei es verwenden soll, siehe Abschnitt <a href="#installation_deploy">2.4</a>. </p> <p>In den folgenden Abschnitten werden die einzelnen Konfigurationsparameter der zentralen Konfigurationsdatei im Detail besprochen. Die meisten Konfigurationsparameter werden leichter verständlich, wenn Sie zunächst<span style="font-style: italic;"> </span>das <a href="../system/system.html">Systemhandbuch<span class="comment"></span></a> lesen. Dort werden der gesamte Ablauf eines Signaturprüfvorgangs in MOA SL sowie die daran beteiligten Komponenten erklärt. </p> <p>Die Konfigurationsdatei ist als <span class="term">Java Properties</span> Datei aufgebaut, d. h. jede Zeile enthält den Namen sowie den Wert des jeweiligen Konfigurationsparameters in der Form <code>name=wert</code>. Details zum Aufbau einer <span class="term">Java Properties</span> Datei finden Sie in der API-Dokumentation zu Ihrem Java JDK, beispielsweise <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html">hier</a>. </p> <h3><a name="konfiguration_konfigurationsdatei_schemata" id="konfiguration_konfigurationsdatei_schemata"></a>3.1.1 XML-Schemata für Request- und Response-Validierung</h3> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>location.schema.sl</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Mit diesem Konfigurationsparameter wird MOA SL mitgeteilt, wo es das XML-Schema für die Validierung eines eingehenden Signaturprüfungsrequests nach Security-Layer V1.2 findet. </p> <p>Der Konfigurationsparameter muss als Wert einen Pfad enthalten, der mit <code>/</code> beginnt, und der von MOA SL als relativ zum <span class="term">Context Root</span> der Webapplikation interpretiert wird.</p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>/WEB-INF/classes/resources/schemas/Core.20031231.xsd</code></p> </td> </tr> </tbody> </table> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>location.schema.moa</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Mit diesem Konfigurationsparameter wird MOA SL mitgeteilt, wo es das XML-Schema für die Validierung eines von MOA SP empfangenen Signaturprüfungsresponses nach MOA SPSS V1.3 findet. </p> <p>Der Konfigurationsparameter muss als Wert einen Pfad enthalten, der mit <code>/</code> beginnt, und der von MOA SL als relativ zum <span class="term">Context Root</span> der Webapplikation interpretiert wird.</p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>/WEB-INF/classes/resources/schemas/MOA-SPSS-1.3.xsd</code></p> </td> </tr> </tbody> </table> <h3><a name="konfiguration_konfigurationsdatei_arbeitsverzeichnis" id="konfiguration_konfigurationsdatei_arbeitsverzeichnis"></a>3.1.2 Arbeitsverzeichnis</h3> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>location.tempdir</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Mit diesem Konfigurationsparameter wird MOA SL mitgeteilt, wo es das Arbeitsverzeichnis zum Ablegen der von einer geprüften Signatur abgesicherten Dokumente findet. Diese Dokumente werden temporär gespeichert, damit sie vom Benutzer über den Prüfbericht abgerufen werden können. </p> <p>Der Konfigurationsparameter muss als Wert einen Pfad enthalten, der von MOA SL als relativ zum <span class="term">Context Root</span> der Webapplikation interpretiert wird. Der angegebene Pfad muss einen abschließenden <code>/</code> aufweisen und im Dateisystem tatsächlich existieren. </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>/workdir/temp/</code></p> </td> </tr> </tbody> </table> <h3><a name="konfiguration_konfigurationsdatei_moasp" id="konfiguration_konfigurationsdatei_moasp"></a>3.1.3 Parameter der verwendeten MOA SP Installation</h3> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>service.sp.endpoint</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Mit diesem Konfigurationsparameter wird MOA SL der Zugangspunkt zum Webservice von MOA SP mitgeteilt. </p> <p>Der Konfigurationsparameter muss eine URL enthalten, die von MOA SL aus erreichbar ist und den Zugangspunkt zu MOA SP adressiert. </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>http://localhost:8080/moa-spss/services/SignatureVerification</code></p> </td> </tr> </tbody> </table> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>service.sp.trustProfileId</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Mit diesem Konfigurationsparameter wird MOA SL mitgeteilt, welches Vertrauensprofil es im Signaturprüfrequest an MOA SP verwenden soll. </p> <p>Der Konfigurationsparameter muss den Bezeichner eines in MOA SP hinterlegten Vertrauensprofils enthalten.</p> <p class="remark">Hinweis: Zum Durchlaufen der Testapplikation nach Abschnitt <a href="#testapp">4</a> dieses Handbuchs müssen Sie in MOA SP ein Vertrauensprofil mit dem Namen <code>MOA-SL-Test</code> einrichten. Unter <code>$MOA_SL_INST/conf/moa-spss/trustprofiles/spssconfig.fragment </code>finden Sie das dazu notwendige XML-Fragment zum Einfügen in die Konfigurationsdatei von MOA SP. Unter <code>$MOA_SL_INST/conf/moa-spss/trustprofiles/moa-sl/test/</code> finden Sie das im XML-Fragment referenzierte Verzeichnis mit den für das Vertrauensprofil notwendigen Zertifikatsdateien. </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>MOA-SL-Test</code></p> </td> </tr> </tbody> </table> <h3><a name="konfiguration_konfigurationsdatei_umfang" id="konfiguration_konfigurationsdatei_umfang"></a>3.1.4 Umfang der Prüfberichtseite</h3> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>result.showetsi</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Dieser Konfigurationsparameter gibt an, ob MOA SL auf der Prüfberichtseite unter den signierten Dokumenten auch eventuell vorhandenene, mitsignierte Signatureigenschaften (z.B. das Signaturdatum) auflisten soll. Signatureigenschaften sind in der Regel vorhanden, wenn die zur Prüfung eingereichte Signatur von einer Bürgerkartenumgebung erstellt worden ist.</p> <p>Der Konfigurationsparamter muss einen der Werte <code>true</code> oder <code>false</code> aufweisen. </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>false</code></p> </td> </tr> </tbody> </table> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>result.showslmanifest</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Dieser Konfigurationsparameter gibt an, ob MOA SL auf der Prüfberichtseite unter den signierten Dokumenten auch ein eventuell vorhandenes, mitsigniertes <span class="term"><a href="http://www.buergerkarte.at/konzept/securitylayer/spezifikation/aktuell/core/Core.html#signaturerstellungNachXMLDSIGAntwort">Signaturmanifest</a></span> nach Security-Layer V1.2 auflisten soll. </p> <p>Der Konfigurationsparamter muss einen der Werte <code>true</code> oder <code>false</code> aufweisen. </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>false</code></p> </td> </tr> </tbody> </table> <h3><a name="konfiguration_konfigurationsdatei_umschreiben" id="konfiguration_konfigurationsdatei_umschreiben"></a>3.1.5 Parameter für das Umschreiben der Links in der Prüfberichtseite</h3> <p>Insbesondere zum Verständnis dieses Abschnitts sollten Sie zunächst das <a href="../system/system.html">Systemhandbuch</a> lesen. Dort werden der gesamte Ablauf eines Signaturprüfvorgangs in MOA SL sowie die daran beteiligten Komponenten erklärt. </p> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>rewrite</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Dieser Konfigurationsparameter gibt an, ob MOA SL Links auf der Prüfberichtseite umschreiben soll.</p> <p>der </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>true</code></p> </td> </tr> </tbody> </table> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>rewrite.proxyURL</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Dieser Konfigurationsparameter enthält die URL des <span class="term">Rewrite-Proxy</span>. Der <span class="term">Rewrite-Proxy</span> ist jener Rechner, der (möglicherweise im Gegensatz zum Rechner, auf dem MOA SL läuft) vom Internet aus erreichbar ist, und über den alle Anfragen vom Benutzer an MOA SL geleitet werden. </p> <p>Teil der mit diesem Konfigurationsparameter angegebenen URL ist der Platzhalter für den Domänennamen des <span class="term">Rewrite-Proxy</span>. Wie dieser Platzhalter aussehen muss, wird im Konfigurationsparameter <code>rewrite.proxyURL.proxyhostDummy</code> festgelegt. Im unten angegebenen Beispiel lautet der Platzhalter <code><proxyhost></code>.</p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>http://<rewriteproxyhost>:1234/rewrite</code></p> </td> </tr> </tbody> </table> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>rewrite.proxyURL.proxyhostDummy</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Dieser Konfigurationsparameter enthält das Format für den Platzhalter für den Domänennamen des <span class="term">Rewrite-Proxy</span>. Der Platzhalter im Konfigurationsparameter <code>rewrite.proxyURL</code> muss genau diesem Format entsprechen. </p> <p>Notwendig ist dieser Platzhalter, weil MOA SL bei der Erstellung der Prüfberichtseite alle Vorkommnisse dieses Platzhalters in der Prüfberichtseite durch den Domänennamen jener IP-Adresse ersetzt, von der aus der Signaturprüfrequest an MOA SL gesendet wurde. Die Konfiguration des dazu notwendigen <span class="term">Reverse DNS Lookup</span> geschieht mit dem Konfigurationsparameter <code>rewrite.dn.*</code>. </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code><rewriteproxyhost></code></p> </td> </tr> </tbody> </table> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>rewrite.dn.*</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Dieser (bzw. diese) Konfigurationsparameter definieren die Lookup-Tabelle für das <span class="term">Reverse DNS Lookup</span> im Zuge der Umschreibung von Links in der Prüfberichtseite, damit diese ausschließlich über den <span class="term">Rewrite-Proxy</span> abgerufen werden können. </p> <p>Der Aufbau der Konfigurationsparameter entspricht dabei dem Schema<code> rewrite.dn.<IP-Adresse>=<Domänenname></code>. </p> <p>Der Default-Domänenname, der für die Umschreibung verwendet wird, wenn für die IP-Adresse des <span class="term">Rewrite-Proxy</span> kein Eintrag in der Lookup-Tabelle definiert wurde, wird wie folgt angegeben: <code>rewrite.dn.default=<Domänenname></code>. </p> <p>Das Beispiel geht von zwei möglichen <span class="term">Rewrite-Proxys</span> aus, denen die IP-Adressen <code>192.168.0.101</code> bzw. <code>192.168.0.102</code> zugeordnet sind. Die nach außen sichtbaren Namen dieser <span class="term">Rewrite-Proxys</span> lauten <code>rewriteproxyhost1</code> und <code>rewriteproxyhost2</code>. <code>rewriteproxyhost1</code> ist als Standard-<span class="term">Rewrite-Proxy</span> konfiguriert. </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>rewrite.dn.192.168.0.101=rewriteproxyhost1<br> rewrite.dn.192.168.0.102=rewriteproxyhost2<br> rewrite.dn.default=rewriteproxyhost1</code></p> </td> </tr> </tbody> </table> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>rewrite.MOASLUrlParamName</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Dieser Konfigurationsparameter gibt den Namen des URL-Parameters in den im Signaturprüfbericht für den <span class="term">Rewrite-Proxy</span> umgeschriebenen Links an, dessen Wert die vom <span class="term">Rewrite-Proxy</span> für den tatsächlichen Abruf von Daten von MOA SL enthält.</p> <p>Am Wert dieses Konfigurationsparameters erkennt der <span class="term">Rewrite-Proxy</span>, wie der HTTP-Request an den <span class="term">Rewrite-Proxy</span> in einen HTTP-Request an das MOA SL Webservice umzusetzen ist. Lautet eine im Signaturprüfbericht enthaltene URL z.B. <code>http://rewriteproxyhost1:1234/rewrite?targetURL=http://moaslhost:8080/moa-sl/showdata?hidCount=0</code>, dann geht zunächst ein HTTP-Request an den <span class="term">Rewrite-Proxy </span>(der auf dem Rechner mit dem Namen <code>rewriteproxyhost1 unter Port 1234 lauscht)</code>. Der <span class="term">Rewrite-Proxy</span> entnimmt nun aus dem URL-Parameter <code>targetURL</code> die URL für die Umsetzung an MOA SL, also <code>http://moaslhost:8080/moa-sl/showdata?hidCount=0</code>. Der <span class="term">Rewrite-Proxy</span> setzt nun einen entsprechenden HTTP-Request an MOA SL ab; die Antwort von MOA SL wird als Antwort auf den an den <span class="term">Rewrite-Proxy</span> gerichteten HTTP-Request weitergegeben. </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>targetURL</code></p> </td> </tr> </tbody> </table> <table class="fixedWidth" border="1" cellpadding="2"> <tbody> <tr> <td>Name</td> <td><code>rewrite.MOASLWebAppServUrl</code></td> </tr> <tr> <td>Erläuterung</td> <td> <p>Dieser Konfigurationsparameter gibt jene URL an, unter der der Webapplikationsserver mit MOA SL vom <code>Rewrite-Proxy</code> aus erreichbar ist.</p> <p>Die URL besteht aus Protokoll, Domänennamen sowie gegebenenfalls Port (wenn dieser nicht dem Standardport für das Protokoll entspricht). Nach dem Domänennamen bzw. Port dürfen keine weiteren Bestandteile mehr vorkommen. </p> <p>Verwendung findet dieser Konfigurationsparameter als erster Teil des Werts für den oben besprochenen URL-Parameter (<code>rewrite.sliUrlParamName</code>). </p> </td> </tr> <tr> <td>Beispiel</td> <td> <p><code>http://moaslhost:8080</code></p> </td> </tr> </tbody> </table> <h2><a name="konfiguration_layout" id="konfiguration_layout"></a>3.2 Layout des Prüfberichts </h2> <p>Die einzige Schnittstelle des MOA SL Webservices zum Benutzer ist der Prüfbericht über die eingereichte Signatur, den das Service dem Benutzer in einer für ihn gut aufbereiteten Form darstellt, bevor das automatisch auswertbare Prüfprotokoll an die aufrufende Applikation zurückübermittelt (für eine Erklärung des gesamten Signaturprüfvorgangs in MOA SL sowie der daran beteiligten Komponenten vergleiche das <a href="../system/system.html">Systemhandbuch</a>). </p> <p>Das Layout des Prüfberichts, das in der JSP-Seite <code>$MOA_SL_WEBAPP/pages/resultOverview.jsp</code> (<code>$MOA_SL_WEBAPP</code> steht für den Ort der Webapplikatioin, für gewöhnlich ist das<code> $CATALINA_HOME/webapps</code>) festgelegt ist, kann völlig frei gestaltet werden. </p> <p>Wenn Sie das Layout gegenüber der Vorgabe verändern möchten, editieren Sie einfach die HTML-Teile dieser JSP-Seite. Beachten Sie bitte, dass Sie dabei die JSP-Scriptelemente unverändert lassen. JSP-Scriptelemente sind entweder Tags, die mit dem Präfix <code>jsp</code> gekennzeichnet sind (z.B. <code><jsp:useBean></code> oder <code><jsp:getProperty></code>, oder Bereiche die mit der Kennzeichnung <code><%</code> eingeleitet bzw. mit der Kennzeichnung <code>%></code> ausgeleitet werden. </p> <h1><a name="testapp" id="testapp"></a>4 Durchlaufen der Testapplikation</h1> <p>Konnte das MOA SL Webservice entsprechend Abschnitt <a href="#installation_tomcatstartstop_verify">2.5.4</a> erfolgreich initialisiert werden, und haben Sie weiters die Konfiguration des MOA SL Webservices entsprechend Abschnitt <a href="#konfiguration">3</a> an Ihre Anforderungen angepasst, sollten Sie schließlich prüfen, ob die mit MOA SL mitgelieferte Testapplikation erfolgreich durchlaufen werden kann.</p> <p>Beginnen Sie bitte, in dem Sie einen Webbrowser starten und sich mit folgender Seite verbinden, die Teil des MOA SL Webservices ist. Sollte Ihre Tomcat-Installation unter einer anderen Adresse als <code>localhost:8080</code> erreichbar sein, passen Sie die URL bitte entsprechend an.</p> <pre>http://localhost:8080/moa-sl/pages/test/forms/verify.slxhtml.jsp</pre> <p>Die aufgerufene Webseite sollte in etwa wie folgt aussehen (für eine größere Darstellung bitte klicken):</p> <p style="text-align: center;"><a href="images/testapp.screen1.png" target="_blank"><img src="images/testapp.screen1.png" alt="pplikation - Screen 1" border="0" height="287" width="400"></a></p> <p>Durch Abschicken des dargestellten Formulars wird ein vorbereiteter Signaturprüfungsrequest entsprechend der Spezifikation des Security-Layers an MOA SL übermittelt. Als weiterer Parameter wird eine DataURL ebenfalls ensprechend der Spezifikation des Security-Layers angegeben. Beide Parameter sind auf das installierte MOA SL Webservice abgestimmt und können unverändert übernommen werden. </p> <p>Wenn das Formular an an MOA SL übermittelt wurde, antwortet MOA SL mit dem Signaturprüfbericht, der in etwa wie folgt aussehen sollte:</p> <p style="text-align: center;"><a href="images/testapp.screen2.png" target="_blank"><img src="images/testapp.screen2.png" alt="pplikation - Screen 2" height="458" width="400"></a></p> <p>Sollten Sie an statt des Prüfberichts eine Fehlerseite von Tomcat erhalten, liegt das mit hoher Wahrscheinlichkeit daran, dass das Zusammenspiel von MOA SL mit MOA SPSS nicht korrekt konfiguriert wurde. Prüfen Sie dann Ihre Konfiguration entsprechend den Angaben in Abschnitt <a href="#konfiguration_konfigurationsdatei_moasp">3.1.3</a>.</p> <p>Wenn Sie den Prüfbericht zwar erhalten, der Text zu Prüfungen/Zertifikat jedoch in rot gehalten ist und auf einen Fehler bei der Zertifikatsprüfung hinweist, wurde das für die Testapplikation notwendige Vertrauensprofil in MOA SPSS nicht korrekt konfiguriert. Folgen Sie dann den Hinweisen in Abschnitt <a href="#konfiguration_konfigurationsdatei_moasp">3.1.3</a>.</p> <p>Der Prüfbericht selbst enthält Informationen zum Ersteller der Signatur, zum Aussteller des Zertifikats, über Seriennummer und Qualität des Zertifikats, sowie über die durchgeführten Prüfungen bezüglich der Signatur selbst sowie des verwendeten Zertifikats. Nach diesen Informationen enthält der Prüfbericht eine Liste der von der Signatur gesicherten Dokumente. In unserem Fall erstreckt sich die Signatur über genau ein Dokument. Dieses Dokument kann durch einen Klick auf den entsprechenden Link in einem neuen Fenster geöffnet werden. Das geöffnete Dokument sollte in etwa wie folgt aussehen:</p> <p style="text-align: center;"><a href="images/testapp.screen3.png" target="_blank"><img src="images/testapp.screen3.png" alt="Testapplikation - Screen 3" height="100" width="400"></a> </p> <p>Wenn Sie schließlich im Prüfbericht dem Link <span class="term">Zurück zur Anwendung ...</span> folgen, gelangen Sie zur Abschlussseite der Testapplikation:</p> <p style="text-align: center;"><a href="images/testapp.screen4.png" target="_blank"><img src="images/testapp.screen4.png" alt="Testapplikation - Screen 4" border="0" height="290" width="400"></a></p> <p> Die Abschlussseite präsentiert in Tabellenform die Informationen, die vom MOA SL Webservice als automatisch auswertbare Information entsprechend der Spezifikation des Security-Layers an den <code>DataURL</code>-Server (vergleiche Parameter auf der Startseite der Testapplikation) übermittelt. Im Wesentlichen ist das der Signaturprüfresponse entsprechend der Spezifikation des Security-Layers. </p> </body> </html>