CIB doXisign technischer Leitfaden

1. Lieferumfang

CIB doXisign wird in Form einer einzelnen Datei namens doxisign-<version>.zip geliefert. Diese enthält:

Dieselbe war-Datei ist für Linux/Solaris/AIX und für Windows geeignet. Mit dieser war-Datei allein ist CIB doXisign bereits in einem Servlet-Container wie Tomcat lauffähig.

2. Überblick

CIB doXisign ist eine Web Applikation mit einem clientseitigen und einem serverseitigen Anteil.

Die Serverseite übernimmt im Wesentlichen die folgenden Aufgaben:

• Verwaltung von laufenden Signaturprozessen
• Digitales Signieren von Dokumenten
• Konfiguration eigener Zertifikate
• Optional: Ansteuerung einer Time Stamp Authoritiy für signierte Zeitstempel
• Optional: Erstellen eines Signaturverlaufsprotokolls
• Optional: Authentifizierung der Benutzers

Die Clientseite übernimmt folgende Aufgaben:

• Öffnen des Signaturpads für den Unterzeichnenden.
• Entgegennahme des Unterschriftenbildes (Touchpad, Maus, Schrift, Bild)
• Optional: Entgegennahme eines persönlichen Zertifikates
• Optional: Möglichkeit ein mobiles Endgerät mit dem Signaturprozess zu verbinden.
• Optional: Eingabe der Benutzerdaten für die Authentifizierung

In diesem Bereich werden die Funktionen nur knapp beschrieben, eine detaillierte Auflistung aller Möglichkeiten findet sich im Bereich „REST SCHNITTSTELLE“

2.1. Signaturprozess

Ein Dokument kann grundsätzliche mehrere Unterschriftenfelder besitzen. Diese Felder sollten innerhalb eines Signaturprozesses unterschrieben werden.

Wird ein Signaturprozess zum Unterschreiben aller Signaturfelder wiederverwendet, nennen wir ihn dokumentbasiert. Genauso kann aber auch für jedes Signaturfeld ein neuer Signaturprozess erzeugt werden. Diese Prozesse sind dann inhaltlich signaturfeldbasiert.

Die Auswahl eines dokumentbasierten oder signaturfeldbasierten Ablaufszenarios wirkt sich wie folgt aus:

• Speicherung von prozessbezogenen Daten in der integrierenden Applikation: Beim dokumentbasierten Ablaufszenario muss sich die aufrufende Anwendung die Prozess-ID merken, damit der Prozess pro Unterschriftenfeld wiederverwendet werden kann. Beim signaturfeldbasierten Ablaufszenario muss sich die integrierende Anwendung keinerlei Daten zum Signaturprozess merken.
• Signaturverlaufsprotokolle: Bei der Erstellung von Signaturverlaufsprotokollen, ist beim dokumentbasierten Ablaufszenario einem Dokument nur ein Protokoll zugeordnet, wohingegen beim signaturfeldbasierten Szenario einem Dokument mehrere Protokolle zugeordnet werden müssen.

Außerdem kann festgelegt werden welche Angaben der Unterzeichner machen bzw. welche Daten er verifizieren muss.

2.2. Signatur-Session

Eine Signatur-Session bezeichnet den Vorgang des Unterschreibens von einem Signaturfeld im Dokument. Signatur-Sessions werden durch die integrierende Anwendung von CIB doXisign für einen Signaturprozess erzeugt. Das aufrufende System kann beim Erstellen der Session Daten zum Benutzer mitliefern. Diese dienen im Wesentlichen dazu die Unterschrift des Benutzers zu speichern und doppelte Authentifizierung zu Vermeiden.

2.3. Signatur-Token

Dieses Token wird zusätzlich mit der Unterschrift, dem Zeitstempel und dem hinterlegten Zertifikat in das Dokument sichtbar eingemischt.

Hintergrund: Die meisten Dokumente sind nur dann erreichbar, wenn man sich in einem führenden System authentifiziert. Um das Dokument unterzeichnen zu können, sind dann ein Benutzerkonto und ein erfolgreiches Einloggen vorausgesetzt. Beim Starten der Signatur-Session kann nun optional die technische ID des verwendeten Accounts mitgegeben werden. Diese wird sichtbar in das Dokument eingemischt und bietet einen weiteren Hinweis auf den tatsächlichen Unterzeichner. Dieser Token kann von einem Benutzer mit seinem Namen überschrieben werden.

3. Serverseitige REST-Schnittstelle

Dieser Bereich beschreibt die Schnittstellen von doXisign und dessen angebotene Optionen. Sollten Sie doXisign über ein anderes Produkt der CIB Unternehmensgruppe einbinden, in der Regel CIB. doXiview, ist dieser Bereich für Sie weniger relevant. In dem Fall können Sie hier die verfügbaren Optionen und Erklärungen einsehen, für die technische Ansteuerung der Schnittstelle prüfen Sie bitte die Dokumentation des Produktes welches Sie einbinden.

