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/common/LogoBKA.png | Bin 0 -> 8062 bytes erecht.client.ss/handbook/common/handbook.css | 300 ++++++++++++ erecht.client.ss/handbook/constraints.txt | 5 + erecht.client.ss/handbook/index.html | 37 ++ .../handbook/operation/images/testapp.screen1.png | Bin 0 -> 38150 bytes .../handbook/operation/images/testapp.screen2.png | Bin 0 -> 44749 bytes .../handbook/operation/images/testapp.screen3.png | Bin 0 -> 16625 bytes .../handbook/operation/images/testapp.screen4.png | Bin 0 -> 40110 bytes erecht.client.ss/handbook/operation/operation.html | 467 ++++++++++++++++++ .../handbook/system/images/Zusammenspiel.VSD | Bin 0 -> 138240 bytes .../handbook/system/images/Zusammenspiel.mit.png | Bin 0 -> 48649 bytes .../handbook/system/images/Zusammenspiel.ohne.png | Bin 0 -> 36106 bytes erecht.client.ss/handbook/system/system.html | 529 +++++++++++++++++++++ erecht.client.ss/handbook/usage/dummy.txt | 0 14 files changed, 1338 insertions(+) create mode 100644 erecht.client.ss/handbook/common/LogoBKA.png create mode 100644 erecht.client.ss/handbook/common/handbook.css create mode 100644 erecht.client.ss/handbook/constraints.txt create mode 100644 erecht.client.ss/handbook/index.html create mode 100644 erecht.client.ss/handbook/operation/images/testapp.screen1.png create mode 100644 erecht.client.ss/handbook/operation/images/testapp.screen2.png create mode 100644 erecht.client.ss/handbook/operation/images/testapp.screen3.png create mode 100644 erecht.client.ss/handbook/operation/images/testapp.screen4.png create mode 100644 erecht.client.ss/handbook/operation/operation.html create mode 100644 erecht.client.ss/handbook/system/images/Zusammenspiel.VSD create mode 100644 erecht.client.ss/handbook/system/images/Zusammenspiel.mit.png create mode 100644 erecht.client.ss/handbook/system/images/Zusammenspiel.ohne.png create mode 100644 erecht.client.ss/handbook/system/system.html create mode 100644 erecht.client.ss/handbook/usage/dummy.txt (limited to 'erecht.client.ss/handbook') diff --git a/erecht.client.ss/handbook/common/LogoBKA.png b/erecht.client.ss/handbook/common/LogoBKA.png new file mode 100644 index 000000000..6a92647fd Binary files /dev/null and b/erecht.client.ss/handbook/common/LogoBKA.png differ diff --git a/erecht.client.ss/handbook/common/handbook.css b/erecht.client.ss/handbook/common/handbook.css new file mode 100644 index 000000000..b8428d58d --- /dev/null +++ b/erecht.client.ss/handbook/common/handbook.css @@ -0,0 +1,300 @@ +body +{ + font-family: "Times New Roman", Times, serif; + font-size: medium; + font-weight: normal; + margin-left: 2.5em; + margin-right: 2.5em; +} + +p +{ + margin-top: 0pt; + margin-bottom: 0.5em; + text-align: justify +} + +pre +{ + font-family: "Courier New", monospace; + font-size: 90%; + background-color: #cccccc; + color: #000000; + margin-left:1.5%; + margin-right:1.5%; + margin-top: 1em; + margin-bottom: 1em; + border: #008000 none; +} + +hr +{ + color: #000080; + background-color: #000080; + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +table.fixedWidth +{ + width: 97%; + margin-left:1.5%; + margin-right:1.5%; + margin-top: 1em; + margin-bottom: 1em; +} + + +table.varWidth +{ + margin-left:1.5%; + margin-top: 1em; + margin-bottom: 1em; +} + +th +{ + text-align: left; +} + +h1 +{ + color: #000080; + text-align: left; + font-size: 167%; + font-family: Arial, Helvetica, sans-serif; + font-weight: normal +} + +h2 +{ + color: #000080; + font-size: 150%; + font-family: Arial, Helvetica, sans-serif; + font-weight: normal +} + +h3 +{ + color: #000080; + font-size: 133%; + font-family: Arial, Helvetica, sans-serif; + font-weight: normal +} + +h4 +{ + color: #000080; + font-size: 116%; + font-family: Arial, Helvetica, sans-serif; + font-weight: normal +} + +h5 +{ + color: #000080; + font-size: 100%; + font-family: Arial, Helvetica, sans-serif; + font-weight: normal +} + +h6 +{ + color: #000080; + font-size: 83%; + font-family: Arial, Helvetica, sans-serif; + font-weight: normal +} + +code +{ + font-family: "Courier New", Courier, monospace; + font-size: 90%; + color: #000000 +} + +dd +{ + margin-top: 0.8em; + margin-bottom: 0.8em; + text-align: justify + +} + +dt +{ + margin-top: 0.8em; + font-family: Arial, Helvetica, sans-serif; + color: #000080 +} + +ol +{ + margin-top: 0.5em; + margin-bottom: 0.5em +} + +ol.alpha +{ + list-style-type: lower-alpha +} + +li +{ + margin-top: 0.25em; + margin-bottom: 0.25em; + text-align: justify +} + +a:hover +{ + color: #990000 +} + + +.title +{ + text-align: left; + font-size: 167%; + color: #000080; + font-family: Arial, Helvetica, sans-serif; + margin-top: 0.4em; + margin-bottom: 0.4em +} + +.subtitle +{ + text-align: left; + font-size: 133%; + color: #000080; + font-family: Arial, Helvetica, sans-serif; + margin-top: 0.4em; + margin-bottom: 0.4em +} + +.glossaryTerm +{ + font-style: italic; + color: #006699 +} + +.example +{ + font-family: "Courier New", monospace; + background-color: #CCFFFF; + color: #000000; + margin: 0pt 0pt; + border: #008000 none +} + +.schema +{ + font-family: "Courier New", monospace; + background-color: #FFFFCC; + color: #000000; + margin: 0pt 0pt; + border: #008000 none +} + +.documentinfo +{ + font-family: Arial, Helvetica, sans-serif; + font-size: 100%; +} + +.ol-contents +{ + font-size: 100%; + margin-top: 0.0em; + margin-bottom: 0.0em; +} + +.li-contents +{ + font-size: 100%; + margin-top: 0.0em; + margin-bottom: 0.0em; +} + +.logoTitle +{ + text-align: center; + font-size: 133%; + color: #000080; + font-family: Arial, Helvetica, sans-serif; +} + +.logoTable +{ + margin-bottom: 0px; + margin-left: 0px +} + +.superscript +{ + vertical-align: super; + font-size: 66%; +} + +.term +{ + font-style: italic; +} + +.comment +{ + color: #000000; + background: #ffff00; + font-style: italic +} + +.addedErrata12 +{ + color: #FF0000; + background-color: #FFEEEE; + text-decoration: underline +} + +.deletedErrata12 +{ + color: #999999; + background-color: #EEEEEE; + text-decoration: line-through +} + +.added12 +{ + color: #FF0000; + text-decoration: underline +; background-color: #F8F0FF +} + +.deleted12 +{ + color: #999999; + text-decoration: line-through +; background-color: #f8f0ff +} + +.rfc2119Keyword +{ + font-variant: small-caps; + font-style: normal; +} + +.remark { font-style: italic} + +li.faq +{ + margin-top: 1.5em; + margin-bottom: 1.5em; +} + +.faq-question +{ + color: #000080; + font-size: 100%; + font-family: Arial, Helvetica, sans-serif; + font-weight: normal; + margin-bottom: 0.4em; +} diff --git a/erecht.client.ss/handbook/constraints.txt b/erecht.client.ss/handbook/constraints.txt new file mode 100644 index 000000000..637a7764e --- /dev/null +++ b/erecht.client.ss/handbook/constraints.txt @@ -0,0 +1,5 @@ +- Der E-Recht Signaturclient für MOA SS unterstützt derzeit die Anbindung + von MOA SS nur über die ungesicherte HTTP Webservice-Schnittstelle. + +- Der E-Recht Signaturclient bietet derzeit keine eigenständige + Benutzerauthentisierung. \ No newline at end of file diff --git a/erecht.client.ss/handbook/index.html b/erecht.client.ss/handbook/index.html new file mode 100644 index 000000000..005639b94 --- /dev/null +++ b/erecht.client.ss/handbook/index.html @@ -0,0 +1,37 @@ + + + + MOA SL - Übersicht + + + + + + + + + + + + + + + +
Logo BKAE-Recht
+
+ +

E-Recht: Signaturclient für MOA SS

+ +

Übersicht zur Dokumentation der Version 0.9

+
+ +
+
Betriebshandbuch
+ +
Anleitung für die Installation sowie Erläuterung aller Konfigurationsoptionen.
+ +
Systemhandbuch
+ +
Beschreibung der einzelnen Komponenten des Signaturclients und ihrem Zusammenspiel.
Anwenderhandbuch
Beschreibung der Verwendung des Signaturclients.
+
+ \ No newline at end of file diff --git a/erecht.client.ss/handbook/operation/images/testapp.screen1.png b/erecht.client.ss/handbook/operation/images/testapp.screen1.png new file mode 100644 index 000000000..38a226d09 Binary files /dev/null and b/erecht.client.ss/handbook/operation/images/testapp.screen1.png differ diff --git a/erecht.client.ss/handbook/operation/images/testapp.screen2.png b/erecht.client.ss/handbook/operation/images/testapp.screen2.png new file mode 100644 index 000000000..45230d5c9 Binary files /dev/null and b/erecht.client.ss/handbook/operation/images/testapp.screen2.png differ diff --git a/erecht.client.ss/handbook/operation/images/testapp.screen3.png b/erecht.client.ss/handbook/operation/images/testapp.screen3.png new file mode 100644 index 000000000..7d5db9cad Binary files /dev/null and b/erecht.client.ss/handbook/operation/images/testapp.screen3.png differ diff --git a/erecht.client.ss/handbook/operation/images/testapp.screen4.png b/erecht.client.ss/handbook/operation/images/testapp.screen4.png new file mode 100644 index 000000000..9fe7ee264 Binary files /dev/null and b/erecht.client.ss/handbook/operation/images/testapp.screen4.png differ 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 diff --git a/erecht.client.ss/handbook/system/images/Zusammenspiel.VSD b/erecht.client.ss/handbook/system/images/Zusammenspiel.VSD new file mode 100644 index 000000000..0088d5109 Binary files /dev/null and b/erecht.client.ss/handbook/system/images/Zusammenspiel.VSD differ diff --git a/erecht.client.ss/handbook/system/images/Zusammenspiel.mit.png b/erecht.client.ss/handbook/system/images/Zusammenspiel.mit.png new file mode 100644 index 000000000..4e7fcda67 Binary files /dev/null and b/erecht.client.ss/handbook/system/images/Zusammenspiel.mit.png differ diff --git a/erecht.client.ss/handbook/system/images/Zusammenspiel.ohne.png b/erecht.client.ss/handbook/system/images/Zusammenspiel.ohne.png new file mode 100644 index 000000000..0dc944cb9 Binary files /dev/null and b/erecht.client.ss/handbook/system/images/Zusammenspiel.ohne.png differ diff --git a/erecht.client.ss/handbook/system/system.html b/erecht.client.ss/handbook/system/system.html new file mode 100644 index 000000000..e4924f5fb --- /dev/null +++ b/erecht.client.ss/handbook/system/system.html @@ -0,0 +1,529 @@ + + + + + + MOA SL - Systemhandbuch + + + + + + + + + + + + + + + + + + + + + + + + +
Logo BKAOpen +Source
+ +für das E-Government		Logo MOA
+ +
+

MOA: +Serverseitige Signaturprüfung (SL), V 1.1

+ +

Systemhandbuch

+ +
+

Inhalt

+ +
    + +
  1. +

    Einführung

    + +
    2. + +
  2. Überblick
    3. + +
  3. Komponenten +
      + +
    1. Der +Filter SL2MOAFilter +
      2. + +
    2. Das +Servlet MOAServlet +
      3. + +
    3. Die +JSP-Seite resultOverview.jsp +
      4. + +
    4. Das +Servlet HashInputDataServlet
      5. + +
    5. Das +Servlet ReturnServlet
      6. + +
    6. Die +Klasse URLRewriter
      7. + +
    7. Der +Deployment Descriptor web.xml
      8. + +
    + +
    4. + +
  4. Zusammenspiel der +Komponenten +
      + +
    1. Basisablauf
      2. + +
    2. Ablauf mit Rewrite-Proxy
      3. + +
    + +
    5. + +
+ +
+

1 +Einführung

+ +

Das Modul Serverseitige +Signaturprüfung (MOA SL) ist als +plattformunabhängiges Modul ausgelegt, das als Webservice +über HTTP bzw. HTTPS angesprochen werden kann.

+ +

Dieses Handbuch beschreibt den Aufbau von MOA SL. Abschnitt 2 +bietet einen groben Überblick über die Funktionsweise +von MOA SL. Abschnitt 3 beschreibt die einzelnen Komponenenten, aus +denen MOA SL aufgebaut ist. Abschnitt 4 schließlich +beschreibt das Zusammenspiel der einzelnen Komponenten.

+ +

Für die Installation und die Konfiguration von MOA SL +siehe Betriebshandbuch. +

+ +

2 +Überblick

+ +

Das Modul Serverseitige +Signaturprüfung (MOA SL) bietet für +Signaturprüfung eine serverseitige Implementierung einer +Bürgerkarten-Umgebung entsprechend den Spezifikationen +zur österreichischen Bürgerkarte in der +Version 1.2.

+ +

Der Funktionsumfang von MOA SL kann wie folgt zusammengefasst +werden:

+ + + +

3 +Komponenten

+ +

3.1 +Der Filter SL2MOAFilter

+ +

Die Klasse SL2MOAFilter +ist ein +Filter, +der einerseits +den HttpServletRequest +verändert, bevor er an das Servlet MOAServlet +weitergeleitet wird, und andererseits den HttpServletResponse +verändert, nachdem er vom Servlet MOAServlet +bearbeitet wurde.

+ +

Der HttpServletRequest +enhält ja zunächst den Request zur Prüfung +der XML-Signatur in einem Format entsprechend der Spezifikationen +zur österreichischen Bürgerkarte in der +Version 1.2 (SL-Request). Das MOAServlet +erwartet sich jedoch den +Request zur Prüfung der XML-Signatur in einem Format +entsprechend der Webservice-Schnittstelle für das Basismodul +MOA SP (MOA-Request). Aufgabe des SL2MOAFilters +ist es daher, vor der Ausführung des MOAServlets +für eine passende Umsetzung des SL-Requests in den +entsprechenden MOA-Request zu sorgen.

+ +

Zur Erfüllung dieser +Aufgabe bedient sich der SL2MOAFilter +der Klasse SL2MOA, +in der die Request-Transformation gekapselt ist. Zunächst wird eine einfache Transformation des SL-Requests in den MOA-Request durchgeführt, +indem die Namen der XML-Elemente entsprechend angepasst werden. Danach werden am dadurch entstandenen MOA-Request noch folgende Modifikationen +durchgeführt: +

+

+ +

Das MOAServlet +würde dann die Antwort des Basismoduls MOA SP in einem Format +entsprechend der Webservice-Schnittstelle für das Basismodul +MOA SP (MOA-Response) retournieren. Die Anwendung, die das MOAServlet +aufruft, erwartet sich jedoch die Antwort auf den Request zur +Prüfung +der XML-Signatur in einem Format entsprechend der Spezifikationen +zur österreichischen Bürgerkarte in der +Version 1.2 (SL-Response). Aufgabe des SL2MOAFilters +ist es daher, nach der Ausführung des MOAServlets +für eine passende Umsetzung der MOA-Response in die +entsprechende SL-Response zu sorgen. Zur Erfüllung +dieser +Aufgabe bedient sich der SL2MOAFilter +der Klasse MOA2SL, +in der die +Response-Transformation gekapselt ist.

+ +

Eine weitere Aufgabe der Klasse SL2MOAFilter +ist es schließlich, die JSP-Seite resultoverview.jsp +einzubinden, die für eine benutzertaugliche HTML-Darstellung +der SL-Response sorgt. Diese benutzertaugliche Darstellung wird dann +tatsächlich als finales Resultat des MOAServlets +an die Anwendung zurückübermittelt. Bevor die +JSP-Seite eingebunden wird, erzeugt SL2MOAFilter +Java Beans aus den Informationen der SL-Response und speichert sie im +Request Scope bzw. Session Scope. Diese Java Beans werden dann von der +JSP-Seite zum +Aufbau der benutzertauglichen HTML-Darstellung herangezogen. +Für weitere Informationen zur JSP-Seite sowie zu den von ihr +verwendeten Java Beans siehe Abschnitt 3.3. +

+ +

3.2 +Das Servlet MOAServlet

+ +

Die Klasse +MOAServlet ist ein HttpServlet +und als solches für die Kommunikation mit dem Basismodul MOA +SP verantwortlich.

+ +

Das Servlet liest aus dem ServletInputStream +des HttpServletRequests +den MOA SP Request +zur Prüfung der XML-Signatur und sendet diesen XML-Request +unter Verwendung der Webservice-Schnittstelle von MOA SP an das +Basismodul MOA SP.

+ +

Danach liest das Servlet die vom Basismodul MOA SP auf den +Request zur Prüfung der XML-Signatur +rückübermittelte Response und schreibt diese +XML-Response in den ServletOutputStream +der HttpServletResponse.

+ +

Das MOAServlet bedient sich zur Kommunikation mit MOA SP der +Klasse +MOAInvoker, in der die +Funktionalität des Webservice-Clients für MOA SP +gekapselt ist.

+ +

3.3 Die JSP-Seite resultOverview.jsp

+ +

Die JSP-Seite resultOverview.jsp ist +verantwortlich für die Aufbereitung +einer benutzertauglichen HTML-Darstellung der SL-Response, die +das Servlet MOAServlet +im Zusammenspiel mit dem Filter SL2MOAFilter +erzeugt. 

+ +

Die für die Aufbereitung erforderlichen Informationen +werden der JSP-Seite in Form von Java Beans zur Verfügung +gestellt, die zuvor vom SL2MOAFilter +erzeugt worden sind (vergleiche Abschnitt 3.1). +Folgende Java Beans stehen der JSP-Seite zur Verfügung:

+ + + +

Die JSP-Seite resultOverview.jsp +erzeugt aus den mittels der erwähnten Java Beans zur +Verfügung gestellten Informationen eine HTML-Darstellung. +Diese HTML-Darstellung ist in die folgenden Informationsblöcke +unterteilt:

+ + + +

Ein Beispiel für die resultierende HTML-Darstellung +befindet sich hier.

+ +

3.4 Das Servlet HashInputDataServlet

+ +

Das Servlet HashInputServlet +ist +für die Verfügbarkeit der von der geprüften +XML-Signatur gesicherten Dokumente verantwortlich. 

+ +

In der HTML-Aufbereitung der SL-Response, die von der +JSP-Seite resultOverview.jsp erzeugt wird, +(vergleiche Abschnitt +3.3) befinden sich Links auf alle gesicherten Dokumente. +Diese Links führen jeweils auf das Servlet HashInputServlet. 

+ +

Das Servlet entnimmt aus der aufgerufenen URL die Parameter +zum Auffinden des Session Scopes sowie die fortlaufende Nummer des +gesicherten Dokuments. Im Session Scope ist als Attribut die in Abschnitt 3.3 +erwähnte DataInfoBean: +gespeichert, die alle notwendigen Informationen enthält, damit +das Servlet das angefragte gesicherte Dokument aus dem Filesystem lesen +und als Ergebnis an den Browser zurückliefern kann. Je nach +dem, ob es sich beim gesicherten Dokument um ein SLXHTML-Dokument +handelt oder nicht, wird der Content-Type Header der HTTP Response an +den Browser passend gesetzt.

+ +

3.5 +Das Servlet ReturnServlet

+ +

Das Servlet ReturnServlet +ist nach Quittierung der HTML-Darstellung zur geprüften +XML-Signatur durch den Benutzer für die Weiterleitung der +SL-Response an den DataURL-Server sowie für die Weiterleitung +der daraus resultierenden Antwort des DataURL-Servers an den Benutzer +verantwortlich.

+ +

Damit verhält sich MOA SL genau wie in der +Spezifikation Transportprotokolle +Security-Layer (Teil der Spezifikationen +zur österreichischen Bürgerkarte in der +Version 1.2) in Abschnitt +3.2.3 für den Fall 5e beschrieben ist: Wenn der +Benutzer die HTML-Aufbereitung der Ergebnisse der geprüften +XML-Signatur gesichtet hat und durch Verfolgung des darin enthaltenen +Links quittiert, sendet das ReturnServlet +die SL-Response an den DataURL-Server. Die URL des DataURL-Servers +wurde von der Anwendung im ursprünglichen Request an das MOAServlet +als Formular-Parameter angegeben. Der DataURL-Server antwortet auf das +Eintreffen der SL-Response mit einem HTTP-Response an das ReturnServlet, +diese wird vom ReturnServlet +als Antwort auf das Quittieren der HTML-Darstellung an den Browser +weitergeleitet. 

+ +

Nachdem mit diesem Schritt die Bearbeitung der zur +Prüfung übermittelten XML-Signatur durch MOA-SL +abgeschlossen ist, wird am Ende des ReturnServlet +die Session und damit alle gespeicherten Informationen zur +geprüften XML-Signatur gelöscht. 

+ +

3.6 +Die Klasse URLRewriter

+ +

Die Klasse URLRewriter +ist +für das Umschreiben von URLs verantwortlich die in der +HTML-Aufbereitung der SL-Response enthalten sind, die dem Benutzer in +seinem Webbrowser angezeigt wird.

+ +

MOA SL kann so konfiguriert werden, dass die in der +HTML-Aufbereitung der SL-Response enthaltenen +URLs nicht direkt +auf +Ressourcen von MOA SL (z.B. die von der Signatur gesicherten +Dokumente), sondern auf einen Rewrite-Proxy +verweisen. Die URL auf die eigentliche Ressource von MOA SL ist in dem +umgeschriebenen Link als URL-Parameter kodiert. Der Rewrite-Proxy sorgt +für die Umsetzung des aus dem umgeschriebenen Link +resultierenden +Requests an ihn selbst in einen Request an MOA SL. 

+ +

Sinnvoll ist diese Konfigurationsvariante dann, wenn MOA SL +nicht direkt vom Internet aus erreichbar sein soll, sondern nur auf dem +Umweg über einen dedizierten Webserver, dem Rewrite-Proxy.

+ +

Die Methode rewrite der Klasse URLRewriter +wird bei der Erstellung der HTML-Aufbereitung der SL-Response durch die +JSP-Seite resultOverview.jsp jedenfalls +aufgerufen; die Entscheidung, ob die in die Methode übergebene +URL tatsächlich umgeschrieben wird oder nicht, entscheidet die +Methode auf Grund der Konfigurationseinstellungen von MOA SL.

+ +

3.7 +Der Deployment Descriptor web.xml

+

+Im Deployment Descriptor web.xmldes +Web Archives (WAR-File) von MOA SL sind im Wesentlichen folgende +Konfigurationen eingerichtet, die im Normalfall nicht verändert +werden müssen:

+ + +

4 +Zusammenspiel der Komponenten

+ +

4.1 Basisablauf

+

Die nachfolgende Grafik stellt das Zusammenspiel der Komponenten aus Abschnitt 3 mit dem Anwender und dem DataURL-Server dar.

+

Zusammenspiel der Komponenten - Basisablauf

+ + + + + + + + + + + + + + + +
1, 2 +

Prüfung der Signatur: Anfrage wird eigentlich an MOAServlet gerichtet, durch die Filter-Konfiguration über den Deployment-Descriptor web.xml wird jedoch vorher und nachher der SL2MOAFilter dazwischengeschalten. Die Aufbereitung der HTML-Darstellung der SL-Response wird vom SL2MOAFilter an die JSP-Seite resultOverview.jsp delegiert.

+
3,4 +

Über die HTML-Ansicht der SL-Response kann der Anwender +die einzelnen, von der XML-Signatur gesicherten Dokumente abrufen. +Die Links für die Dokumente verweisen auf das HashInputServlet, die Zuordnung im Servlet passiert über URL-Parameter (Session-ID, fortlaufende Nummer des Dokuments).

+
5, 6, 7, 8 +

In Schritt 5 quittiert der Anwender die HTML-Darstellung der +SL-Response. Das Quittieren funktioniert über einen Link in der +HTML-Darstellung, der auf das ReturnServlet verweist. Das ReturnServlet +sendet die SL-Response an den DataURL-Server. Der DataURL-Server +antwortet entsprechend auf die übermittelte SL-Response; diese +Antwort wird vom ReturnServlet unverändert an den Antwender weitergeleitet.

+
+

4.2 Ablauf mit Rewrite-Proxy

+Die nachfolgende Grafik stellt das Zusammenspiel der Komponenten aus +Abschnitt 3 mit dem Anwender und dem DataURL-Server dar, wobei die +Anfragen vom Anwender nicht direkt an MOA SL, sondern indirekt +über einen Rewrite-Proxy gestellt werden.
+
Zusemmenspiel der Komponenten - mit Rewrite-Proxy
+
+ + + + + + + + + + + + + + + +
1, 2 +

Prüfung der Signatur: Anfrage wird eigentlich an MOAServlet gerichtet, durch die Filter-Konfiguration über den Deployment-Descriptor web.xml wird jedoch vorher und nachher der SL2MOAFilter dazwischengeschalten. Die Aufbereitung der HTML-Darstellung der SL-Response wird vom SL2MOAFilter an die JSP-Seite resultOverview.jsp delegiert. Die Anfrage des Anwenders wird nicht direkt an das MOAServlet gerichtet, sondern über den Rewrite-Proxy, der die Anfrage-URL passend umschreibt.

+
3,4 +

Über +die HTML-Ansicht der SL-Response kann der Anwender die einzelnen, von +der XML-Signatur gesicherten Dokumente abrufen. Die Links für die +Dokumente verweisen nicht direkt auf das HashInputServlet, sondern zunächst auf den Rewrite-Proxy, der die Links passend auf das HashInputServlet umsetzt. Die Zuordnung im Servlet passiert über URL-Parameter (Session-ID, fortlaufende Nummer des Dokuments).

+
5, 6, 7, 8 +

In +Schritt 5 quittiert der Anwender die HTML-Darstellung der SL-Response. +Das Quittieren funktioniert über einen Link in der HTML-Darstellung, +der nicht direkt auf das ReturnServlet verweist, sondern zunächst auf den Rewrite-Proxy, der die Links passend auf das ReturnServlet  umsetzt. Das ReturnServlet +sendet die SL-Response an den DataURL-Server. Der DataURL-Server +antwortet entsprechend auf die übermittelte SL-Response; diese Antwort +wird vom ReturnServlet unverändert an den Antwender weitergeleitet.

+
+
+
+ + diff --git a/erecht.client.ss/handbook/usage/dummy.txt b/erecht.client.ss/handbook/usage/dummy.txt new file mode 100644 index 000000000..e69de29bb -- cgit v1.2.3