Update documentation (Usage for CreateCMSSignatureRequest)

1 files changed, 57 insertions, 12 deletions

diff --git a/spss/handbook/handbook/usage/usage.html b/spss/handbook/handbook/usage/usage.html
index 4d14ab917..6fcccc612 100644
--- a/spss/handbook/handbook/usage/usage.html
+++ b/spss/handbook/handbook/usage/usage.html
@@ -29,8 +29,8 @@
         <li><a href="#webservice_xmlrequests">XML-Requests</a>          <ol>
             <li><a href="#webservice_xmlrequests_erstellungcms">Erstellung einer CMS bzw. CAdES-Signatur</a></li>
               <ol>
-                <li><a href="#webservice_xmlrequests_erstellungcms_einfach">Einfaches Beispiel</a></li>
-                <li><a href="#webservice_xmlrequests_erstellungcms_erweitert">Erweitertes Beispiel</a></li>
+                <li><a href="#webservice_xmlrequests_erstellungcms_einfach">Beispiel (Base64-codiertes Datenobjekt)</a></li>
+                <li><a href="#webservice_xmlrequests_erstellungcms_erweitert">Beispiel (Datenobjekt als Referenz)</a></li>
               </ol>
             <li><a href="#webservice_xmlrequests_erstellungxml">Erstellung einer XML bzw. XAdES-Signatur</a>              
               <ol>
@@ -85,18 +85,64 @@
   <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>
   <h2><a name="webservice_xmlrequests" id="webservice_xmlrequests"></a>2.1 XML-Requests </h2>
-  <p>TODO: Auch plain CMS unterst&uuml;tzt?</p>
-<p>Dieser Abschnitt stellt typische XML-Requests f&uuml;r die Erstellung einer XML/XAdES- und CMS/CAdES-Signatur mittels SS bzw. zur Pr&uuml;fung einer CMS/CAdES- bzw. XML/XAdES-Signatur mittels SP vor. Zu jedem Request wird jeweils auch eine typische Response des Services besprochen. </p>
-  <p class="remark">Bitte beachten Sie: Einige der vorgestellten Requests referenzieren beispielhafte Daten auf <code>localhost</code>, z.B. <code>http://localhost:8080/referencedData/Text.txt</code>. Wenn Sie diese Beispiele ausprobieren m&ouml;chten, m&uuml;ssen Sie daf&uuml;r sorgen, dass MOA SS bzw. SP diese Daten auch tats&auml;chlich aufl&ouml;sen kann. Wenn Sie Ihre Tomcat-Installation auf <code>localhost:8080</code> betreiben, ist es ausreichend, wenn sie die diesem Handbuch beiliegende Webapplikation <code><a href="../../clients/common/referencedData/referencedData.war">referencedData.war</a></code> in das Verzeichnis <code>webapps</code> Ihrer Tomcat-Installation kopieren. Ansonsten m&uuml;ssen Sie zus&auml;tzlich die URLs in den Requests anpassen. </p>
+  <p>Dieser Abschnitt stellt typische XML-Requests f&uuml;r die Erstellung einer XML/XAdES- und CMS/CAdES-Signatur mittels SS bzw. zur Pr&uuml;fung einer CMS/CAdES- bzw. XML/XAdES-Signatur mittels SP vor. Zu jedem Request wird jeweils auch eine typische Response des Services besprochen. </p>
+<p class="remark">Bitte beachten Sie: Einige der vorgestellten Requests referenzieren beispielhafte Daten auf <code>localhost</code>, z.B. <code>http://localhost:8080/referencedData/Text.txt</code>. Wenn Sie diese Beispiele ausprobieren m&ouml;chten, m&uuml;ssen Sie daf&uuml;r sorgen, dass MOA SS bzw. SP diese Daten auch tats&auml;chlich aufl&ouml;sen kann. Wenn Sie Ihre Tomcat-Installation auf <code>localhost:8080</code> betreiben, ist es ausreichend, wenn sie die diesem Handbuch beiliegende Webapplikation <code><a href="../../clients/common/referencedData/referencedData.war">referencedData.war</a></code> in das Verzeichnis <code>webapps</code> Ihrer Tomcat-Installation kopieren. Ansonsten m&uuml;ssen Sie zus&auml;tzlich die URLs in den Requests anpassen. </p>
   <h3><a name="webservice_xmlrequests_erstellungcms" id="webservice_xmlrequests_erstellungcms"></a>2.1.1 Erstellung einer CMS bzw. CAdES-Signatur</h3>