3.1. Signaturprozess starten

Es kann keine Unterschrift geleistet werden solange die benötigten Angaben (requireName, requireMail, requireSms) nicht gemacht und Verifiziert wurden. Diese Voraussetzung gilt für alle Unterschriften auf diesem Dokument.

Sollten diese optionalen Angaben fehlen werden die Standardeinstellungen (siehe Konfiguration) benutzt.

3.2. Signatur-Session starten

Innerhalb des erzeugten Prozesses kann für jedes Signaturfeld eine Signatur-Session zum Unterschreiben gestartet werden.

3.3. Dokument Abholen

Die Kommunikation nach dem Unterschreiben des Dokumentes geschieht am Client über JavaScript-Callbacks. Dort wird der Integrator darüber informiert, dass eine neue Unterschrift geleistet wurde. Zusätzlich bekommt er die Information, ob das Dokument bereits vollständig signiert ist.

Wenn das Dokument noch nicht vollständig signiert ist und der Prozess dokumentbasiert ist, sollte die Download-Schnittstelle aufgerufen werden, um das Dokument als Zwischenstand abzuholen. 

3.4. Prozess beenden

Soll der Prozess beendet werden bevor alle Signaturfelder unterschrieben wurden, z. B. Fristablauf, kann diese Schnittstelle aufgerufen werden. Sobald der Prozess beendet wurde kann keine Unterschrift mehr geleistet werden,

3.5. Audit trail

Um sich ein Verlaufsprotokoll zu dem Prozess (Audit Trail) abzuholen, nutzen Sie bitte folgende REST-Schnittstelle:

3.6. Audit Trail Daten

Alle gesammelten Daten können auch in einer JSON-basierten Datenstruktur abgeholt werden. In diesem Fall nutzen Sie bitte den folgenden Aufruf:

4. Datenbank

Aktuell werden nur PostgreSQL Datenbanken unterstützt. Sollte eine andere Datenbank unterstützt werden wenden Sie sich an einen Mitarbeiter des CIB Vertriebs.

Folgende Tabellen werden aktuell für CIB doXisign benötigt, diese werden beim Starten des Servers automatisch erstellt. Sollten Sie aber eine neue Version aufspielen prüfen Sie bitte ob die Datenbank geändert wurde, diese Änderungen müssen ggf. manuell durchgeführt werden. Sollten Sie sich unsicher sein oder Fragen hierbei haben unterstützen wir Sie gerne.

4.1. Tabelle: doxisignprocess

Hier werden alle Informationen über den Prozess gespeichert.

4.2. Tabelle: doxisignaudittraildata

Hier werden alle Daten für den Audit Trail gespeichert.

4.3. Tabelle: doxisignaudittrail

Hier wird der Finale Audit Trail gespeichert. Dieser wird einmalig generiert beim Beenden des Prozesses.

4.4. Tabelle: doxisignsignatures

Hier werden alle Daten des Unterzeichners gespeichert.

5. Konfiguration

Der Konfigurationsmechanismus von CIB doXisign beruht auf bis zu drei Konfigurationsdateien:

5.1. Benötigte Konfigurationen

Tragen Sie bitte die folgenden Konfigurationseinstellungen vor dem ersten Deployment in der Datei environment-config.properties innerhalb des WAR Archivs ein. Später können Sie diese Datei externalisieren.

5.2. Optionale Konfigurationen

Diese Angaben sind Optional zu machen wenn Sie Abweichungen gegenüber den Defaults haben wollen. 

Nachdem CIB doXisign auf Ihrem System läuft, schenken sie bitte zwecks Konfiguration auch den Kapiteln (Zertifikate und Zeitstempel) noch einmal ihre Aufmerksamkeit.

5.3. Externalisierung der Konfiguration

Um das Deployment von Software Updates zu erleichtern, ist es möglich, eine externe Konfigurations-Datei einzubinden. Dort können Konfigurationen außerhalb des .war Archivs verwaltet werden.

Folgende Dinge müssen bei der Externalisierung der Konfiguration beachtet werden:

1. Der Name der externen Konfigurations-Datei ist doxisign.properties.
2. Die Datei doxisign.properties muss sich im Classpath des JEE Servlet-Container befinden. Um beispielsweise den Classpath des Apache Tomcat so zu erweitern, dass auch Verzeichnisse außerhalb des .war Archivs berücksichtigt werden, muss die Datei catalina.properties im Tomcat conf-Verzeichnis angepasst werden, indem man das gewünschte Verzeichnis der Property shared.loader hinzufügt.

6. Clientseitige JavaScript Integration

