E-Recht

E-Recht: Signaturclient für MOA SS, V0.9

Betriebshandbuch

Inhalt

Übersicht
Installation
Konfiguration
1. Zentrale Konfigurationsdatei
2. Layout der Benutzeroberfläche

1 Übersicht

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.

2 Installation

2.1 Einführung

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.

2.2 Vorbereitung

Die folgenden Schritte dienen der Vorbereitung der Installation.

Installation von J2SE SDK: Installieren Sie J2SE 1.4.2 SDK oder J2SE 5.0 SDK in ein beliebiges Verzeichnis. Das Wurzelverzeichnis der J2SE SDK Installation wird im weiteren Verlauf als $JAVA_HOME bezeichnet.
Installation von Apache Tomcat: Installieren Sie Apache Tomcat 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 $CATALINA_HOME bezeichnet.
Installation von MOA SP: Installieren Sie das Kombinationsmodul MOA SPSS Version 1.3 oder höher entsprechend seiner Installationsanleitung. Sie benötigen die Webservice-Schnittstelle von MOA SS. Es ist ausreichend, mittels entsprechender Konfigurationseinstellungen ausschließlich MOA SS zu aktivieren; MOA SP kann deaktiviert bleiben. Wenn Sie sowohl für MOA SPSS als auch für den E-Recht Signaturclient für MOA SS Apache Tomcat als Servlet Container verwenden möchten, empfehlen wir, MOA SPSS und en E-Recht Signaturclient für MOA SS in jeweils eigenständigen Instanzen von Apache Tomcat zu betreiben.
Entpacken der Distribution des E-Recht Signaturclients für MOA SS: Entpacken Sie die Datei moa-ss-erecht-client-x.y.zip in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als $MOA_SS_CLIENT_INST bezeichnet.

2.3 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.3.1 Konfiguration des HTTP Connectors

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.

2.4 Einsatz des E-Recht Signaturclient für MOA SS in Tomcat

Um den E-Recht Signaturclient für MOA SS in Tomcat für den Einsatz vorzubereiten, sind folgende Schritte notwendig:

Die Datei $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.
Die zentrale Konfigurationsdatei für den E-Recht Signaturclient für MOA SS muss in ein beliebiges Verzeichnis im Dateisystem kopiert werden (z.B. $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.
Die Dateien 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.
Folgende System Properties für die Java Virtual Machine müssen bzw. können gesetzt werden. Am einfachsten können diese System Properties beim Starten von Tomcat in der Umgebungsvariablen 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.. Wird ein relativer Pfad angegeben, wird zuerst versucht, diesen relativ zum Wurzelverzeichnis der Webapplikation (also $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.

2.5 Starten und Stoppen von Tomcat

2.5.1 Unter Windows

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.

2.5.2 Unter Unix

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 start

gestartet werden. Das Stoppen von Tomcat erfolgt analog mit

bin/catalina.sh stop

2.5.3 Logging

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.

2.5.3.1 Format der Log-Meldungen

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.

2.5.4 Prüfen des erfolgreichen Starts

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.

3 Konfiguration

3.1 Zentrale Konfigurationsdatei

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.

3.1.1 Parameter für den MOA SS Signaturerstellungsrequest

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 / beginnt, und der vom E-Recht Signaturclient für MOA SS als relativ zum Context Root der Webapplikation interpretiert wird.

Beispiel

/WEB-INF/classes/resources/schemas/MOA-SPSS-1.3.xsd

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 / beginnt, und der vom E-Recht Signaturclient für MOA SS als relativ zum Context Root der Webapplikation interpretiert wird.

Beispiel

/static/erecht.stylesheet.1-9-0.xsl

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 / beginnt, und der vom E-Recht Signaturclient für MOA SS als relativ zum Context Root der Webapplikation interpretiert wird.

Beispiel

/WEB-INF/classes/resources/templates/CreateRequest.xml

3.1.2 Parameter der verwendeten MOA SS Installation

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

http://localhost:8081/moa-spss/services/SignatureCreation

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

KG_allgemein

3.1.3 Adressierung des Servlet Containers des E-Recht Signaturclients

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 http), Hostname (z.B. localhost) und Portnummer (z.B. 8084) enthält.

Beispiel

http://localhost:8084

Name location.webAppHostPortFromMOASS

Erläuterung

Der Konfigurationsparameter muss eine URL sein, die ausschließlich die Komponenten Protokoll (also in der Regel http), Hostname (z.B. localhost) und Portnummer (z.B. 8084) enthält.

Beispiel

http://localhost:8084

3.1.4 Arbeitsverzeichnis

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 / aufweisen und im Dateisystem tatsächlich existieren.

Beispiel

/workdir/temp/

3.2 Layout der Benutzeroberfläche

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.