-  <h4><a name="webservice_xmlrequests_erstellungcms_einfach" id="webservice_xmlrequests_erstellungcms_einfach"></a>2.1.1.1 Einfaches Beispiel</h4>
-  <p>TODO</p>
-  
-  <h4><a name="webservice_xmlrequests_erstellungcms_erweitert" id="webservice_xmlrequests_erstellungcms_erweitert"></a>2.1.1.1 Erweitertes Beispiel</h4>
+  <p>MOA-SS erm&ouml;glicht die Erstellung einer herk&ouml;mmlichen CMS-Signatur und einer CAdES-Signatur&nbsp;gem&auml;&szlig; der <a href="http://www.buergerkarte.at/konzept/securitylayer/spezifikation/20080220/core/Core.html#signaturerstellungNachXMLDSIG" target="_blank">Security-Layer Spezifikation V1.2x TODO</a>. Die Auswahl ob eine herk&ouml;mmliche XML oder eine Security-Layer konforme CAdES-Signatur erstellt wird, erfolgt durch das Attribute <code>SecurityLayerConformity</code> im Signaturerstelltungs-Request (siehe auch folgende Beispiele).</p>
+<h4><a name="webservice_xmlrequests_erstellungcms_einfach" id="webservice_xmlrequests_erstellungcms_einfach"></a>2.1.1.1 Beispiel (Base64-codiertes Datenobjekt)</h4>
+<h5>Request</h5>
+  <p><code><a href="../../clients/webservice/resources/requests/CreateCMSSignatureRequest.Base64Content.xml" target="_blank">CreateCMSSignatureRequest.Base64Content.xml</a></code> ist ein einfacher XML-Request zur Erzeugung einer CAdES-Signatur. Sein Aufbau wird nachfolgend analysiert:</p>
+  <pre>  &lt;KeyIdentifier&gt;KG_allgemein&lt;/KeyIdentifier&gt; </pre>
+  <p><code>KG_allgemein</code> bezeichnet eine Schl&uuml;sselgruppe, aus der SS einen Signaturschl&uuml;ssel selektieren soll und muss einer in der SP/SS-Konfigurationsdatei definierten Schl&uuml;sselgruppe entsprechen. </p>
+  <pre>  &lt;SingleSignatureInfo SecurityLayerConformity="true"&gt;</pre>
+  <p> F&uuml;r jedes <code>SingleSignatureInfo</code>Element wird eine eigene CMS/CAdES-Signatur erzeugt. Wird das Attribut <code>SecurityLayerConformity</code> auf <code>true</code> gesetzt, dann wird eine CAdES-Signatur gem&auml;&szlig; <a href="http://www.buergerkarte.at/konzept/securitylayer/spezifikation/20080220/core/Core.html#signaturerstellungNachXMLDSIG" target="_blank">Security-Layer Spezifikation V1.2x TODO </a> erzeugt; d.h. es werden signierte Properties (Zeitpunkt der Signaturerstellung, das f&uuml;r die Signatur&uuml;berpr&uuml;fung zu verwendende Zertifikat, Metainformationen zu den signierten Datenobjekten).</p>
+<pre>    &lt;DataObjectInfo Structure="enveloping"&gt;
+	     &lt;DataObject&gt;
+		    &lt;MetaInfo&gt;
+             &lt;MimeType&gt;text/plain&lt;/MimeType&gt;
+          &lt;/MetaInfo&gt;
+          &lt;Content&gt;
+         	   &lt;Base64Content&gt;RGllc2UgRGF0ZW4gc2luZCByZWluZXIgVGV4dC4=&lt;/Base64Content&gt;
+          &lt;/Content&gt;			
+       &lt;/DataObject&gt;		
+	  &lt;/DataObjectInfo&gt;
+</pre>
+<p>Das zu signierende Daten-Objekt muss in einem  <code>DataObjectInfo</code> Element spezifiziert werden. Das Attribut <code>Structure</code> gibt an, ob die Daten in die Signatur integriert werden sollen (<code>Structure="enveloping"</code>) oder nicht (<code>Structure="detached"</code>). </p>
+<p> Im nachfolgenden <code>DataObject</code> Element muss entweder das Attribut <code>Reference</code> (enth&auml;lt eine URL, von der SS die Daten beziehen soll) gesetzt sein, oder aber die zu signierenden Daten werden explizit im Element <code>Base64Content</code> (enth&auml;lt Daten in Base64 kodierter Form) spezifiziert sein. Die Angabe der zu signierenden Daten &uuml;ber das Attribut <code>Reference</code> und gleichzeitig im Element <code>Base64Content</code> ist nicht erlaubt. Zus&auml;tzlich muss im Element <code>MimeType</code> (unter dem Element <code>MetaInfo</code>) der MIME-Type der zu signierenden Daten spezifiziert werden.</p>
+  <p>Im konkreten Beispiel sollen die Daten in die Signatur integriert werden (<code>Structure="enveloping"</code>). Die Daten werden in diesem Beispiel mittels <code>Base64Content</code> angegeben. Der MIME-Type wird mit <code>text/plain</code> angegeben.</p>
+<h5>Response</h5>
+<p>TODO: Neue Signatur erzeugen (da CAdES - d.h. noch auf neues iaik-moa warten)</p>
+  <p><code><a href="../../clients/webservice/resources/requests/CreateCMSSignatureRequest.Base64Content.resp.xml" target="_blank">CreateCMSSignatureRequest.Base64Content.resp.xml</a></code> ist eine typische Response des SS Webservices auf den obigen Request. Sein Aufbau wird nachfolgend analysiert. Bitte beachten Sie, dass  die  dargestellte Response zur bessernen Lesbarkeit einger&uuml;ckt und gek&uuml;rzt wurde.  </p>
+  <pre>&lt;CreateCMSSignatureResponse
+  xmlns=&quot;http://reference.e-government.gv.at/namespace/moa/20020822#&quot; <br>  xmlns:dsig=&quot;http://www.w3.org/2000/09/xmldsig#&quot;&gt;<br>	&lt;CMSSignature&gt;MIAGCSqGSI...p92gh6wAAAAAAAA=&lt;/CMSSignature&gt;<br>&lt;/CreateCMSSignatureResponse&gt;</pre>
+<p><code>CreateCMSSignatureResponse</code> enth&auml;lt je erzeugter Signatur ein Element <code>CMSSignature</code> (in diesem Fall genau ein Element). <code>CMSSignature</code> enth&auml;lt die von SS erzeugte CAdES-Signatur (da <code>SecurityLayerConformity="true"</code> im Request angegeben wurde) als Base64-codierten Wert. Das unterzeichnete Datenobjekt ist in der Signaturstruktur selbst enthalten (<code>enveloping</code>). </p>
+<h4><a name="webservice_xmlrequests_erstellungcms_erweitert" id="webservice_xmlrequests_erstellungcms_erweitert"></a>2.1.1.2 Beispiel (Datenobjekt als Referenz)</h4>
   
