Kapitel über Webserviceclients (2.2) hinzugefügt.

git-svn-id: https://joinup.ec.europa.eu/svn/moa-idspss/trunk@327 d688527b-c9ab-4aba-bd8d-4036d912da1d

1 files changed, 97 insertions, 13 deletions

diff --git a/spss.handbook/handbook/usage/usage.html b/spss.handbook/handbook/usage/usage.html
index 889a7dfed..f355a5676 100644
--- a/spss.handbook/handbook/usage/usage.html
+++ b/spss.handbook/handbook/usage/usage.html
@@ -53,8 +53,8 @@
         </a>          <ol>
             <li><a href="#webservice_clients_&#252;bersicht">&Uuml;bersicht</a></li>
             <li><a href="#webservice_clients_gemeinsamkeiten">Gemeinsamkeiten</a></li>
-            <li><a href="#webservice_clients_httpsserverauth">Besonderheiten von HTTPSServerAuth</a></li>
-            <li><a href="#webservice_clients_httpsclientauth">Besonderheiten von HTTPSClientAuth</a></li>
+            <li><a href="#webservice_clients_httpsserverauth">Besonderheiten von <code>HTTPSServerAuth.java</code></a></li>
+            <li><a href="#webservice_clients_httpsclientauth">Besonderheiten von <code>HTTPSClientAuth.java</code></a></li>
           </ol>
         </li>
       </ol>
@@ -68,12 +68,14 @@
       </ol>
     </li>
   </ol>
+  <ol type="A">	
+    <li><a href="#referenzierte_software">Referenzierte Software</a></li>
+  </ol>
 <hr/>
   <h1><a name="übersicht" id="übersicht"></a>1 &Uuml;bersicht</h1>
   <p>   Die Module Signaturpr&uuml;fung (SP) und Serversignatur (SS) sind als plattformunabh&auml;ngige Module ausgelegt, die entweder als Webservice &uuml;ber HTTP bzw. HTTPS oder als Klassenbibliothek &uuml;ber ein API angesprochen werden k&ouml;nnen. Dieses Handbuch beschreibt die Anwendung der beiden Module auf jede dieser beiden Arten.</p>
-  <p class="comment">TODO: Referenzierte Daten </p>
   <h1><a name="webservice"></a>2 Verwendung des Webservices </h1>
-  <p>Dieser Abschnitt beschreibt die Verwendung der Module SP und SS &uuml;ber die Webservice-Schnittstelle. Im ersten Unterabschnitt werden typische XML-Requests zur Signaturerstellung mittels SS bzw. zur Signaturpr&uuml;fung mittels SP vorgestellt, wie sie an das Webservice gesendet werden k&ouml;nnen. Der zweite Unterabschnitt stellt beispielhafte Implementierungen eines Webservice-Clients in Java vor, mit dem die Requests aus dem ersten Unterabschnitt an das Webservice gesendet werden k&ouml;nnen.. </p>
+  <p>Dieser Abschnitt beschreibt die Verwendung der Module SP und SS &uuml;ber die Webservice-Schnittstelle. Im ersten Unterabschnitt werden typische XML-Requests zur Signaturerstellung mittels SS bzw. zur Signaturpr&uuml;fung mittels SP vorgestellt, wie sie an das Webservice gesendet werden k&ouml;nnen. Der zweite Unterabschnitt stellt beispielhafte Implementierungen eines Webservice-Clients in Java vor, mit dem die Requests aus dem ersten Unterabschnitt an das Webservice gesendet werden k&ouml;nnen.</p>
   <h2><a name="webservice_xmlrequests" id="webservice_xmlrequests"></a>2.1 XML-Requests </h2>
   <p>Dieser Abschnitt stellt typische XML-Requests f&uuml;r die Erstellung einer XML-Signatur mittels SS bzw. zur Pr&uuml;fung einer CMS- bzw. XML-Signatur mittels SP vor. Zu jedem Request wird jeweils auch eine typische Response des Services besprochen. </p>
   <h3><a name="webservice_xmlrequests_erstellungxml" id="webservice_xmlrequests_erstellungxml"></a>2.1.1 Erstellung einer XML-Signatur</h3>
@@ -1091,17 +1093,99 @@ Ich habe weiters ein eigenens ID-Attribut bekommen.&lt;/doc:Paragraph&gt;
 </pre>
 <p>Das Element<code> CertificateCheck</code> enth&auml;lt das Resultat der Zertifikatspr&uuml;fung (siehe <a href="#webservice_xmlrequests_pruefungxml_einfach">Einfaches Beispiel</a>).</p>
 <h2><a name="webservice_clients" id="webservice_clients"></a>2.2 Webservice-Clients</h2>