Dieses Kapitel ist vor allem dann relevant, wenn CIB doXisign direkt und nicht z.B. über CIB doXiview integriert werden soll. Wird eine Integration über CIB doXiview genutzt, sei hier auf die Schnellstart-Dokumentation von CIB doXiview verwiesen.

Clientseitig wird CIB doXisign in einem IFrame integriert. Die Aufruf-URL ist das Ergebnis des REST Aufrufs „prepare“. 

Damit eine Integration über IFrame-Grenzen hinweg möglich ist, wird das Postmessage Framework CIB iwc (CIB inter window communication) genutzt. Dieses muss der Aufrufer bei sich integrieren und beim Öffnen der URL nutzen. 

Die folgenden Abhängigkeiten müssen vom Integrator (der einbettenden Seite von CIB doXisign) geladen werden:

<script type="text/javascript" src="./js/cib.iwc.1.0.0.min.js"></script>
<script type="text/javascript" src="./js/iwc-interfaces-min.js"></script>

Anschließend kann CIB doXisign wie folgt geöffnet werden:

// url taken from response of REST call prepare
function openDoxisign(url)
{
        // initialize IWC framework
        var master = {};
        master.iwc = new window.CibGetMasterController().createMaster();
        master.signPad = new window.CibSignPadMasterFunctions(master.iwc);
 master.signPad.registerOnFinishSignProcessCallback(function(params) {
                console.log(">>> " + params.referenceId);
                // will be called after successful signing      
        });
 master.signPad.registerOnCancelSignProcessCallback(function(params) {
                // will be called after canceled signing 
        });
        // open doxisign which will trigger the start parameter callback
        master.iwc.openURLInFrame("#doxisign-frame", url);
}

Sobald ein Signaturvorgang erfolgreich abgeschlossen wurde, wird der Integrator über den folgenden Callback darüber informiert:

master.signPad.registerOnFinishSignProcessCallback(function(params) {
                console.log(">>> " + params.referenceId);
                // will be called after successful signing      
        });

Über die Refrenz-ID des Prozesses können nun weitere Aktivitäten ausgeführt werden. Dafür sei auf die Schnittstellen-Beschreibung der REST-Services in diesem Dokument verwiesen.

Wenn ein Signaturvorgang abgebrochen wurde, wird der Integrator über folgenden Callback informiert:

master.signPad.registerOnCancelSignProcessCallback(function(params) {
                // will be called after canceled signing 
        });

7. Zertifikate

Am Server kann ein Default Zertifikat konfiguriert werden (siehe Konfiguration). Dieses wird normalerweise bei jeder Unterschrift benutzt. Jeder Benutzer hat manuell die Möglichkeit ein persönliches Zertifikat hoch zu laden.

Zusätzlich kann beim Starten einer Signatur-Session ein Zertifikat mitgegeben werden (siehe REST Schnittstellen). Dies ist vor allem Sinnvoll wenn der Unterzeichner in einem angemeldeten System ein Zertifikat besitzt.

Per Default ist ein CIB eigenes Zertifikat hinterlegt. Dieses Zertifikat dient lediglich für erste Integrationstests und sollte nicht in Produktion verwendet werden.

8. Zeitstempel

In CIB doXisign gibt es zwei Arten Zeitdienste zu integrieren.

8.1. NTP ZeitServer

Das Network Time Protocol ist ein Standard zur Synchronisierung von Uhren in Computersystemen. Es ist möglich einen NTP Zeitserver in CIB doXisign zu konfigurieren. Wenn dies der Fall ist, wird nicht die lokale Systemzeit zur Bestimmung des Signierzeitpunktes herangezogen, sondern die abgeglichene Zeit mit dem NTP Zeitserver.

Die URL kann in der Datei environment-config.properties oder in der Datei doxisign.properties wie folgt hinterlegt werden:

Die Zeitserver der PTB (Physikalisch-Technischen Bundesanstalt) in Braunschweig sind beispielsweise für jedermann zu benutzen und kann unter folgender Adresse abgefragt werden:

             ptbtime1.ptb.de

Quelle: https://www.zeitserver.de/deutschland/ptb-zeitserver-in-braunschweig/

8.2. Time Stamp Authority (TSA)

Vertrauenswürdiges Zeitstempeln ist ein Prozess, bei dem die Erstellungs- und Änderungszeiten eines Dokuments sicher verfolgt werden können. Dieser setzt eine sogenannte Time Stamp Authority (TSA) voraus, der das Signieren mit einem aktuellen Zeitstempel übernimmt.

Mehrere Anbieter stellen diesen Service als Software as a Service (SaaS) zur Verfügung und dieser kann in CIB doXisign konfiguriert werden.

Es werden lediglich die Hashwerte der digitalen Signaturen an diesen Dienst übermittelt und keine Dokumente.