| E-Recht |
E-Recht: -Signaturclient für MOA SS, V0.9
-Betriebshandbuch
-Der E-Recht Signaturclient für MOA SS ist als -plattformunabhängiges Modul ausgelegt, das als Webanwendung -über HTTP angesprochen werden kann.
-Dieses Handbuch beschreibt einerseits die Installation des -Clients, andererseits werden die Konfigurationsmöglichkeiten -dargestellt. Für eine funktionale Beschreibung des Moduls -siehe Systemhandbuch. -
Der E-Recht Signaturclient für MOA SS wurde -plattformunabhänig -konzipiert und in Java entwickelt. Er benötigt als -Ablaufumgebung eine Java 2 Standard Edition (J2SE SDK, Version 1.4.2 oder 5.0) sowie -einen Java Servlet Container, der die Java -Servlet Specification in der Version 2.3 erfüllt. Als -grafische Benutzerschnittstelle für den Anwender dient ein -herkömmlicher Webbrowser.
-In diesem Betriebshandbuch wird davon ausgegangen, dass -der E-Recht Signaturclient für MOA SS -Apache -Tomcat (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.
-Weiters wird davon ausgegangen, dass Apache Tomcat -gleichzeitig als HTTP-Server dient, d.h. die Kommunikation zwischen dem -Webbrowser als grafische Benutzerschnittstelle des Signaturclients und -der Kernanwendung des Signaturclients wird über Tomcat abgewickelt. Die -Verwendung eines vor Apache Tomcat geschalteten -Webservers ist grundsätzlich möglich. So werden etwa -als Teil des Apache Tomcat Projekts Module -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.
Aufgabe -des E-Recht -Signaturclients für MOA SS ist es zunächst, alle Informationen zu -sammeln, die notwendig sind, um ein Rechtsdokument aus E-Recht mit -Hilfe des Moduls MOA SS elektronisch zu signieren. Zu diesen -Informationen zählen die XML-Präsentation des Rechtsdokuments, der -Stylesheet für die Umwandlung der XML-Repräsentation in die -HTML-Repräsentation, -sowie etwaige Bilder und Grafiken, die in der XML- und damit auch -HTML-Repräsentation -referenziert werden. Liegen all diese Informationen vor, steuert der -Signaturclient das Modul MOA SS, um die Signatur über das -Rechtsdokument herzustellen. Die erstellte Signatur kann wird dem -Benutzer abschließend zur lokalen Speicherung zur Verfügung gestellt. -Für den Betrieb des E-Recht Signaturclients ist daher -die Verfügbarkeit einer -Webservice-Installation von MOA SP in der Version 1.3 oder -höher Voraussetzung.
-Als Logging Toolkit verwendet das MOA SL Webservice Apache Log4j. -
-Die folgenden Schritte dienen der Vorbereitung der -Installation.
-$JAVA_HOME
-bezeichnet. $CATALINA_HOME
-bezeichnet.moa-ss-erecht-client-x.y.zip
-in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren
-Verlauf als $MOA_SS_CLIENT_INST bezeichnet. 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_SS_CLIENT_INST/conf/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.
Sicherheitshinweis: Es wird in diesem -Betriebshandbuch davon ausgegangen, dass der E-Recht Signaturclient für -MOA SS sowie das Modul MOA SS selbst miteinander in einer abschlossenen -Umgebung betrieben werden. Der E-Recht Signaturclient für MOA -SS unterstützt derzeit die Anbindung von MOA SS nur über die -ungesicherte HTTP Webservice-Schnittstelle. Weiters bietet der E-Recht -Signaturclient für MOA SS derzeit keine eigenständige -Benutzerauthentisierung.
Um den E-Recht Signaturclient für MOA SS in -Tomcat für den Einsatz -vorzubereiten, sind folgende Schritte notwendig:
-$MOA_SS_CLIENT_INST/moa-ss-erecht-client.war
-enthält das einsatzfertige Webarchiv für den E-Recht Signaturclient für
-MOA SS und muss ins
-Verzeichnis $CATALINA_HOME/webapps kopiert
-werden. Dort wird sie beim ersten Start von Tomcat automatisch ins
-Verzeichnis $CATALINA_HOME/webapps/moa-ss-erecht-client
-entpackt. $CATALINA_HOME/conf/moa-ss-erecht-client/).
-Eine funktionsfähige Konfiguration, die als Ausgangspunkt
-für die Konfiguration des E-Recht Signaturclients für MOA SS
-dienen kann,
-finden Sie unter $MOA_SS_CLIENT_INST/conf/moa-ss-erecht-client.config.properties.
-xalan.jar,
-xercesImpl.jar
-und xml-apis.jar aus dem Verzeichnis $MOA_SS_CLIENT_INST/endorsed14
-müssen in das Tomcat-Verzeichnis $CATALINA_HOME/common/endorsed
-kopiert werden. Sind gleichnamige Dateien dort bereits vorhanden,
-müssen sie überschrieben werden. CATALINA_OPTS
-in der Form -D<name>=<wert>
-übergeben werden. at.gv.egovernment.moa.ss.erechtclient.PropertiesLocation:
-Pfad und Name der zentralen Konfigurationsdatei
-für den E-Recht
-Signaturclient für MOA SS.
-Eine beispielhafte Konfigurationsdatei finden Sie unter $MOA_SS_CLIENT_INST/conf/moa-ss-erecht-client.config.properties.$CATALINA_HOME/webapps/moa-ss-erecht-client)
-zu interpretieren. Klappt das nicht, wird dann versucht, den relativen
-Pfad relativ zum Startverzeichnis der Java
-Virtual Machine zu interpretieren. Diese System Property muss jedenfalls
-gesetzt werden.log4j.configuration:
-URL der Log4j Konfigurationsdatei. Eine beispielhafte
-Log4j-Konfiguration finden Sie unter $MOA_SS_CLIENT_INST/conf/log4j.properties.
-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.Das Verzeichnis $MOA_SL_INST/conf/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.4
-besprochenen System Properties
-anpassen.
Zunächst müssen die in Abschnitt
-2.4
-besprochenen System Properties
-mit Hilfe der Umgebungsvariablen CATALINA_OPTS
-gesetzt werden. Die Datei $MOA_SL_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
Das MOA SL Webservice verwendet Apache Log4j -für die -Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. Log4j -bietet zahlreiche Konfigurationsmöglichkeiten, die -ausführlich im Apache -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.
Der E-Recht Signaturclient für
-MOA SS verwendet für alle
-Logeinträge die Log-Hierarchie erechtclient.
-Für die einzelnen Pakete des E-Recht Signaturclients für MOA
-SS
-werden davon
-abgeleitete Sub-Hierarchien eingesetzt, z.B. erechtclient.xmlparser, erechtclient.init,
-erechtclient.servlets oder erechtclient.moainvoker.
Eine für den E-Recht Signaturclient für MOA
-SS passende Konfigurationsdatei
-für Log4j finden Sie unter $MOA_SS_CLIENT_INST/conf/log4j.properties.
-Wird diese
-Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen
-sowohl in die Konsole, als auch in die Datei $CATALINA_HOME/logs/moa-ss-erecht-client.log
-geschrieben.
Anhand einer konkreten Log-Meldung wird das Format -der -Log-Meldungen erläutert:
-INFO | 28 12:14:48,567 | erechtclient.init | main |
Web application initialization succeeded.
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 28 12:14:48,567
-gibt den Zeitpunkt an, zu dem die Log-Meldung generiert wurde (in
-diesem Fall den 28. Tag im aktuellen Monat, sowie die genaue Uhrzeit).
Der Wert erechtclient.init gibt
-die Log-Hierarchie an, aus der die Log-Meldung stammt.
Der Wert main bezeichnet den Thread,
-aus der die Log-Meldung stammt.
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.
-Ein erfolgreicher Start des E-Recht Signaturclients -für MOA SS ist an -folgender Log-Meldung ersichtlich:
-INFO | 28 12:14:48,567 | erechtclient.init | main |
Web application initialization succeeded.
Konnte -der E-Recht Signaturclient für MOA SS nicht -ordnungsgemäß gestartet werden, führt das -zu folgender Log-Meldung:
-FATAL | 28 10:17:03,475 | main | TID=startup NID=<null>
Web application initialization failed.
In
-diesem Fall geben die Log-Meldungen
-unmittelbar davor Aufschluss über den genaueren Grund.
Alle Konfigurationsparameter des E-Recht
-Signaturclients für MOA SS sind in einer
-zentralen Konfigurationsdatei zusammengefasst. Eine beispielhafte
-Konfigurationsdatei finden Sie unter $MOA_SS_CLIENT_INST/conf/moa-ss-erecht-client.config.properties.
-Für Hinweise, wie Sie dem E-Recht Signaturclient für MOA SS
-mitteilen, welche
-Konfigurationsdatei er verwenden soll, siehe Abschnitt 2.4.
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 -das Systemhandbuch lesen. Dort werden -der gesamte Ablauf eines Signaturerstellungsvorgangs sowie -die daran beteiligten Komponenten erklärt.
-Die Konfigurationsdatei ist als Java
-Properties Datei aufgebaut, d. h. jede Zeile
-enthält den Namen sowie den Wert des jeweiligen
-Konfigurationsparameters in der Form name=wert.
-Details zum Aufbau einer Java
-Properties Datei finden Sie in der API-Dokumentation zu
-Ihrem Java JDK, beispielsweise hier.
-
| Name | -location.schema.moa |
| Erläuterung | Mit -diesem Konfigurationsparameter wird dem E-Recht Signaturclient -für MOA SS -mitgeteilt, wo er das XML-Schema für die Validierung eines von -MOA SS empfangenen Signaturerstellungsresponses nach MOA SPSS -V1.3 findet. Der Konfigurationsparameter muss als
-Wert einen Pfad
-enthalten, der mit |
| Beispiel |
|
| Name | -location.ss.stylesheet |
| Erläuterung | Mit -diesem Konfigurationsparameter wird dem E-Recht Signaturclient -für MOA SS -mitgeteilt, wo er den Default-Stylesheet findet, der im MOA SS -Signaturerstellungsrequest angegeben und von MOA SS dazu verwendet -wird, um die XML-Repräsentation des Rechtsdokuments in die dann -tatsächlich elektronisch sigierte HTML-Repräsenation überzuführen. -Der Konfigurationsparameter muss als
-Wert einen Pfad
-enthalten, der mit |
| Beispiel |
|
| Name | -location.ss.requestTemplate |
-
| Erläuterung | Mit -diesem Konfigurationsparameter wird dem E-Recht Signaturclient -für MOA SS -mitgeteilt, wo er das XML-Template für den Signaturerstellungsrequest -an MOA SS findet. Der
-Konfigurationsparameter muss als
-Wert einen Pfad
-enthalten, der mit |
| Beispiel |
|
| Name | -service.ss.endpoint |
-
| Erläuterung | Mit -diesem Konfigurationsparameter wird dem E-Recht -Signaturclient für MOA SS der -Zugangspunkt zum Webservice von MOA SS mitgeteilt. Der -Konfigurationsparameter muss eine URL enthalten, die vom -E-Recht Signaturclient für MOA SS aus erreichbar ist und den -Zugangspunkt zu MOA SS -adressiert. |
| Beispiel | -
|
| Name | -service.ss.keyIdentifier |
-
| Erläuterung | Mit -diesem Konfigurationsparameter wird dem E-Recht -Signaturclient für MOA SS -mitgeteilt, welchen Schlüsselbezeichner er im -Signaturerstellungsrequest -an MOA SS verwenden soll. Der -Konfigurationsparameter muss den Bezeichner eines in -MOA SS hinterlegten Schlüsselbezeichner enthalten. |
-
| Beispiel |
|
| Name | -location.webAppHostPort |
-
| Erläuterung | Mit -diesem Konfigurationsparameter wird dem E-Recht -Signaturclient für MOA SS -mitgeteilt, unter welchem Hostnamen bzw. Port der Servlet Container, in -dem der E-Recht -Signaturclient für MOA SS läuft, vom Benutzer erreicht werden kann. -Der
-Konfigurationsparameter muss eine URL sein, die ausschließlich die
-Komponenten Protokoll (also in der Regel |
-
| Beispiel |
|
| Name | -location.webAppHostPortFromMOASS |
-
| Erläuterung | Mit -diesem Konfigurationsparameter wird dem E-Recht -Signaturclient für MOA SS -mitgeteilt, unter welchem Hostnamen bzw. Port der Servlet Container, in -dem der E-Recht -Signaturclient für MOA SS läuft, von MOA SS erreicht werden kann. -Der
-Konfigurationsparameter muss eine URL sein, die ausschließlich die
-Komponenten Protokoll (also in der Regel |
-
| Beispiel |
|
| Name | -location.tempdir |
-
| Erläuterung | Mit -diesem Konfigurationsparameter wird dem E-Recht -Signaturclient für MOA SS -mitgeteilt, wo es das Arbeitsverzeichnis zum temporären Ablegen der vom -Benutzer hochgeladenen Dokumente findet. Der
-Konfigurationsparameter muss als Wert
-einen Pfad
-enthalten, der vom E-Recht Signaturclient für MOA SS als relativ zum Context
-Root der Webapplikation interpretiert wird. Der angegebene
-Pfad muss einen abschließenden |
-
| Beispiel |
|
Die Benutzeroberfläche des E-Recht Signaturclient für MOA SS ist in -Form von Webseiten realisiert, die dem Benutzer in seinem Webbrowser -angezeigt werden.
Das Layout dieser Webseiten kann völlig frei
-gestaltet werden. Die Vorlagen für die Webseiten liegen in Form von
-JSP-Seiten (Java Server Pages) im Verzeichnis $MOA_SL_WEBAPP/pages (UploadXML.jsp, UploadImages.jsp, DownloadSignature.jsp sowie Error.jsp).
Wenn Sie das Layout gegenüber der Vorgabe
-verändern möchten, editieren Sie einfach die
-HTML-Teile dieser JSP-Seiten. Beachten Sie bitte, dass Sie dabei die
-JSP-Scriptelemente unverändert lassen. JSP-Scriptelemente sind
-entweder Tags, die mit dem Präfix jsp
-gekennzeichnet sind (z.B. <jsp:useBean>
-oder <jsp:getProperty>, oder
-Bereiche die mit der Kennzeichnung <%
-eingeleitet bzw. mit der Kennzeichnung %>
-ausgeleitet werden.