diff options
Diffstat (limited to 'spss.handbook')
| -rw-r--r-- | spss.handbook/handbook/usage/usage.html | 110 |
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_übersicht">Ü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 Übersicht</h1> <p> Die Module Signaturprüfung (SP) und Serversignatur (SS) sind als plattformunabhängige Module ausgelegt, die entweder als Webservice über HTTP bzw. HTTPS oder als Klassenbibliothek über ein API angesprochen werden kö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 über die Webservice-Schnittstelle. Im ersten Unterabschnitt werden typische XML-Requests zur Signaturerstellung mittels SS bzw. zur Signaturprüfung mittels SP vorgestellt, wie sie an das Webservice gesendet werden kö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önnen.. </p> + <p>Dieser Abschnitt beschreibt die Verwendung der Module SP und SS über die Webservice-Schnittstelle. Im ersten Unterabschnitt werden typische XML-Requests zur Signaturerstellung mittels SS bzw. zur Signaturprüfung mittels SP vorgestellt, wie sie an das Webservice gesendet werden kö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önnen.</p> <h2><a name="webservice_xmlrequests" id="webservice_xmlrequests"></a>2.1 XML-Requests </h2> <p>Dieser Abschnitt stellt typische XML-Requests für die Erstellung einer XML-Signatur mittels SS bzw. zur Prü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.</doc:Paragraph> </pre> <p>Das Element<code> CertificateCheck</code> enthält das Resultat der Zertifikatsprü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önnen die nun gesendet werden </p> +<p><a href="#webservice_xmlrequests">Abschnitt 2.1</a> bespricht eine Reihe von typischen XML-Requests, die über die Webservice-Schnittstelle an MOA SP/SS gesendet werden können, um entweder Signaturen zu erstellen (MOA SS) oder Signaturen zu prü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 Übersicht</h3> -<p>kurzvorstellung der drei clients (http, httpsserverauth, httpsclientauth), einsatzszenario fü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üft weder die Authentizität des verwendeten MOA-Webservices, noch identifiziert er sich selbst gegenü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üft die Authentizität des verwendeten MOA-Websservices an Hand dessen SSL-Serverzertifikats, identifiziert sich selbst jedoch nicht gegenü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üft einerseits die Authentizität des verwendeten MOA-Websservices an Hand dessen SSL-Serverzertifikats; andererseits weist er sich selbst mittels eines SSL-Client-Zertifikats gegenüber dem MOA-Webservice aus. </li> +</ul> +<p>Welcher der drei Varianten des Webservice-Clients zum Einsatz kommen soll, hängt von der Art ab, wie das MOA-Webservice betrieben wird, d.h. ob es Server- bzw. Client-Authentisierung unterstü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ächst einmal benö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öher; nicht nötig wenn JDSE 1.4.2 oder hö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öher; nur notwendig fü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 über HTTP an MOA SP/SS. </li> + <li>Der Webservice-Client empfä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ö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ält Pfad und Dateiname einer Java-Properties-Datei, die die weiteren Konfigurationsparameter für den Webservice-Client enthält. Ein relativer Pfad wird als relativ zum Arbeitsverzeichnis der Java Virtual Machine interpretiert. Genaue Infos zu den mö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ä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 über HTTPS.</p> +<p>Die Konfiguration von JSSE (Speicher für die vertrauenswürdigen Serverzertifikate, Typ dieses Speichers, Passwort für diesen Speicher) wird mittels zusä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ä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ü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 über HTTPS.</p> +<p>Die gegenüber <a href="#webservice_clients_httpsserverauth">Abschnitt 2.2.3</a> zusätzlich notwendige Konfiguration von JSSE (Speicher für das SSL-Client-Zertifikat sowie den dazugehörigen privaten Schlüssel, Typ dieses Speichers, Passwort für diesen Speicher) wird mittels zusä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ä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 ü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> </p> </body> </html> |