Anwender der Bibliothek sollen ihre bereits vorhandenen Security-Module möglichst weiterverwenden können. Neben der Einbindung eigener Implementierungen der benötigten Algorithmen steht die Verwendung unterschiedlichster Schlüssel- und Zertifikatsressourcen im Vordergrund. Darüber hinaus muss die Verwendung von Crypto-Tokens ermöglicht werden, die neben der Bereitstellung von Schlüsseln und Zertifikaten auch die kryptographischen Operationen selbst durchführen (PKCS#11-Module, SmartCards etc.).

3.4.1.1. Aufgabe der Schnittstelle

Im JAVA-Umfeld hat sich für die Durchführung kryptographischer Funktionen der Einsatz von JCA/JCE bewährt. Die JCA/JCE-Schnittstellen erlauben es dem Nutzer, eigene Service-Provider zu schreiben und zu registrieren, so dass hier kein neues Interface definiert werden musste, sondern auf ein bewährtes Konzept zurückgegriffen werden konnte.

Im Rahmen der OSCI-Spezifikation sind die folgenden Algorithmen vorgeschrieben worden. Außerdem wird eine Methode zur sicheren Erzeugung von Zufallszahlen benötigt.

Verschlüsselung
Signatur (Hashen)
- RIPMED-160
- SHA-1

3.4.1.2. Aufbau der Schnittstelle

Die JAVA-Sicherheitsarchitektur stellt mit der JCA/JCE-Architektur bereits Schnittstellen, sogenannte Service Provider Interfaces zur Verfügung, die die Anbindung unterschiedlicher Implementierungen ermöglichen. Für die Bibliothek sind dabei die Interfaces

javax.crypto.CipherSpi
java.security.MessageDigestSpi
java.security.SecureRandomSpi
javax.crypto.KeyGeneratorSpi

von Bedeutung.

Für die Anbindung von Crypto-Tokens wurden zwei abstrakte Klassen für die sicherheitsrelevanten Funktionen Entschlüsseln und Signieren vorgesehen:

de.osci.osci12.common.Decrypter
de.osci.osci12.common.Signer

Anwender müssen Implementierungen dieser Klassen an die Rollenobjekte für eine OSCI-Nachricht bzw. einen OSCI-Dialog übergeben.

3.5. Programmierschnittstelle (API) der OSCI-Bibliothek

Im folgenden Abschnitt werden die Klassen, Interfaces und Resource-Dateien behandelt, die Anwendungsprogrammierer für den Betrieb der OSCI-Bibliothek benötigen.

3.5.1. Akteure der OSCI-Bibliothek

Die Akteure gemäß dem Rollenmodell der OSCI-Spezifikation werden in folgenden Objekten gehalten:

Intermed (beschreibt einen Intermediär)
Originator (beschreibt einen Sender)
Addressee (beschreibt einen Empfänger)
Author (beschreibt einen Autor)
Reader (beschreibt einen Leser)

Die Rollen in einer OSCI-Sitzung ändern sich in den meisten Fällen nicht, sodass die Konstruktoren aller Rollen nahezu gleich aussehen. Eine Ausnahme bildet das Reader-Objekt, weil die OSCI-Spezifikation das Element SignatureCertificateOtherReader nicht verwendet und damit Signaturen des Reader (Rückantworten) nicht benötigt werden.

Es gibt zwei Möglichkeiten zum Aufbau der Rollen-Objekte:

Als Besitzer der privaten Schlüssel: Hier wird dem Konstruktor zum Signieren ein Signer-Objekt bzw. zum Entschlüsseln von Rückantworten ein Decrypter-Objekt übergeben. Beide Parameter können unter Umständen NULL sein. Bei einem NULL-Parameter wird keine Signatur bzw. Entschlüsselung gewünscht. Beispiel: Originator(Signer signer, Decrypter decrypter)
Als Besitzer der öffentlichen Schlüssel: Hier wird dem Konstruktor ein X509-Signaturzertifikat zur Signaturprüfung bzw. ein X509-Chiffrierzertifikat zur Verschlüsselung übergeben. Beide Parameter können unter Umständen NULL sein. Bei einem NULL-Parameter wird keine Signaturprüfung bzw. Verschlüsselung gewünscht. Beispiel: Addressee(X509Certificate signatureCertificate, X509Certificate cipherCertificate)

Abbildung 4. Überblick der Akteure der OSCI-Bibliothek

3.5.2. Verwaltung von OSCI-Dialogen

Der Begriff des Dialogs betrifft die Auftragsebene von OSCI-Transport. Auftrag-Antwort-Paare werden zu Dialogen zusammengefasst. Jeder Dialog umfasst mindestens ein Auftrag-Antwort-Paar. Ein Dialog besteht zwischen genau einem Client und einem Supplier. Dialoge sind in der OSCI-Spezifikation von elementarer Bedeutung. Zum Beispiel muss vor dem Abholen von Nachrichten ein Dialog eröffnet werden, um die Berechtigung hierfür zu erlangen. Die Verwaltung der Dialoginformationen über mehrere OSCI-Nachrichten hinweg übernimmt der Dialog-Handler der OSCI-Bibliothek.

3.5.2.1. Aufgaben des Dialog-Handler

Die OSCI-Bibliothek verwaltet für den Nutzer auch die Dialoge, das heißt, es wird die Richtigkeit des Tripels aus ConversationID, Sequenz-Nummer und Supplier betrachtet, sowie die Richtigkeit der Challenge- und Responsewerte.

Folgende Aufgaben übernimmte der Dialog-Handler zur Dialogverwaltung:

Verwaltung der OSCI-Sicherheitsmechanismen zur Absicherung des Dialogs. Dazu dienen Methoden zur Einstellung und zum Check von
- Challenge-Response
- Sequence-Number und Conversation-ID der Nachricht
Festlegung konkreter Einstellungen für das jeweilige Request/Response-Tupel (bzw. auch die gesamte Session) wie
- Attribut checkSignatures-Signaturen der empfangenen Nachrichten prüfen (optional für einen Client)

Zusätzlich zu den Dialog-relevanten Informationen wird der Dialog-Handler auch als Konfigurationsinstrument benutzt. Jeder OSCI-Nachricht muss im Konstruktor ein Dialog-Handler übergeben werden, sodass statische Informationen, die sich während einer Sitzung nicht ändern, ebenfalls im Dialog-Handler mitgeführt werden.

Folgende Konfigurationsinformationen werden im Dialog-Handler verwaltet:

Konfiguration der Schnittstellen-Implementierung:
Somit werden die meisten Schnittstellen im Dialog-Handler definiert.
Weiter werden hier die Referenzen auf folgende Akteur-Objekte einer OSCI-Kommunikation gehalten:
- Originator (Sender der Nachricht, Client)
- Intermediär (Supplier)
Diese Informationen werden zusammen mit der Transportschicht im Konstruktor des Dialog-Handler übergeben.
Informationen über Transportverschlüsselung, Signatur und Spracheinstellung (DesiredLanguages-Element)

Jede OSCI Request/Response-Folge erhält die Referenz auf die Dialog-Handler-Instanz, um im konkreten OSCI-Request die entsprechenden aktuellen Attributwerte setzen und die korrespondierenden Werte des jeweiligen Response auf Korrektheit gemäß OSCI-Spezifikation prüfen zu können. Nach erfolgreicher Prüfung werden die Attribute zur Dialogabsicherung jeweils sofort auf die Werte gesetzt, die für die nächste Request-Response-Sequenz gefordert sind.

Für die Initiierung einer neuen Dialogabfolge können die Attributwerte mit resetControlBlock() neu initialisiert werden.

In dem folgendem Schaubild werden die vom Dialog-Handler verwalteten Objekte dargestellt.

Abbildung 5. Überblick über den Dialog-Handler

3.5.3. OSCI-Nachrichtenobjekte

Die OSCI-Kommunikation verläuft generell in Form von Request/Response- Szenarien. Die OSCI-1.2-Spezifikation definiert insgesamt 20 verschiedene Nachrichtentypen, nämlich 10 Auftrags- und die dazugehörigen 10 Antwortnachrichten.

Für jeden Nachrichtentyp stellt die OSCI-Bibliothek eine repräsentierende Klasse bereit. Diese Klassen befinden sich in dem Package de.osci.osci12.messagetypes. Die gemeinsame Superklasse aller Auftragsnachrichten ist die Klasse de.osci.osci12.messagetypes.OSCIRequest, die der Antwortnachrichten de.osci.osci12.messagetypes.OSCIResponseTo. Diese beiden Klassen sind wiederum von der Klasse de.osci.osci12.messagetypes.OSCIMessage abgeleitet.

3.5.3.1. Erstellen von OSCI-Nachrichten

Entsprechend den in der OSCI-Spezifikation den Benutzern zugewiesenen Aufgaben müssen Anwendungen OSCI-Nachrichten erzeugen können. Sie werden vom Benutzer erstellt und vom Intermediär geparst:

Tabelle 1. Nachrichtentypen (Erstellen) und ihre zugehörigen JAVA-Klassen

Nachricht	Quellcodedateiname
Dialogintialisierungsauftrag	InitDialog.java
Dialogendeauftrag	ExitDialog.java
MessageID-Anforderungsauftrag	GetMessageId.java
Zustellungsauftrag	StoreDelivery.java
Zustellungsabholauftrag	FetchDelivery.java
Laufzettelabholauftrag	FetchProcessCard.java
Weiterleitungsauftrag	ForwardDelivery.java
Annahmeantwort	ResponseToAcceptDelivery.java
Abwicklungsauftrag	MediateDelivery.java
Bearbeitungsantwort	ResponseToProcessDelivery.java

Diese Klassen besitzen öffentliche Konstruktoren und können über setX()-Methoden mit den erforderlichen Informationen bestückt werden. Weiterhin bieten die folgenden Klassen die Möglichkeit, Inhaltsdaten in die Nachricht aufzunehmen:

Zustellungsauftrag
Weiterleitungsauftrag
Annahmeantwort
Abwicklungsauftrag

Zur Aufnahme von Inhaltsdaten bedienen sich die Klassen folgender Methoden:

addEncryptedData(de.osci.osci12.messageparts.EncryptedData encData)
addContentContainer(ContentContainer container)

Mit Ausnahme der beiden Antwortnachrichten ResponseToAcceptDelivery und ResponseToProcessDelivery besitzen alle Klassen außerdem eine öffentliche send()-Methode, mit der der Versand der Nachricht veranlasst wird. Die Methode gibt als Rückgabeparameter ein korrespondierendes Antwortnachricht-Objekt zurück.

3.5.3.2. Parsen von Nachrichten

Die verbleibenden Nachrichtentypen werden von Anwendungen nur als Ergebnis der send-Methoden zurückgegeben (diese Nachrichtentypen werden nur vom Intermediär erstellt) oder, im Falle der beiden Auftragsnachrichten ResponseToAcceptDelivery und ResponseToProcessDelivery, von der statischen Methode parseStream(InputStream in) des IncomingMSGParser (passiver Empfänger) erstellt. Die Klassen haben daher keine öffentlichen Konstruktoren. Zur Auswertung der Nachrichten stehen in den Klassen entsprechende getX(...)-Methoden, wie z.B. getFeedback(), bereit.

Folgende OSCI-Nachrichten werden vom Intermediär erstellt und vom Client geparst:

Tabelle 2. Nachrichtentypen (Parsen) und ihre zugehörigen JAVA-Klassen

Nachricht	Quellcodedateiname
Dialogintialisierungsantwort	ResponseToInitDialog.java
Dialogendeantwort	ResponseToExitDialog.java
MessageID-Anforderungsantwort	ResponseToGetMessageId.java
Zustellungsantwort	ResponseToStoreDelivery.java
Zustellungsabholantwort	ResponseToFetchDelivery.java
Laufzettelabholauftrag	ResponseToFetchProcessCard.java
Weiterleitungsantwort	ResponseToForwardDelivery.java
Annahmeauftrag	AcceptDelivery.java
Abwicklungsantwort	ResponseToMediateDelivery.java
Bearbeitungsauftrag	ProcessDelivery.java

Eingehende Bescheibungen der Methoden der speziellen OSCI-Nachrichten-Klassen finden sich im Anhang.

Bei folgenden OSCI-Nachrichtentypen müssen nach dem Empfang die Inhaltsdaten ausgewertet werden:

Zustellungsabholantwort
Annahmeauftrag
Abwicklungsantwort
Bearbeitungsauftrag

Zum Auswerten dieser Inhaltsdaten können die ContentContainer entweder mit der Methode getContentContainer() direkt aus der Nachricht gelesen oder zuvor entschlüsselt werden. Zum Entschlüsseln eines EncryptedData-Objekts sind folgende Schritte notwendig:

Analyse des verschlüsselten Datencontainers durch die Methode getReaders(); durch diese Methode werden die Leser dieses Datencontainers bekannt gegeben.
Auf Grundlage des EncryptedData-Objekts wird die Methode decrypt(Role addressee) aufgerufen. Als Parameter muss ein Role-Objekt übergeben werden, welches einen Decrypter enthält.
Als Ergebnis gibt die Methode decrypt(Role addressee) ein MessagePart-Objekt zurück. Dieses muss noch Typ-überprüft werden. Mögliche Return-Typen sind hier Attachment, ContentContainer und EncryptedData.
Auswerten des MessageParts entsprechend der jeweiligen getX()-Methoden der Klassen von Attachment, ContentContainer und EncryptedData.

Nähere Informationen zur Weiterverarbeitung der ContentContainer finden sich in dem Kapitel Inhaltsdaten-Container.

dem folgendem Schaubild wird beispielhaft die Struktur der OSCI-Nachrichtenobjekte in der OSCI-Bibliothek dargestellt.

Abbildung 6. Klassendiagramm der OSCI-Nachrichtentypen

3.5.4. Inhaltsdaten-Container

OSCI-Nachrichten, die zur Übermittlung von Inhaltsdaten (in Form von XML-Data oder unstrukturiert als Binär-Daten) benutzt werden, enthalten immer ContentContainer zur Aufnahme dieser Informationen.

Ein ContentContainer beinhaltet Content-Elemente (und ggf. EncryptedData-Elemente), die wiederum die auftragsspezifischen Inhaltsdaten aufnehmen. Auf der Empfängerseite werden die Inhaltsdaten eines ContentContainers ausgewertet. OSCI stellt ein sicheres Übermittlungsprotokoll dar, mit dem sich Inhaltsdaten in beliebiger Form (insbesondere XML-Inhaltsdaten) nachprüfbar übertragen lassen. Das Ergebnis dieser Übertragung besteht dann in der Auswertung eben dieser Inhaltsdaten im ContentContainer sowie der Signaturen.

ContentContainer sind also Einheiten, die nur als Ganzes signiert und/oder verschlüsselt werden können. Einer OSCI-Nachricht können beliebig viele dieser ContentContainer übergeben werden. Somit kann es leicht vorkommen, dass Teile (nämlich einzelne ContentContainer) einer Nachricht unverschlüsselte Informationen enthalten, während gleichzeitig andere ContentContainer derselben Nachricht schutzwürdige Inhalte aufnehmen und deswegen signiert und/oder verschlüsselt sind.

Zum leicheren Verständnis sollen einige weitere Bibliotheks-Klassen vorgestellt werden:

3.5.4.1. Content-Klasse

Content-Objekte enthalten entweder XML-Inhaltsdaten oder eine Referenz auf ein Attachment. Alle wichtigen Informationen werden schon mit dem Konstruktor gesetzt. Das Content-Objekt stellt keine Methoden zum Signieren (diese befinden sich auf ContentContainer-Ebene) oder zum Verschlüsseln (siehe EncryptedData-Klasse) bereit. Inhaltsdaten, seien es nun XML-Daten oder Binär-Daten, werden immer erst einmal einem Content hinzugefügt. Ggf. mehrere Content-Objekte bilden Container zum Bündeln von Inhaltsdaten. Erst auf der ContentContainer-Ebene kann die Signatur bzw. Verschlüsselung erfolgen. Die Content-Klasse stellt folgende Konstruktoren zur Verfügung:

Content(Attachment attachment)
Content(java.io.InputStream ins)
Content(String data)

Daneben gibt es mehrere Methoden zum Auswerten der eingestellten Daten.

3.5.4.2. ContentContainer

Die ContentContainer-Klasse stellt einen OSCI-Auftragscontainer dar. Ein ContentContainer kann einen oder mehrere Content- (XML-Datencontainer) oder EncryptedData-Objekte enthalten. Attachments werden als Content-Objekte eingestellt, die eine Referenz auf das Attachment enthalten. Daten, die in gleicher Weise zu behandeln sind (Signieren und/oder Verschlüsseln), werden zu einem ContentContainer zusammengeführt. Sobald Inhaltsdaten unterschiedlich signert und/oder verschlüsselt werden sollen, müssen diese auf verschiedene ContentContainer verteilt werden; die Übertragung erfolgt zusammen in einer OSCI-Nachricht.

Die Methoden zum Bearbeiten von Content-Objekten:

public Content[] getContents()
Liefert die enthaltenen Content-Objekte zurück.
public void addContent(Content content)
Fügt ein Content-Objekt hinzu.
public void removeContent(Content content, boolean removeAttachment)
Entfernt ein Content-Objekt.

Die Methoden zum Bearbeiten von EncryptedData-Objekten:

public EncryptedDataOSCI[] getEncryptedData()
Liefert die enthaltenen EncryptedData-Objekte.
addEncryptedData(EncryptedDataOSCI encryptedDataElement)
Fügt ein EncryptedData-Objekt hinzu.
public void removeEncryptedData(EncryptedDataOSCI encryptedDataElement, boolean removeAttachment)
Entfernt ein EncryptedData-Objekt.

Für das Signieren eines kompletten ContentContainers steht folgende Methode zu Verfügung:

public void sign(Role role, String signatureAlgorithm)
Diese Methode übernimmt das Signieren des kompletten ContentContainers einschließlich in Content-Elementen referenzierter Attachments. Für Mehrfachsignaturen kann diese Methode mehrfach mit verschiedenen Rollen-Objekten aufgerufen werden.

Die Methoden zum Auswerten des ContentContainers:

public Role[] getRoles()
Liefert alle beteiligten Rollen-Objekte (Verschlüsselung und Signatur).
public Role[] getSigners()
Liefert alle beteiligten Signatur-Rollen-Objekte.

3.5.4.2.1. Beispiele für das Zusammenstellen von ContentContainern

In folgendem Beispiel werden dem ContentContainer zwei Content-Objekte mit XML-Inhaltsdaten hinzugefügt.

Abbildung 7. ContentContainer mit zwei Content-Objekten

In folgendem Beispiel werden ein Content-Objekt mit XML-Inhaltsdaten und ein Content-Objekt mit einem Attachment als Inhalt dem ContentContainer hinzugefügt.

Abbildung 8. ContentContainer mit Content-Objekten und Attachment

3.5.4.3. EncryptedData-Klasse

Die EncryptedData-Klasse wird benutzt, um XML-Encryption-Elemente zu erzeugen, d.h. Inhaltsdaten zu verschlüsseln. Einer EncryptedData-Klasse kann ein ContentContainer oder wiederum ein EncryptedData-Objekt übergeben und mit den entsprechenden Methoden verschlüsselt werden. Die EncryptedData-Klasse stellt einen Datencontainer für verschlüsselte Daten in einer OSCI-Nachricht dar. Auch hier werden die wichtigen Informationen beim Konstruktor übergegeben.

Die Konstruktoren sehen folgendermaßen aus:

EncryptedData(javax.crypto.SecretKey secretKey, String encryptionMethodAlgorithm, ContentContainer coco)
Dieser Konstruktor bekommt ein SecretKey-Objekt zum symmetrischen Verschlüsseln der Inhaltsdaten, den symmetrischen Verschlüsselungsalgorithmus sowie den vorbereiteten Inhaltsdatencontainer (ContentContainer) mit den eigentlichen, zu verschlüsselnden Informationen.

Durch diese Konstruktoren sind die wichtigsten Informationen gesetzt. Für das eigentliche Verschlüsseln müssen folgende Methoden aufgerufen werden:

encrypt(de.osci.osci12.roles.Role reader)
Verschlüsselt den symmetrischen Schlüssel und fügt ihn als EncryptedKey-Element dem EncyptedDataOSCI-Element hinzu.
encrypt(byte[] encryptedSymKey,de.osci.osci12.roles.Role reader)
Es existiert bereits ein verschlüsselter symmetrischer Schlüssel, der hier übergeben werden kann. Als zweiter Parameter wird der Leser der Nachricht eingetragen.

Die encrypt-Methoden können mehrfach nacheinander aufgerufen werden um für weitere Adressaten zu verschlüsseln. Die hinzugefügten Empfänger-Zertifikate werden beim Hinzufügen des EncryptedData-Objekts zur OSCI-Nachricht übertragen.

Folgendes Sequenzdiagramm verdeutlicht das Erstellen eines verschlüsselten Inhaltsdatencontainers:

Abbildung 9. Verschlüsselten Inhaltsdatencontainers

Im obigen Diagramm wird dem Konstruktor von EncryptedDataOSCI ein schon bestehender ContentContainer übergeben, ein neuer Leser erstellt und die Verschlüsselung des Inhaltsdatencontainers mit dem Zertifikat des Lesers durchgeführt.

3.5.4.4. Beispielszenarien für das Zusammenstellen von Inhaltsdaten

Exemplarisch soll der Vorgang des Hinzufügens eines signierten und verschlüsselten Inhaltsdatencontainers zu einer Nachricht vorgestellt werden:

Erstellen eines Content-Objekts und Übergabe der XML-Inhaltsdaten an das Content-Objekt (n mal)
Hinzufügen der Content-Objekte zu dem ContentContainer
Signieren des ContentContainers mit dem übergebenen Author-Objekt
Einhängen des ContentContainers in ein EncryptedData-Objekt
Verschlüsseln des EncryptedData-Objekts (mit Hilfe eines Addressee-Objekts)
Hinzufügen des EncryptedData-Objekts zu der OSCI-Nachricht

Im Sourcecode sieht der Ablauf folgendermaßen aus:

      // Vorbereitungen; Erstellen der Rollen-Objekte
      X509Certificate empfaenger = Tools.createCertificate(new 
               FileInputStream("Empfaenger.cer"));
      de.osci.osci12.roles.Reader leser= new de.osci.osci12.roles.Reader(empfaenger);
      Addressee addressee = new Addressee(null, empfaenger);
      DialogHandler dialog=this.getDialogHandler(1);
      // Erstellen der OSCI-Nachricht mit ihren Rollen-Objekten
      StoreDelivery osci = new StoreDelivery(dialog, addressee);
      // Erstellen eines ContentContainers
      ContentContainer coco = new ContentContainer();
      // Hinzufügen eines Contents
      coco.addContent(new Content("<xml>Inhaltsdaten in XML-Form</xml>"));
      // Signieren des Contentcontainers
      coco.sign(new Author (new AuthorSigner(),null),
                Constants.SIGNATURE_ALGORITHM_RSA_SHA1);
      // Erzeugen eines symmetrischen Schluessels
      javax.crypto.SecretKey secretKey = Crypto.createTDESKey();
      // Erstellen eines Encrypteddata-OSCI-Objekts
      EncryptedDataOSCI encData= new EncryptedDataOSCI(secretKey,
          Constants.SYMMETRIC_CIPHER_ALGORITHM_TDES,coco);
      // Verschluesseln der Inhaltsdaten
      encData.encrypt(leser);
      // Hinzufuegen der fertigen Inhaltsdaten zur OSCI-Nachricht
      osci.addEncryptedData(encData);

Damit wurde eine einfach signierte, verschlüsselte Nachricht erstellt. Um Mehrfachverschlüsselung zu erreichen, müssen dem ContentContainer anstatt dem Content bereits verschlüsselte Nachrichten hinzugefügt werden.

Für das Versenden mit Mehrfachverschlüsselung (Vier-Augen-Prinzip) müssen folgende Schritte durchgeführt werden:

Erstellen eines Content-Objekts und Übergabe der XML-Inhaltsdaten an den Content (x mal)
Hinzufügen der Content-Objekte zu dem ContentContainer
Verschlüsseln des ContentContainers mit der EncryptedData-Klasse und dem ersten Reader-Objekt
Hinzufügen des EncryptedData-Objekts zu einem neuen ContentContainer
Erstellen eines neuen Content-Objekts und Hinzufügen der Content-Objekte zu dem ContentContainer
Signieren des zweiten ContentContainers mit dem übergebenen Author-Objekt
Verschlüsseln des zweiten ContentContainers mit der EncryptedData-Klasse und dem zweiten Reader-Objekt
Hinzufügen des EncryptedData-Objekts zu der OSCI-Nachricht

3.6. Fehlerbehandlung und Fehlercodes

Entsprechend den Vorgaben der OSCI-Transport-1.2-Spezifikation wird zwischen Fehlermeldungen auf Nachrichtenebene und Rückmeldungen auf Auftragsebene unterschieden. Erstere stellen grundsätzlich echte Fehler dar. Sie werden von den auslösenden Methoden je nach Art des Fehlers durch eine der beiden folgenden Exceptions angezeigt:

SOAPClientException
SOAPServerException

Diese Exceptions enthalten den OSCI-Fehlercode. Die Methode getMessage() (bzw. getLocalizedMessage()) liefert den dazugehörigen Text in der Sprache des default-Locale.

Bei Rückmeldungen auf Auftragsebene wird zwischen Warnungen und Fehlern unterschieden. Während Erstere (OSCI-Code beginnend mit 9) eine Exception vom Typ OSCIErrorException auslösen, wird bei Warnungen (OSCI-Code beginnend mit 3) die Verarbeitung der betreffenden Nachricht fortgesetzt. Warnungen müssen von der Anwendung selbst durch Auswertung des Feedback-Eintrags der Antwortnachricht ermittelt werden.

Fehler, die innerhalb des Bibliothekscodes auftreten, werden durch verschiedene Exceptions angezeigt. Sofern es sich nicht um Exceptions der JAVA-API handelt, sind alle diese Exceptions von OSCIException abgeleitet und erben die o.g. Implementierung der Methode getMessage().

3.7. Aufbau der Bibliothek

Die OSCI-Bibliothek besteht aus einer Vielzahl von Klassen, die in ihrer Gesamtheit die Szenarien der OSCI-Spezifikation abdecken sollen (Client- und Supplierseitig). Die Klassen der OSCI-Bibliothek sind alle in dem Package de.osci.osci12 untergebracht. Unterhalb dieses Packages befinden sich die Untergeordneten Packages, welche der Anwendungsentwickler benutzt. In dem folgenden Schaubild wird die Packagestruktur (mit ihren Klassen) dargestellt.

Abbildung 10. Packageübersicht der OSCI-Bibliothek-

Erläuterung zu der Grafik:

de.osci.osci12.common. Dieses Package enthält allgemeine Klassen, welche zumeist von vielen anderen Klassen aus verschiedenen Packages benutzt werden. Package-übergreifende Klassen wie z.B der Dialog-Handler, die Default-Implementierung des DialogFinder und der DataSource-Klasse sowie allgemeine Konstanten und Helferklassen können in diesem Package gefunden werden.
de.osci.osci12.extinterfaces. Die externen Schnittstellen der Bibliothek. In diesem Package können alle externen Schnittstellen gefunden werden. Dies betrifft die Interfaces sowie die abstrakten Klassen der OSCI-Spezifikation. Weitere Informationen finden sich im Kapitel 'Schnittstellen'.
de.osci.osci12.messageparts. In diesem Package befinden sich OSCI-Nachrichtenbestandteile. Die in diesem Package zu findenden Klassen sind Bestandteile von OSCI-Nachrichten, welche in vielen Nachrichten Verwendung finden. Zu finden sind hier z.B. Repräsentationen der OSCI-Elemente Content-Container, Content, EncryptedData, Inspection, TimeStamp uvm.
de.osci.osci12.messagetypes. Dieses Package beinhaltet die Repräsentationen der OSCI-Nachrichtenobjekte. Für jede OSCI-Nachricht, ob Request oder Response, findet man in diesem Package eine gleichnamige Klasse. Weitere Informationen finden sich im Kapitel 'OSCI-Nachrichtenobjekte'.
de.osci.osci12.roles. Die Akteure der OSCI-Spezifikation. In diesem Package werden alle in der OSCI-Spezifikation erwähnten Akteure als JAVA-Klasse abgebildet. Weitere Informationen finden sich im Kapitel 'Akteure der OSCI-Bibliothek'.

Folgende Auflistung enthält weitere interne Packages, die vom Benutzer der OSCI-Bibliothek nicht direkt benutzt werden:

encryption
signature
soapheader

3.8. Usecases

3.8.1. Use Case Nr. 1: Senden eines Zustellungsauftrags

Use Case Nr.	1
Use Case Name	Senden eines Zustellungsauftrags
Geschäftsvorfall	Versand einer Nachricht in Form eines OSCI-Zustellauftrags
Initiierender Aktor	Sender
Weitere Aktoren	Intermediär
Kurzbeschreibung	Versenden einer OSCI-Nachricht mit Inhaltsdatencontainer und Signaturen an den Intermediär
Vorbedingungen	Verwendete Module müssen konfiguriert sein (Crypto, Transport und Sprache) Die Informationen/Zertifikate der beteiligten Personen/Institutionen müssen eingestellt werden (Sender, Empfänger und Intermediär)
Resultate	Zustellungsantwort mit Informationen zu dem Zustellungsauftrag
Erstellen eines Originator-Objekts ori=new Originator(new MySigner(...), new MyDecrypter(...) Erstellen eines Intermed-Objekts intermed=new Intermed(null,x509IntermedCert,"http://uri/des/intermeds" Dialog-Handler-Objekt für die Steuerung des Dialogablaufs anlegen DialogHandlerClient dh = new DialogHandlerClient(ori,intermed,transportModul); Erstellen eines OSCI-Nachrichtenobjekts (MessageID-Anforderung), Versenden der Nachricht und Einlesen der Rückantwort GetMessageID msgIDReq= new GetMessageID(dh) ResponseToGetMessageID msgIDRsp=msgIDReq.send() Erstellen eines OSCI-Nachrichtenobjekts (Zustellungsauftrag) StoreDelivery strDeliReq= new StoreDelivery(dh); strDeliReq.setMsgID(msgIDRsp.getMessageID) Erstellung eines Inhaltsdatencontainers mit Nutzdaten (XML) Content content= new Content("hier nun die Nutzdaten"); ContentContainer coco=new ContentContainer (); coco.addContent(content); Signieren der Inhaltsdaten coco.sign(new Author(...),"RSA_SHA1") Inhaltsdaten dem Nachrichtenobjekt zuordnen strDeliReq.addContentContainer(coco); Verschicken der OSCI-Nachricht ResponseToStoreDelivery strDeliRsp=strDeli.send() Überprüfen der gerade gesendeten Nachricht ProcessCard proCard=strDeliRsp.getProcessCard()
Alternative Pfade	Keine
Fehlersituationen, Ausnahmen	OSCI-Fehlercodes des Typs 9*** lösen Exceptions aus; andere Fehler, Warnungen und Informationen können den OSCI-FeedBack-Objekten der Nachricht entnommen werden.

3.8.2. Use Case Nr. 2: Senden eines Zustellungsabholauftrags

Use Case Nr.	2
Use Case Name	Senden eines Zustellungsabholauftrags
Geschäftsvorfall	Ein Empfänger holt eine Nachricht aus seinem Postfach ab.
Initiierender Aktor	Wegzugsmeldebehörde
Weitere Aktoren	Intermediär
Kurzbeschreibung	Abholen einer OSCI-Nachricht vom Intermediär als Empfänger/Leser
Vorbedingungen	Die verwendeten Module müssen konfiguriert sein (Crypto, Transport und Sprache). Die Informationen/Zertifikate der beteiligten Personen/Institutionen müssen eingestellt werden (Sender und Intermediär). Der Privatschlüssel des Empfängers (privateKey) muss vorhanden sein.
Resultate	Zustellungsabholantwort mit dem Inhalt des Zustellungsauftrags
Erstellen eines Originator-Objekts ori=new Originator(new MySigner(...), new MyDecrypter(...) Erstellen eines Intermed-Objekts intermed=new Intermed(null,x509IntermedCert,"http://uri/des/intermeds" Dialog-Handler-Objekt für die Steuerung des Dialogablaufs anlegen DialogHandlerClient dh = new DialogHandlerClient(ori,intermed,transportModul); Dialog-Initialisierungsnachricht erzeugen und versenden, Antwortobjekt einlesen ResponseToInitDialog initDialogRsp initDiaRsp = new InitDialog(dh).send(); Zustellungsabholauftrag anlegen, versenden und Antwortobjekt einlesen FetchDelivery fetchDev = new FetchDelivery(dh) fetchDev.setReceptionOfDelivery(new Date(...)) ResponseToFetchDelivery fetchDevRsp = fetchDev.send(); Inhaltsdatencontainer extrahieren, ggf. entschlüsseln/Signatur prüfen, Daten auslesen ContentContainer coco[] = fetchDevRsp.getContentContainer(); EncryptedDataOSCI encData[] = fetchDevRsp.getEncryptedData(); [n-mal]: encData[n].decrypt(new Reader(...)) [n-mal m-mal]: coco[n].getContents()[m].getContentStream(); [n-mal]: coco[n].getAttachments()
Alternative Pfade	Keine
Fehlersituationen, Ausnahmen	Beim Prüfen der Inhaltsdatensignaturen und beim Decrypten des Inhaltsdatencontainers können Fehler auftreten, welche zu Exceptions führen. Auch beim Überprüfen des DialogControlblocks werden falsche Dialogkontexte durch Fehlermeldungen beantwortet.

3.8.3. Use Case Nr. 3: Senden eines Weiterleitungsauftrags

Use Case Nr.	3
Use Case Name	Senden eines Weiterleitungsauftrags
Geschäftsvorfall	Versand einer Nachricht in Form eines OSCI-Weiterleitungsauftrags
Initiierender Aktor	Sender eines Weiterleitungsauftrags
Weitere Aktoren	Intermediär
Kurzbeschreibung	Versenden einer OSCI-Nachricht mit Inhaltsdatencontainer und Signaturen an den Intermediär. Als Ergebnis wird eine Antwort vom Fachverfahren erwartet.
Vorbedingungen	Verwendete Module müssen konfiguriert sein (Visualisierung, Crypto, Transport und Sprache) Die Informationen/Zertifikate der beteiligten Personen/Institutionen müssen eingestellt werden (Sender, Empfänger und Intermediär).
Resultate	Weiterleitungsantwort mit Informationen zur Weiterleitung.
Erstellen eines Originator-Objekts ori=new Originator(new MySigner(...), new MyDecrypter(...) Erstellen eines Intermed-Objekts intermed=new Intermed(null,x509IntermedCert,"http://uri/des/intermeds" Dialog-Handler-Objekt für die Steuerung des Dialogablaufs anlegen DialogHandlerClient dh = new DialogHandlerClient(ori,intermed,transportModul); Erstellen eines OSCI-Nachrichtenobjekts (MessageID-Anforderung), Versenden der Nachricht und Einlesen der Rückantwort GetMessageID msgIDReq= new GetMessageID(dh) ResponseToGetMessageID msgIDRsp=msgIDReq.send() Erstellen eines OSCI-Nachrichtenobjekts (Weiterleitungsauftrag) ForwardDelivery strForwReq= new ForwardDelivery(dh); strForwReq.setMsgID(msgIDRsp.getMessageID) Erstellung eines Inhaltsdatencontainers mit Nutzdaten (XML) Content content= new Content("hier nun die Nutzdaten"); ContentContainer coco=new ContentContainer (); coco.addContent(content); Signieren der Inhaltsdaten coco.sign(new Author(...),"RSA_SHA1") Inhaltsdaten dem Nachrichtenobjekt zuordnen strDeliReq.addContentContainer(coco); Verschicken der OSCI-Nachricht ResponseToForwardDelivery strForwRsp= strForwReq.send() Überprüfen der gerade gesendeten Nachricht ProcessCard proCard= strForwRsp.getProcessCard()
Alternative Pfade	Keine
Fehlersituationen, Ausnahmen	OSCI-Fehlercodes des Typs 9*** lösen Exceptions aus; andere Fehler, Warnungen und Informationen können dem OSCI-FeedBack-Objekten der Nachricht entnommen werden.