-<p>2.1. zeigte requests, mit 2.2. k&ouml;nnen die nun gesendet werden </p>
+<p><a href="#webservice_xmlrequests">Abschnitt 2.1</a> bespricht eine Reihe von typischen XML-Requests, die &uuml;ber die Webservice-Schnittstelle an MOA SP/SS gesendet werden k&ouml;nnen, um entweder Signaturen zu erstellen (MOA SS) oder Signaturen zu pr&uuml;fen (MOA SP). Dieser Abschnitt zeigt die Verwendung des prototypischen Webservice-Clients, der mit dieser Dokumentation zu MOA SP/SS ausgeliefert wird.</p>
 <h3><a name="webservice_clients_übersicht" id="webservice_clients_übersicht"></a>2.2.1 &Uuml;bersicht</h3>
-<p>kurzvorstellung der drei clients (http, httpsserverauth, httpsclientauth), einsatzszenario f&uuml;r jeden client </p>
+<p>Der Webservice-Client existiert in drei Varianten, wobei jede Variante in einer eigenen Java-Klasse implementiert ist:</p>
+<ul>
+  <li>Der einfache Client (<code><a href="../../clients/webservice/src/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTP.java">HTTP.java</a></code>) arbeitet  ohne Authentifikation. Er pr&uuml;ft weder die Authentizit&auml;t des verwendeten MOA-Webservices, noch identifiziert er sich selbst gegen&uuml;ber dem MOA-Webservice.</li>
+  <li>Der Client mit Server-Authentisierung (<code><a href="../../clients/webservice/src/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSServerAuth.java">HTTPSServerAuth.java</a></code>) pr&uuml;ft die Authentizit&auml;t des verwendeten MOA-Websservices an Hand dessen SSL-Serverzertifikats, identifiziert sich selbst jedoch nicht gegen&uuml;ber dem MOA-Webservice.</li>
+  <li>Der Client mit  Client- und Server-Authentisierung (<code><a href="../../clients/webservice/src/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSClientAuth.java">HTTPSClientAuth.java</a></code>) pr&uuml;ft einerseits die Authentizit&auml;t des verwendeten MOA-Websservices an Hand dessen SSL-Serverzertifikats; andererseits weist er sich selbst mittels eines SSL-Client-Zertifikats gegen&uuml;ber dem MOA-Webservice aus. </li>
+</ul>
+<p>Welcher der drei Varianten des Webservice-Clients zum Einsatz kommen soll, h&auml;ngt von der Art ab, wie das MOA-Webservice betrieben wird, d.h. ob es Server- bzw. Client-Authentisierung unterst&uuml;tzt bzw. verlangt. Befinden sich sowohl MOA-Webservice als auch der Webservice-Client im gleichen, abgeschotteten Netzwerk, kann auch eine Kommunikation ohne Authenifikation in Betracht gezogen werden. Ansonsten wird der Standardfall wohl der Betrieb mit Server-Authentisierung (Verwendung von MOA SP) bzw. mit Server- und Client-Authentisierung (Verwendung von MOA SS) sein.</p>
+<p class="remark">Hinweis: Das <a href="../../">Wurzelverzeichnis</a> dieses Handbuchs stellt ein komplettes und sofort verwendbares Eclipse Projekt dar. </p>
 <h3><a name="webservice_clients_gemeinsamkeiten" id="webservice_clients_gemeinsamkeiten"></a>2.2.2 Gemeinsamkeiten</h3>
