Logo BKA E-Recht

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

Betriebshandbuch


Inhalt

  1. Übersicht

  2. Installation
    1. Einführung
    2. Vorbereitung
    3. Konfiguration von Apache Tomcat
      1. Konfiguration des HTTP Connectors
    4. Einsatz des E-Recht Signaturclients für MOA SS in Tomcat
    5. Starten und Stoppen von Tomcat
      1. Unter Windows
      2. Unter Unix
      3. Logging
        1. Format der Log-Meldungen
      4. Prüfen des erfolgreichen Starts
  3. Konfiguration
    1. Zentrale Konfigurationsdatei
      1. Parameter für den MOA SS Signaturerstellungsrequest
      2. Parameter der verwendeten MOA SS Installation
      3. Adressierung des Servlet Containers des E-Recht Signaturclients
      4. Arbeitsverzeichnis
    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:

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:

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.xmlparsererechtclient.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:

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

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 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.