move handbook files

2 files changed, 325 insertions, 0 deletions

diff --git a/release-infos/handbook/clients/api/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/api/CreateXMLSignature.java b/release-infos/handbook/clients/api/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/api/CreateXMLSignature.java
new file mode 100644
index 0000000..aad0a0c
--- /dev/null
+++ b/release-infos/handbook/clients/api/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/api/CreateXMLSignature.java
@@ -0,0 +1,154 @@
+/*
+ * Copyright 2003 Federal Chancellery Austria
+ * MOA-SPSS has been developed in a cooperation between BRZ, the Federal
+ * Chancellery Austria - ICT staff unit, and Graz University of Technology.
+ *
+ * Licensed under the EUPL, Version 1.1 or - as soon they will be approved by
+ * the European Commission - subsequent versions of the EUPL (the "Licence");
+ * You may not use this work except in compliance with the Licence.
+ * You may obtain a copy of the Licence at:
+ * http://www.osor.eu/eupl/
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the Licence is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the Licence for the specific language governing permissions and
+ * limitations under the Licence.
+ *
+ * This product combines work with different licenses. See the "NOTICE" text
+ * file for details on the various modules and licenses.
+ * The "NOTICE" text file is part of the distribution. Any derivative works
+ * that you distribute must include a readable copy of the "NOTICE" text file.
+ */
+
+
+package at.gv.egovernment.moa.spss.handbook.clients.api;
+
+import java.io.ByteArrayInputStream;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.w3c.dom.Element;
+
+import at.gv.egovernment.moa.spss.api.SPSSFactory;
+import at.gv.egovernment.moa.spss.api.SignatureCreationService;
+import at.gv.egovernment.moa.spss.api.common.Content;
+import at.gv.egovernment.moa.spss.api.common.MetaInfo;
+import at.gv.egovernment.moa.spss.api.xmlsign.CreateTransformsInfo;
+import at.gv.egovernment.moa.spss.api.xmlsign.CreateTransformsInfoProfile;
+import at.gv.egovernment.moa.spss.api.xmlsign.CreateXMLSignatureRequest;
+import at.gv.egovernment.moa.spss.api.xmlsign.CreateXMLSignatureResponse;
+import at.gv.egovernment.moa.spss.api.xmlsign.DataObjectInfo;
+import at.gv.egovernment.moa.spss.api.xmlsign.SignatureEnvironmentResponse;
+import at.gv.egovernment.moa.spss.api.xmlsign.SingleSignatureInfo;
+import at.gv.egovernment.moa.util.DOMUtils;
+
+/**
+ * Dieses einfache Beispiel demonstriert grundlegend den Gebrauch der API von MOA SP/SS. Es wird damit eine
+ * einfach aufgebaute XML-Signatur erzeugt.
+ */
+public class CreateXMLSignature
+{
+  /**
+   * Methode main.
+   * 
+   * Enthält beispielhaften Code zum grundlegenden Gebrauch der API von MOA SP/SS. Es wird damit eine
+   * einfach aufgebaute XML-Signatur erzeugt.
+   * 
+   * ACHTUNG: Stellen Sie bei Verwendung von J2SE 1.4.x bzw. 5.x sicher, dass Sie die System-Property 
+   * <code>java.endorsed.dirs</code> auf jenes Verzeichnis gesetzt haben, in dem sich die XPath-
+   * und XSLT-Bibliothek <em>Xalan-J</em> befindet.
+   * 
+   * @param args <ul>
+   *             <li>
+   *             args[0] enthält einen Verweis auf die Konfigurations-Datei von MOA SP/SS Der Verweis 
+   *             enthält entweder eine absolute oder eine relative Pfadangabe, wobei eine relative 
+   *             Angabe als relativ zum Arbeitsverzeichnis der Java VM interpretiert wird. 
+   *             </li>
+   *             <li>
+   *             args[1] enthält einen Verweis auf die Konfigurations-Datei von Log4J, dem Logging-
+   *             Framework, das von MOA SP/SS verwendet wird. Der Verweis enth�lt entweder eine 
+   *             absolute oder eine relative Pfadangabe, wobei eine relative Angabe als relativ zum
+   *             Arbeitsverzeichnis der Java VM interpretiert wird. 
+   *             </li>
+   *             </ul>
+   * 
+   * @throws Exception Sollten Fehler auftreten werden die Fehler an die Java-VM weitergeleitet.
+   */
+  public static void main(String[] args) throws Exception
+  {
+    // Setzen der System-Properties
+    init(args);
+
+    // Serverfunktionshandler instanzieren
+    SPSSFactory spf = SPSSFactory.getInstance();
+
+    // Zu signierende Daten in ein Contentobjekt einbinden (die Daten werden hier explizit angegeben,
+    // sollen aber in der Signatur mittels URL "http://uri.data.org" referenziert werden
+    byte[] data = "Diese Daten werden signiert.".getBytes("UTF-8");
+    ByteArrayInputStream bis = new ByteArrayInputStream(data);
+    Content cont = spf.createContent(bis, null);
+
+    // Metainformationen zu den zu signierenden Daten erstellen
+    MetaInfo mi = spf.createMetaInfo("text/plain", null, null, null);
+
+    // Transformationen erstellen (hier werden keine Transformationen angewandt)
+    CreateTransformsInfo cti = spf.createCreateTransformsInfo(null, mi);
+    CreateTransformsInfoProfile ct = spf.createCreateTransformsInfoProfile(cti, null);
+
+    // Datenobjekt aufbauen
+    DataObjectInfo doi = spf.createDataObjectInfo(DataObjectInfo.STRUCTURE_ENVELOPING, false, cont, ct);
+
+    // Erstellen eines SingleSignatureInfo-Containers
+    // Enth�lt alle Angaben zur Erstellung *einer* Signatur
+    List dataobjectinfolist = new ArrayList();
+    dataobjectinfolist.add(doi);
+    SingleSignatureInfo ssi = spf.createSingleSignatureInfo(dataobjectinfolist, null, false);
+
+    // Erstellen des Request-Objekts (Schl�sselbezeichner, Liste von SingleSignatureInfo-Containern)
+    List singlesignatureinfolist = new ArrayList();
+    singlesignatureinfolist.add(ssi);
+    CreateXMLSignatureRequest cxsreq = spf.createCreateXMLSignatureRequest("KG_allgemein",
+      singlesignatureinfolist);
+
+    // Signatureerstellungsservice instanzieren und aufrufen
+    SignatureCreationService scs = SignatureCreationService.getInstance();
+    CreateXMLSignatureResponse cxsres = scs.createXMLSignature(cxsreq);
+
+    // Response auswerten
+    List elements = cxsres.getResponseElements();
+    SignatureEnvironmentResponse ser = (SignatureEnvironmentResponse) elements.get(0);
+
+    // Auswertung des ersten (und einzigen) SignatureEnvironmentResponse-Containers
+    int response_type = ser.getResponseType();
+
+    if (response_type == SignatureEnvironmentResponse.ERROR_RESPONSE)
+    {
+      // Fehlerfall
+      System.out.println("Bei der Erstellung der Signatur ist ein Fehler aufgetreten.");
+    }
+    else
+    {
+      // Signaturerstellung erfolgreich
+      System.out.println("Signaturerstellung erfolgreich:");
+
+      Element se = ser.getSignatureEnvironment();
+      System.out.println(DOMUtils.serializeNode(se));
+    }
+  }
+
+  /**
+   * Setzt die notwendigen System-Properties f�r die Konfiguration der MOA SP/SS API. 
+   * 
+   * @param args Siehe @link CreateXMLSignature#main(String[]).
+   */
+  private static void init(String[] args)
+  {
+    if (args == null || args.length != 2)
+    {
+      System.out.println("Verwendung: CreateXMLSignature <MOASPSSConfigFile> <Log4JConfigFile>");
+    }
+    System.setProperty("moa.spss.server.configuration", args[0]);
+    System.setProperty("log4j.configuration", "file:" + args[1]);
+  }
+}
\ No newline at end of file
diff --git a/release-infos/handbook/clients/api/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/api/VerifyXMLSignature.java b/release-infos/handbook/clients/api/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/api/VerifyXMLSignature.java
new file mode 100644
index 0000000..6a4a57c
--- /dev/null
+++ b/release-infos/handbook/clients/api/src/main/java/at/gv/egovernment/moa/spss/handbook/clients/api/VerifyXMLSignature.java
@@ -0,0 +1,171 @@
+/*
+ * Copyright 2003 Federal Chancellery Austria
+ * MOA-SPSS has been developed in a cooperation between BRZ, the Federal
+ * Chancellery Austria - ICT staff unit, and Graz University of Technology.
+ *
+ * Licensed under the EUPL, Version 1.1 or - as soon they will be approved by
+ * the European Commission - subsequent versions of the EUPL (the "Licence");
+ * You may not use this work except in compliance with the Licence.
+ * You may obtain a copy of the Licence at:
+ * http://www.osor.eu/eupl/
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the Licence is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the Licence for the specific language governing permissions and
+ * limitations under the Licence.
+ *
+ * This product combines work with different licenses. See the "NOTICE" text
+ * file for details on the various modules and licenses.
+ * The "NOTICE" text file is part of the distribution. Any derivative works
+ * that you distribute must include a readable copy of the "NOTICE" text file.
+ */
+
+
+package at.gv.egovernment.moa.spss.handbook.clients.api;
+
+import java.io.FileInputStream;
+import java.io.FileNotFoundException;
+import java.util.HashMap;
+
+import at.gv.egovernment.moa.spss.MOAException;
+import at.gv.egovernment.moa.spss.api.SPSSFactory;
+import at.gv.egovernment.moa.spss.api.SignatureVerificationService;
+import at.gv.egovernment.moa.spss.api.common.Content;
+import at.gv.egovernment.moa.spss.api.common.SignerInfo;
+import at.gv.egovernment.moa.spss.api.xmlverify.VerifySignatureInfo;
+import at.gv.egovernment.moa.spss.api.xmlverify.VerifySignatureLocation;
+import at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureRequest;
+import at.gv.egovernment.moa.spss.api.xmlverify.VerifyXMLSignatureResponse;
+
+/**
+ * Dieses einfache Beispiel demonstriert grundlegend den Gebrauch der API von MOA SP/SS. 
+ * Es wird damit eine einfach aufgebaute XML-Signatur gepr�ft.
+ */
+
+public class VerifyXMLSignature
+{
+  /**
+   * Methode main.
+   * 
+   * Enthält beispielhaften Code zum grundlegenden Gebrauch der API von MOA SP/SS. 
+   * Es wird damit eine einfach aufgebaute XML-Signatur geprüft.
+   * 
+   * ACHTUNG: Stellen Sie bei Verwendung von J2SE 1.4.x bzw. 5.x sicher, dass Sie die System-Property 
+   * <code>java.endorsed.dirs</code> auf jenes Verzeichnis gesetzt haben, in dem sich die XPath-
+   * und XSLT-Bibliothek <em>Xalan-J</em> befindet.
+   * 
+   * @param args <ul>
+   *             <li>
+   *             args[0] enthält einen Verweis auf die Konfigurations-Datei von MOA SP/SS Der Verweis 
+   *             enthält entweder eine absolute oder eine relative Pfadangabe, wobei eine relative 
+   *             Angabe als relativ zum Arbeitsverzeichnis der Java VM interpretiert wird. 
+   *             </li>
+   *             <li>
+   *             args[1] enthält einen Verweis auf die Konfigurations-Datei von Log4J, dem Logging-
+   *             Framework, das von MOA SP/SS verwendet wird. Der Verweis enth�lt entweder eine 
+   *             absolute oder eine relative Pfadangabe, wobei eine relative Angabe als relativ zum
+   *             Arbeitsverzeichnis der Java VM interpretiert wird. 
+   *             </li>
+   *             <li>
+   *             args[2] enth�lt Pfad und Dateiname des XML-Dokuments mit der darin enthaltenen, zu
+   *             prüfenden XML-Signatur. Verwenden Sie z.B. das mit diesem Handbuch mitgelieferte
+   *             Beispiel <code>clients/api/signatures/SimpleSignature.xml</code>.
+   *             </li>
+   *             </ul>
+   */
+  public static void main(String[] args)
+  {
+    // Setzen der System-Properties
+    init(args);
+
+    // Factory und Service instanzieren
+    SPSSFactory spssFac = SPSSFactory.getInstance();
+    SignatureVerificationService sigVerifyService = SignatureVerificationService.getInstance();
+    
+    // Content aus Dokument mit zu pr�fender Signatur erstellen
+    FileInputStream sigDocFIS = null;
+    try
+    {
+      sigDocFIS = new FileInputStream(args[2]);
+    }
+    catch (FileNotFoundException e1)
+    {
+      System.err.println("XML-Dokument mit zu prüfender Signatur nicht gefunden: " + args[2]);
+      System.exit(-1);
+    }
+    Content sigDocContent = spssFac.createContent(sigDocFIS, null);
+    
+    // Position der zu pr�fenden Signatur im Dokument angeben
+    // (Nachdem im XPath-Ausdruck ein NS-Pr�fix verwendet wird, muss in einer Lookup-Tabelle
+    // der damit bezeichnete Namenraum mitgegeben werden)
+    HashMap nSMap = new HashMap();
+    nSMap.put("dsig", "http://www.w3.org/2000/09/xmldsig#");
+    VerifySignatureLocation sigLocation = spssFac.createVerifySignatureLocation("//dsig:Signature", nSMap);
+    
+    // Zu pr�fendes Dokument und Signaturposition zusammenfassen
+    VerifySignatureInfo sigInfo = spssFac.createVerifySignatureInfo(sigDocContent, sigLocation);
+    
+    // Pr�frequest zusammenstellen
+    VerifyXMLSignatureRequest verifyRequest = spssFac.createVerifyXMLSignatureRequest(
+      null,    // Wird Pr�fzeit nicht angegeben, wird aktuelle Zeit verwendet 
+      sigInfo, 
+      null,    // Keine Erg�nzungsobjekte notwendig
+      null,    // Signaturmanifest-Pr�fung soll nicht durchgef�hrt werden
+      false,   // Hash-Inputdaten, d.h. tats�chlich signierte Daten werden nicht zur�ckgeliefert
+      "Test-Signaturdienste");  // ID des verwendeten Vertrauensprofils
+    
+    VerifyXMLSignatureResponse verifyResponse = null;
+    try
+    {
+      // Aufruf der Signaturpr�fung
+      verifyResponse = sigVerifyService.verifyXMLSignature(verifyRequest);
+    }
+    catch (MOAException e)
+    {
+      // Service liefert Fehler
+      System.err.println("Die Signaturprüfung hat folgenden Fehler geliefert:");
+      System.err.println("Fehlercode: " + e.getMessageId());
+      System.err.println("Fehlernachricht: " + e.getMessage());
+      System.exit(-1);
+    }
+    
+    // Auswertung der Response
+    System.out.println();
+    System.out.println("Ergebnisse der Signaturprüfung:");
+    System.out.println();
+    
+    // Besondere Eigenschaften des Signatorzertifikats
+    SignerInfo signerInfo = verifyResponse.getSignerInfo();
+    System.out.println("*** Ist Zertifikat des Signators qualifiziert? " + ((signerInfo.isQualifiedCertificate()) ? "ja" : "nein"));
+    System.out.println("*** Ist Zertifikat des Signators von einer Behürde? " + ((signerInfo.isPublicAuthority()) ? "ja" : "nein"));
+    
+    // Ergebnisse von Signatur- und Zertifikatspr�fung
+    System.out.println();
+    System.out.println("Ergebniscode der Signaturprüfung: " + verifyResponse.getSignatureCheck().getCode());
+    System.out.println("Ergebniscode der Zertifikatsprüfung: " + verifyResponse.getCertificateCheck().getCode());
+    
+    // Signatorzertifikat
+    System.out.println();
+    System.out.println("*** Zertifikat des Signators:");
+    System.out.println("Aussteller: " + signerInfo.getSignerCertificate().getIssuerDN());
+    System.out.println("Subject: " + signerInfo.getSignerCertificate().getSubjectDN());
+    System.out.println("Seriennummer: " + signerInfo.getSignerCertificate().getSerialNumber());
+  }
+
+  /**
+   * Setzt die notwendigen System-Properties f�r die Konfiguration der MOA SP/SS API. 
+   * 
+   * @param args Siehe @link VerifyXMLSignature#main(String[]).
+   */
+  private static void init(String[] args)
+  {
+    if (args == null || args.length != 3)
+    {
+      System.out.println("Verwendung: VerifyXMLSignature <MOASPSSConfigFile> <Log4JConfigFile> <XMLDocWithSignature>");
+      System.exit(-1);
+    }
+    System.setProperty("moa.spss.server.configuration", args[0]);
+    System.setProperty("log4j.configuration", "file:" + args[1]);
+  }
+}
\ No newline at end of file