-<p>voraussetzungen (bibliotheken) </p>
-<p>ablauf: request von file lesen, soap-request erstellen, soap-request senden, soap-response empfanden, payload extrahieren, payload als file speichern </p>
-<h3><a name="webservice_clients_httpsserverauth" id="webservice_clients_httpsserverauth"></a>2.2.3 Besonderheiten von HTTPSServerAuth</h3>
-<p>debug property </p>
-<h3><a name="webservice_clients_httpsclientauth" id="webservice_clients_httpsclientauth"></a>2.2.4 Besonderheiten von HTTPSClientAuth </h3>
-<p>debug property</p>
+<p>Dieser Abschnitt beschreibt die Gemeinsamkeiten aller drei Varianten des Webservice-Clients. </p>
+<p>Zun&auml;chst einmal ben&ouml;tigen alle drei Varianten die folgenden Java-Bibliotheken, die im Ordner <a href="../../clients/webservice/lib/">clients/webservice/lib/</a> dieses Handbuchs bereits enthalten sind:</p>
+<table class="fixedwidth" border="1" cellpadding="2">
+  <TBODY>
+    <TR>
+      <TH>Java-Bibliothek</TH>
+      <TH>Bemerkung</TH>
+    </TR><TR>
+      <TD><a href="#referenzierte_software">J2SE</a></TD>
+      <TD> J2SE 1.3.1 SDK oder J2SE 1.4.2 SDK oder J2SE 5.0 SDK. </TD>
+    </TR>
+    <TR>
+      <TD><a href="#referenzierte_software">Apache Xerces</a></TD>
+      <TD>XML-Parser, Version 2.0.2 oder h&ouml;her; nicht n&ouml;tig wenn JDSE 1.4.2 oder h&ouml;her verwendet wird. </TD>
+    </TR>
+    <TR>
+      <TD><a href="#referenzierte_software">AXIS Framework</a></TD>
+      <TD>Webservice-Framework, Version 1.1.</TD>
+    </TR>
+    <TR>
+      <TD><a href="#referenzierte_software">JSSE</a></TD>
+      <TD>Java Secure Socket Extension, Version 1.0.3 oder h&ouml;her; nur notwendig f&uuml;r die Varianten <code>HTTPServerAuth</code> und <code>HTTPClientAuth</code>.</TD>
+    </TR>
+  </TBODY>
+</TABLE>
+<p>Weiters ist allen drei Varianten der folgende Kern-Ablauf gemeinsam:</p>
+<ol>
+  <li>Der Webservice-Client liest einen vorbereiteten MOA-XML-Request (z. B. einen der in <a href="#webservice_xmlrequests">Abschnitt 2.1</a> gezeigten) vom Dateisystem ein.</li>
+  <li>Der Webservice-Client erstellt einen SOAP-Request mit dem vom Dateisystem gelesenen MOA-XML-Request als Nutzlast.</li>
+  <li>Der Webservice-Client sendet den erstellten SOAP-Request &uuml;ber HTTP an MOA SP/SS. </li>
+  <li>Der Webservice-Client empf&auml;ngt die SOAP-Response von MOA SP/SS.</li>
+  <li>Der Webservice-Client extrahiert die Nutzlast des SOAP-Responses (d. h. die zum MOA-XML-Request aus Schritt 1 passende MOA-XML-Response), gibt diese auf die Konsole aus und speichert sie im Dateisystem. </li>
+</ol>
+<p>Konfiguriert werden k&ouml;nnen alle drei Varianten mit Hilfe von zwei Kommandozeilen-Parametern:</p>
+<ol>
+  <li>Der erste Kommandozeilenparameter gibt an, ob MOA SS (Wert <code>sign</code>) oder MOA SP (Wert <code>verify</code>) kontaktiert werden soll. </li>
+  <li>Der zweite Kommandozeilenparameter enth&auml;lt Pfad und Dateiname einer Java-Properties-Datei, die die weiteren Konfigurationsparameter f&uuml;r den Webservice-Client enth&auml;lt. Ein relativer Pfad wird als relativ zum Arbeitsverzeichnis der Java Virtual Machine interpretiert. Genaue Infos zu den m&ouml;glichen Konfigurationsparametern entnehmen Sie bitte der Quellcodedokumentation der jeweiligen Variante des Webservice-Clients. <a href="../../clients/webservice/conf/http.properties"><code>http.properties</code></a> enth&auml;lt eine auf dieses Handbuch abgestimmte Konfiguration.</li>
+</ol>
+<h3><a name="webservice_clients_httpsserverauth" id="webservice_clients_httpsserverauth"></a>2.2.3 Besonderheiten von <code>HTTPSServerAuth.java</code></h3>
+<p>Diese Variante des Webservice-Clients verwendet JSSE, um im Schritt 3 des Kernablaufs aus <a href="#webservice_clients_gemeinsamkeiten">Abschnitt 2.2.2</a> eine SSL-Verbindung mit Server-Authentifizierung zum MOA SP/SS Server aufzubauen. In dieser SSL-Verbindung sendet der Webservice-Client dann den erstellten SOAP-Request &uuml;ber HTTPS.</p>
+<p>Die Konfiguration von JSSE (Speicher f&uuml;r die vertrauensw&uuml;rdigen Serverzertifikate, Typ dieses Speichers, Passwort f&uuml;r diesen Speicher) wird mittels zus&auml;tzlicher Parameter in der in <a href="#webservice_clients_gemeinsamkeiten">Abschnitt 2.2.2</a> besprochenen Java-Properties-Datei vorgenommen. Genaue Infos zu diesen Konfigurationsparametern entnehmen Sie bitte der Quellcodedokumentation von <code><a href="../../clients/webservice/src/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSServerAuth.java">HTTPSServerAuth.java</a></code>. <a href="../../clients/webservice/conf/http.properties"><code>http.properties</code></a> enth&auml;lt eine auf dieses Handbuch abgestimmte Konfiguration.</p>
+<p>Falls Sie Probleme beim SSL-Verbindungsaufbau zwischen Webservice-Client und MOA SP/SS Webservice haben, empfiehlt sich die Aktivierung des JSSE Loggings. Das Setzen der daf&uuml;r notwendigen Java System Property ist im Quellcode von <code><a href="../../clients/webservice/src/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSServerAuth.java">HTTPSServerAuth.java</a></code> bereits enthalten, jedoch auskommentiert. Suchen Sie einfach nach dem String <code>javax.net.debug</code>, um zur entsprechenden Stelle im Quellcode zu gelangen. </p>
+<h3><a name="webservice_clients_httpsclientauth" id="webservice_clients_httpsclientauth"></a>2.2.4 Besonderheiten von <code>HTTPSClientAuth.java</code> </h3>
+<p>Diese Variante des Webservice-Clients verwendet JSSE, um im Schritt 3 des Kernablaufs aus <a href="#webservice_clients_gemeinsamkeiten">Abschnitt 2.2.2</a> eine SSL-Verbindung mit Server- und Client-Authentifizierung zum MOA SP/SS Server aufzubauen. In dieser SSL-Verbindung sendet der Webservice-Client dann den erstellten SOAP-Request &uuml;ber HTTPS.</p>
+<p>Die gegen&uuml;ber <a href="#webservice_clients_httpsserverauth">Abschnitt 2.2.3</a> zus&auml;tzlich notwendige Konfiguration von JSSE (Speicher f&uuml;r das SSL-Client-Zertifikat sowie den dazugeh&ouml;rigen privaten Schl&uuml;ssel, Typ dieses Speichers, Passwort f&uuml;r diesen Speicher) wird mittels zus&auml;tzlicher Parameter in der in <a href="#webservice_clients_gemeinsamkeiten">Abschnitt 2.2.2</a> besprochenen Java-Properties-Datei vorgenommen. Genaue Infos zu diesen Konfigurationsparametern entnehmen Sie bitte der Quellcodedokumentation von <code><a href="../../clients/webservice/src/at/gv/egovernment/moa/spss/handbook/clients/webservice/HTTPSClientAuth.java">HTTPSClientAuth.java</a></code>. <a href="../../clients/webservice/conf/http.properties"><code>http.properties</code></a> enth&auml;lt eine auf dieses Handbuch abgestimmte Konfiguration.</p>
+<p>Beachten Sie bitte auch den Hinweis zum JSSE Logging aus <a href="#webservice_clients_httpsserverauth">Abschnitt 2.2.3</a>.</p>
 <h1><a name="klassenbibliothek" id="klassenbibliothek"></a>3 Verwendung der Klassenbibliothek</h1>