-<p> TODO</p>
+<h5>Request</h5>
+<p><code><a href="../../clients/webservice/resources/requests/CreateCMSSignatureRequest.Reference.xml" target="_blank">CreateCMSSignatureRequest.Reference.xml</a></code> ist ein einfacher XML-Request zur Erzeugung einer CMS-Signatur. Sein Aufbau wird nachfolgend analysiert:</p>
+<pre>  &lt;KeyIdentifier&gt;KG_allgemein&lt;/KeyIdentifier&gt; </pre>
+<p><code>KG_allgemein</code> bezeichnet eine Schl&uuml;sselgruppe, aus der SS einen Signaturschl&uuml;ssel selektieren soll und muss einer in der SP/SS-Konfigurationsdatei definierten Schl&uuml;sselgruppe entsprechen. </p>
+<pre>  &lt;SingleSignatureInfo SecurityLayerConformity="false"&gt;</pre>
+<p> F&uuml;r jedes <code>SingleSignatureInfo</code>Element wird eine eigene CMS/CAdES-Signatur erzeugt. Wird das Attribut <code>SecurityLayerConformity</code> auf <code>true</code> gesetzt, dann wird eine CAdES-Signatur gem&auml;&szlig; <a href="http://www.buergerkarte.at/konzept/securitylayer/spezifikation/20080220/core/Core.html#signaturerstellungNachXMLDSIG" target="_blank">Security-Layer Spezifikation V1.2x TODO </a> erzeugt; d.h. es werden signierte Properties (Zeitpunkt der Signaturerstellung, das f&uuml;r die Signatur&uuml;berpr&uuml;fung zu verwendende Zertifikat, Metainformationen zu den signierten Datenobjekten).</p>
+<pre>    &lt;DataObjectInfo Structure="detached"&gt;
+	     &lt;DataObject&gt;
+		    &lt;MetaInfo&gt;
+             &lt;MimeType&gt;text/plain&lt;/MimeType&gt;
+          &lt;/MetaInfo&gt;
+          &lt;Content Reference=&quot;http://localhost:8080/moa-spss-handbook-referencedData/Text.txt&quot;/&gt;         	   
+       &lt;/DataObject&gt;		
+	  &lt;/DataObjectInfo&gt;
+</pre>
+<p>Das zu signierende Daten-Objekt muss in einem <code>DataObjectInfo</code> Element spezifiziert werden. Das Attribut <code>Structure</code> gibt an, ob die Daten in die Signatur integriert werden sollen (<code>Structure="enveloping"</code>) oder nicht (<code>Structure="detached"</code>). </p>
+<p> Im nachfolgenden <code>DataObject</code> Element muss entweder das Attribut <code>Reference</code> (enth&auml;lt eine URL, von der SS die Daten beziehen soll) gesetzt sein, oder aber die zu signierenden Daten werden explizit im Element <code>Base64Content</code> (enth&auml;lt Daten in Base64 kodierter Form) spezifiziert sein. Die Angabe der zu signierenden Daten &uuml;ber das Attribut <code>Reference</code> und gleichzeitig im Element <code>Base64Content</code> ist nicht erlaubt. Zus&auml;tzlich muss im Element <code>MimeType</code> (unter dem Element <code>MetaInfo</code>) der MIME-Type der zu signierenden Daten spezifiziert werden.</p>
+<p>Im konkreten Beispiel sollen die Daten nicht in die Signatur integriert werden (<code>Structure="detached"</code>). Die Daten werden in diesem Beispiel mittels der Attributs <code>Refernce</code> angegeben und SS muss es von dieser URL laden. Der MIME-Type wird mit <code>text/plain</code> angegeben.</p>
+<h5>Response</h5>
+<p><code><a href="../../clients/webservice/resources/requests/CreateCMSSignatureRequest.Reference.resp.xml" target="_blank">CreateCMSSignatureRequest.Reference.resp.xml</a></code> ist eine typische Response des SS Webservices auf den obigen Request. Sein Aufbau wird nachfolgend analysiert. Bitte beachten Sie, dass  die  dargestellte Response zur bessernen Lesbarkeit einger&uuml;ckt und gek&uuml;rzt wurde. </p>
+<pre>&lt;CreateCMSSignatureResponse
+  xmlns=&quot;http://reference.e-government.gv.at/namespace/moa/20020822#&quot; <br>  xmlns:dsig=&quot;http://www.w3.org/2000/09/xmldsig#&quot;&gt;<br>	&lt;CMSSignature&gt;MIAGCSqGSI...SwxhbA9pAAAAAAAA&lt;/CMSSignature&gt;<br>&lt;/CreateCMSSignatureResponse&gt;</pre>
+<p><code>CreateCMSSignatureResponse</code> enth&auml;lt je erzeugter Signatur ein Element <code>CMSSignature</code> (in diesem Fall genau ein Element). <code>CMSSignature</code> enth&auml;lt die von SS erzeugte CMS-Signatur (da <code>SecurityLayerConformity="false"</code> im Request angegeben wurde) als Base64-codierten Wert. Das unterzeichnete Datenobjekt ist in der Signaturstruktur nicht enthalten (<code>detached</code>).</p>
 <h3><a name="webservice_xmlrequests_erstellungxml" id="webservice_xmlrequests_erstellungxml"></a>2.1.2 Erstellung einer XML bzw. XAdES-Signatur</h3>
