From 1c900609d64445040e8c5bdbfa01ae1a0f563f43 Mon Sep 17 00:00:00 2001 From: gregor Date: Wed, 28 Feb 2007 13:17:57 +0000 Subject: Initial commit git-svn-id: https://joinup.ec.europa.eu/svn/moa-idspss/trunk@806 d688527b-c9ab-4aba-bd8d-4036d912da1d --- erecht.client.ss/handbook/operation/operation.html | 467 +++++++++++++++++++++ 1 file changed, 467 insertions(+) create mode 100644 erecht.client.ss/handbook/operation/operation.html (limited to 'erecht.client.ss/handbook/operation/operation.html') diff --git a/erecht.client.ss/handbook/operation/operation.html b/erecht.client.ss/handbook/operation/operation.html new file mode 100644 index 000000000..25b152803 --- /dev/null +++ b/erecht.client.ss/handbook/operation/operation.html @@ -0,0 +1,467 @@ + + +MOA +SL - Betriebshandbuch + + +
Logo BKA E-Recht

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

+

Betriebshandbuch

+

Inhalt

+

  1. Übersicht

    +
  2. Installation +
    1. Einführung
      2. +
    2. Vorbereitung
      3. +
    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
      6. +
  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
    4. +

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, +für die Beschreibung der Verwendung siehe Anwenderhandbuch. +

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 XML-Dokuments, 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.2 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.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:

+

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 

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

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

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

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

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

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

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

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

+

\ No newline at end of file -- cgit v1.2.3