-<p>3.1  </p>
+<p>abschnitt aus alter doc &uuml;bernehmen </p>
+<h1><a name="referenzierte_software" id="referenzierte_software"></a>A Referenzierte Software</h1>
+<p>Auf folgende Software-Pakete wird in diesem Handbuch verwiesen:</p>
+<table class="fixedWidth" border="1" cellpadding="2">
+  <tbody>
+    <tr>
+      <th scope="col">Name</th>
+      <th scope="col">Beschreibung</th>
+    </tr>
+    <tr>
+      <td><a href="http://xml.apache.org/xerces2-j/">Apache Xerces 2</a> </td>
+      <td>XML-Parser aus dem Apache Project</td>
+    </tr>
+    <tr>
+      <td><a href="http://xml.apache.org/axis/">Apache Axis</a></td>
+      <td>Webservice-Framework  aus dem Apache Project</td>
+    </tr>
+    <tr>
+      <td><a href="http://java.sun.com/j2se/1.3.1/" target="_blank">J2SE 1.3.1 SDK/JRE</a> </td>
+      <td>Java 2 Standard Edition in der Version 1.3.1 (Software Development Kit bzw. Java Runtime Environment) </td>
+    </tr>
+    <tr>
+      <td><a href="http://java.sun.com/j2se/1.4.2/" target="_blank">J2SE 1.4.2 SDK/JRE</a></td>
+      <td>Java 2 Standard Edition in der Version 1.4.2 (Software Development Kit bzw. Java Runtime Environment) </td>
+    </tr>
+    <tr>
+      <td><a href="http://java.sun.com/j2se/1.5.0/" target="_blank">J2SE 5.0 SDK/JRE</a> </td>
+      <td>Java 2 Standard Edition in der Version 5.0 (Software Development Kit bzw. Java Runtime Environment) </td>
+    </tr>
+    <tr>
+      <td><a href="http://java.sun.com/products/jsse/">JSSE</a></td>
+      <td>Java Secure Socket Extension </td>
+    </tr>
+  </tbody>
+</table>
+<p>&nbsp;</p>
 </body>
 </html>