-<p>MOA-SS erm&ouml;glicht die Erstellung einer herk&ouml;mmlichen XML-Signatur und einer XAdES-Signatur&nbsp;gem&auml;&szlig; der <a href="http://www.buergerkarte.at/konzept/securitylayer/spezifikation/20080220/core/Core.html#signaturerstellungNachXMLDSIG" target="_blank">Security-Layer Spezifikation V1.2x</a>. Die Auswahl ob eine herk&ouml;mmliche XML oder eine Security-Layer konforme XAdES-Signatur erstellt wird, erfolgt durch das Attribute <code>SecurityLayerConformity</code> im Signaturerstelltungs-Request (siehe auch folgende Beispiele). </p>
+<p>MOA-SS erm&ouml;glicht die Erstellung einer herk&ouml;mmlichen XML-Signatur und einer XAdES-Signatur&nbsp;gem&auml;&szlig; der <a href="http://www.buergerkarte.at/konzept/securitylayer/spezifikation/20080220/core/Core.html#signaturerstellungNachXMLDSIG" target="_blank">Security-Layer Spezifikation V1.2x TODO</a>. Die Auswahl ob eine herk&ouml;mmliche XML oder eine Security-Layer konforme XAdES-Signatur erstellt wird, erfolgt durch das Attribute <code>SecurityLayerConformity</code> im Signaturerstelltungs-Request (siehe auch folgende Beispiele). </p>
 <p>Im Falle einer XAdES-Signatur, kann entweder eine XAdES-Signatur in der Version 1.1.1 oder in der Version 1.4.2 erstellt werden. Dies h&auml;ngt von der in der MOA-SS Konfiguration angegeben XAdES-Version ab (siehe hierzu <a href="../config/config.html#konfigurationsparameter_ss_xades">Konfiguration der XAdES Version</a>).</p>
 <h4><a name="webservice_xmlrequests_erstellungxml_simple" id="webservice_xmlrequests_erstellungxml_simple"></a>2.1.2.1 Einfaches Beispiel</h4>
   <h5>Request</h5>
@@ -1236,6 +1282,5 @@ Ich habe weiters ein eigenens ID-Attribut bekommen.&lt;/doc:Paragraph&gt;
   </tr>
   </tbody>
 </table>
-<p>&nbsp;</p>
 </body>
 </html>