TSE-Middleware Dokumentation

Dokumentation als PDF herunterladen

I. Haftungsausschluss

Das Softwareprodukt ist sowohl urheberrechtlich als auch durch andere Gesetze und Vereinbarungen über geistiges Eigentum geschützt.

Das Softwareprodukt wird lizenziert, nicht verkauft.

Das Softwareprodukt wurde vom Lizenzgeber mit größter Sorgfalt erarbeitet und unter Einschaltung wirksamer Kontrollmaßnahmen geprüft. Der Lizenzgeber schließt jedoch ausdrücklich eine Gewähr­leistung für das Softwareprodukt aus.

Das Softwareprodukt wird dem Lizenznehmer "so wie es ist" zur Verfügung gestellt, ohne Gewährleis­tung jeglicher Art, weder ausdrücklich noch konkludent. Das gesamte Risiko, das aus der Leistung des Softwareproduktes entsteht, verbleibt beim Lizenznehmer.

Der Lizenzgeber übernimmt keine Gewähr dafür, daß das Softwareprodukt den Anforderungen und Zwecken des Lizenznehmers genügt oder mit anderer von ihm ausgewählter Software bzw. Hardware zusammenarbeitet. Der Lizenzgeber weist ausdrücklich darauf hin, daß er weder irgendeine Haftung noch irgendeine juristische Verantwortung für Kosten und Folgekosten übernimmt, die sich aus dem Verwenden des Softwareproduktes (oder der Unmöglichkeit, das Softwareprodukt zu verwenden) er­geben.

In jedem Fall bleibt die gesamte Haftung des Lizenzgebers beschränkt auf den Betrag, den der Li­zenznehmer für das Softwareprodukt bezahlt hat.

Alle durch Dritte geschützten Marken- und Warenzeichen unterliegen uneingeschränkt den Bestim­mungen des jeweils gültigen Kennzeichenrechts und den Besitzrechten der jeweiligen eingetragenen Eigentümer. Allein aufgrund der bloßen Nennung ist nicht der Schluss zu ziehen, dass Markenzeichen nicht durch Rechte Dritter geschützt sind.

Der Lizenznehmer haftet für alle Schäden, die aufgrund von Urheberrechts- und sonstigen Schutz­rechtsverletzungen entstehen.

Die in einigen Installationspaketen mitgelieferte und zum Betrieb erforderliche WormAPI-Bibliothek der Swissbit AG, Bronschhofen (Switzerland) unterliegt dem Copyright und den Lizenzbedingungen der vorgenannten Firma und darf nur in Verbindung mit der TSE-Middleware benutzt und eingesetzt wer­den.

II. Allgemeines

Die TSE-Middleware dient der einfachen Anbindung einer Swissbit-TSE an ein beliebiges ERP- oder Kassensystem. Dabei müssen keinerlei Programm- oder Codeteile in das Anwenderprogramm inte­griert oder gar einkompiliert werden, sondern die Anbindung erfolgt transprent über einen TCP-Socket. Somit gibt es keinerlei Abhängigkeiten von der verwendeten Programmiersprache der ERP- oder Kas­senlösung, wie es z.B. regelmäßig bei der Integration eines "SDK" der Fall ist. Ebenso sind Updates auf beiden Seiten möglich, ohne daß die jeweils andere Seite geändert oder angepaßt werden muß. Selbst eine komplette Plattformänderung der ERP- oder Kassenlösung tangiert die TSE-Anbindung nicht.

Dieser unschätzbare Vorteil unserer Lösung für den Programmierer/Anwender bedeutet neben einer erhöhten Investitionssicherheit (die Lösung ist völlig transparent und jederzeit austauschbar) auch eine erhebliche Ersparnis von Kosten bei der Programmierung. Die TSE-Middleware wird als fertige Anwendung ausgeliefert, die Installation ist im nächsten Abschnitt detailliert erläutert.

Aufgrund der Architektur der TSE-Middleware lassen sich mit einer TSE beliebig viele Kassen betrei­ben (ohne Probleme auch mehr als zehn Kassen). Abhängig von der Hardware und den verfügbaren TSE-Steckplätzen kann die TSE-Middleware auch beliebig viele TSE parallel an einem Server/PC ver­walten. Somit ersetzt unsere TSE-Middleware gleichzeitig auch weitere Hard- und/oder Software-Komponenten (wie z.B. "LAN-TSE").

Die Swissbit-TSE und das zugehörige SDK entsprechen vollumfänglich allen gesetzlichen Vorgaben, wie sie u.a. in BSI TR-03151 (Secure Element API) festgelegt sind. Unsere Middleware setzt dabei auf diesem SDK auf. Zusätzlich verfügt unsere Middleware noch über die Möglichkeit, die von der TSE erzeugten Signaturen zu prüfen. Außerdem bieten wir eine optionale Syntax- und Semantikprüfung für die von Ihnen an die TSE übergebenen Werte an.

Die TSE-Middleware wird aktuell für folgende Systeme und Plattformen entwickelt und bereitgestellt:

• Linux 64 Bit für Intel (amd64) als Konsolenanwendung
• Linux 32 Bit für ARM (arm32) als Konsolenanwendung
• Windows 64 Bit (ab Windows 7) als GUI-Anwendung (Qt-basiert)
• Windows 32 Bit (ab Windows 7) als GUI-Anwendung (Qt-basiert)
• Linux 64 Bit für Intel (amd64) als GUI-Anwendung (Qt-basiert), auf Anfrage

Der prinzipielle Funktionsumfang, die zugrundeliegenden Bibliotheken und die Ansteuerung der TSE sind bei allen Betriebssystemen und auch auf auf allen Plattformen immer gleich. Dennoch gibt es, aufgrund der komplett anderen Philosophie von Linux und Windows, einige wichtige Unterschiede.

• unter Windows gibt es keine Möglichkeit, die Zugriffe auf ein (USB-)Gerät einzuschränken
• unter Windows gibt es keinen Mount-Befehl
• unter Windows ist die Herunterstufung der Rechte eines Daemons nicht vorgesehen

Trotz dieser Einschränkungen beim Betrieb unter Windows haben wir uns entschlossen, beide Lösun­gen parallel anzubieten, da am Markt viele Windows-ERP und/oder Kassen-Lösungen, teilweise auch als Einzelplätze, anzutreffen sind. Genau für diese Lösungen, die teilweise in Programmiersprachen wie VB5, VB6 (oder älteren Basic-Derivaten), PHP, Delphi, ja sogar Cobol oder FoxPro geschrieben sind, stellt aber unsere TSE-Middleware eine unverzichtbare Abstraktionsschnittstelle bereit.

Da die Systemsicherheit unter Linux als höher angesehen werden darf, empfehlen wir die Nutzung der TSE-Middleware unter Linux bei besonders unternehmenskritischen Anwendungen bzw. bei Vorhan­densein von Netzwerken und/oder Linux-Servern.

Daneben gibt es natürlich auch Unterschiede zwischen der Konsolenversion und der GUI-Version. Während die GUI-Version eher auf kleine (Windows)-Installationen abzielt, kann die Konsolen-Version auch komplett ohne Oberfläche, d.h. programmgesteuert betrieben werden, z.B. wenn die TSE an ei­nem Server in einem zentralen Serverraum angesteckt ist.

Durch das, je nach Plattform unterschiedlich ausgelegte, Locking der TSE wird zudem zuverlässig sichergestellt, daß immer nur eine Instanz der Software zeitgleich auf die TSE zugreift. Dies ist für die reibungslose Funktion wichtig und eines der Alleinstellungsmerkmale unserer Software.

Die Visualisierung der Log-Messages, die Verifizierung der Signaturen und vor allem die Möglichkeit, fremde Tar-Files und Signaturen zu verarbeiten, beherrschen momentan nur sehr wenige Programme auf dem Markt (uns ist persönlich nur ein Einziges bekannt).

Wichtig! Die meisten Datums- oder Zeitwerte der TSE werden als Unix-Timestamp erfaßt und ausgegeben. Dieser Timestamp entspricht den Sekunden seit dem 01.01.1970 und wird immer in UTC (Coordina­ted Universal Time) angegeben. Dies ist bei der Umrechnung in die lokale Zeitzone zu beachten.

III. Installation

1. Linux (Intel 64Bit, ARM 32Bit)

Es wird ein aktuelles Linux-System vorausgesetzt, welches folgende Mindestanforderungen erfüllen muß:

• glibc in Version >= 6.0.30 (abweichende Konfigurationen, z.B. glibc in Version 6.0.28 für Debian 10, sind auf Anfrage möglich)
• OpenSSL Version 1.1.1x
• libarchive.so.13, libattr.so.1, liblzma.so.5, libacl.so.1, libxml2.so.2, libbz2.so.1.0
• icu (ab Version 63)
• libWormAPI.so (ab Version 5.8.x, teilweise enthalten)

Es wird empfohlen, einen dedizierten User und eine eigene Gruppe für die TSE anzulegen. Damit wird einerseits ausgeschlossen, daß der TSE-User andere Teile des Systems beeinflussen kann und an­dererseits der Zugriff auf die TSE für andere Benutzer unterbunden.

Die TSE selbst wird an einen USB-Anschluß des Linux-Servers angesteckt und gemountet. Der Befehl hängt von der Linux-Distribution ab. Wir gehen davon aus, daß die TSE unter "/dev/sdc1" ansprech­bar ist, der Mountpoint der TSE "/mnt" und TSE-Benutzer und -gruppe "tse" lauten. Der Befehl zum Mounten der TSE lautet dann: "mount -o fmask=0177,dmask=0077,uid=tse /dev/sdc1 /mnt"

Das Programmpaket besteht aus einem Tar-Archiv, welches sieben Dateien enthält, die alle den je­weiligen Copyrights unterliegen:

1. tse_admin (das TSE-Administrations-Programm)
2. tse_server (das TSE-Server-Programm)
3. tse_admin.conf (die Konfigurationsdatei für tse_admin)
4. tse_server.conf (die Konfigurationsdatei für tse_server)
5. tse.lic (die Lizenzdatei mit der signierten Lizenz)
6. libWormAPI.so (die Bibliothek der Swissbit AG zur TSE-Ansteuerung)
7. optional client.pl (ein Perl-Demoprogramm für Test und Simulation der Kommunikation)

Die fünf Dateien (1) ... (5) sollten in einen eigenen Ordner (z.B. "/opt/tse") gelegt werden. Die Dateien (1) und (2) benötigen das gesetzte Execute-Bit (z.B. 0755). Die Konfigdateien (3) und (4) sollten nur für den TSE-Benutzer lesbar sein, da darin die Admin-PIN steht (Vorgabe tse:tse 0600). Die Bibliothek (6) muß in ein System-Bibliotheksverzeichnis installiert werden (z.B. "/usr/lib"). Danach ist i.d.R. der Befehl "ldconfig" als root Benutzer aufzurufen. Der optionale Perl-Script (7) benötigt zum Aufruf eine installierte Perl-Umgebung (Aufruf "perl -Tf /opt/tse/client.pl"). Er dient hauptsächlich als Anregung zur Imple­mentierung der Clients (Kassen).

Zuerst sollte man sicherstellen, daß die Programme tse_admin und tse_server fehlerfrei aufgerufen werden können, also alle Bibliotheken im System vorhanden sind. Dazu führt man am besten einmal diesen Befehl aus: "ldd /opt/tse/tse_admin". Sollten dabei Zeilen/Einträge mit "not found" ausgegeben werden, so müssen die betreffenden Biblio­theken nachin­stalliert werden, dazu ist je nach Distribution entsprechend vorzugehen (z.B. "apt-get install ...").

Als nächstes überprüfen Sie bitte die Uhrzeit des Servers (z.B. mit "date"). Erst wenn diese korrekt ist, sollten die Programme tse_admin oder tse_server gestartet werden.

Später sollte das Mounten und der Start des Servers in den Systemstart aufgenommen werden. Hierzu können wir Ihnen, je nach verwendetem System (Systemd oder InitV) mit Beispielen für Startscripte weiterhelfen.

Wichtig! Vor dem ersten Aufruf der Programme tse_admin oder tse_server müssen unbedingt die zugehörigen Konfigdateien angepaßt werden. Es müssen mindestens die Admin-PIN und das TSE-Mountverzeich­nis eingetragen werden.

2. Windows (Intel 64Bit, Intel 32Bit)

Es wird ein Windows-Betriebssystem (mindestens MS-Windows 7) mit 32 oder 64Bit vorausgesetzt. Die Mindestanforderungen sind:

• MS-Windows 7 oder MS-Windows-Server 2012
• MS-VisualC-Redistributable-Kit 2015-2019 (mindestens 14.26.x)

Die TSE selbst wird an einen USB-Anschluß des Windows-PC oder -Servers angesteckt. Sie muß anschließend als Laufwerk mit einem eigenen Buchstaben angezeigt werden und ansprechbar ein.

Das Programmpaket besteht hier aus einem Rar-Archiv, welches u.a. folgende Dateien enthält, die alle den jeweiligen Copyrights unterliegen:

1. tse_admin.exe (das TSE-Administrations-Programm)
2. tse_server.exe (das TSE-Server-Programm)
3. tse_admin.conf (die Konfigurationsdatei für tse_admin)
4. tse_server.conf (die Konfigurationsdatei für tse_server)
5. tse.lic (die Lizenzdatei mit der signierten Lizenz)
6. libWormAPI.dll (die Bibliothek der Swissbit AG zur TSE-Ansteuerung)
7. einige Dll's und Verzeichnisse, die die Laufzeitumgebung von "Qt" bereitstellen
8. einige Dll's, die u.a. für die Signaturprüfung und den Tar-Export notwendig sind
9. optional client.pl (ein Perl-Demoprogramm für Test und Simulation der Kommunikation)

Sämtliche Dateien und Ordner des Archivs müssen in ein eigenes Verzeichnis entpackt werden (z.B. "C:\Programme\tse").

Als nächstes prüfen Sie bitte die Uhrzeit des Rechners. Erst wenn diese korrekt ist, sollten die Programme tse_admin.exe oder tse_server.exe gestartet werden. Der optionale Perl-Script (9) benötigt zum Aufruf eine installierte Perl-Umgebung (Aufruf "perl -Tf /opt/tse/client.pl"). Er dient hauptsächlich als Anregung zur Implementierung der Clients (Kassen).

Wichtig! Vor dem ersten Aufruf der Programme tse_admin.exe oder tse_server.exe müssen unbedingt die zu­gehörigen Konfigdateien angepaßt werden. Es müssen mindestens die Admin-PIN und das TSE-Lauf­werk (z.B. "F:", nur Buchstabe und Doppelpunkt) eingetragen werden.

IV. Lizenzierung

Das Kernstück für die Lizenzierung der TSE-Middleware stellt die Seriennummer der TSE (dies ist der SHA-2 Hash des BitStrings vom PublicKey) dar. Diese SN wird als 32-Byte-Octet ausgegeben, d.h. als Folge von 64 Hex-Zeichen. Die Lizenzierung der TSE-Middleware erfolgt immer für genau eine TSE-Seriennummer. Dabei ist es möglich, eine Lizenz für die gesamte Laufzeit des TSE-Zertifikates (maximal fünf Jahre) oder auch für einzelne Jahre zu erwerben.

In der Lizenz ist dabei neben dem Start- und Ende-Datum und der SN der TSE auch der Umfang der gewährten Nutzung enthalten. Folgende Bausteine sind einzeln lizenziert:

• die Plattform (Linux und/oder Windows)
• der Anwendungstyp (Konsole und/oder GUI)
• der TSE-Typ (Entwickler- und/oder Produktions-TSE)
• die maximale Anzahl der zugelassenen Kassen
• die Nutzung des Serverprogramms (tse_server)
• die Nutzung des Adminprogramms (tse_admin)
• die Visualisierung der Message-Logs und die Validierung der Signaturen der TSE
• die Visualisierung von externen Message-Logs und die Validierung von externen Tar-Dateien

Aufgrund des Aufbaus und der Funktionsweise der Lizenzdatei (die Lizenz wird mit einem privaten Schlüssel signiert, den die TSE dann mit ihrem PublicKey überprüft) lassen sich Manipulationen aus­schließen, ohne daß die Lizenzdatei geheim sein muß. Da die signierte Lizenz in "Base64" kodiert ist, kann die Lizenzdatei problemlos übertra­gen werden (z.B. per Mail).

Damit das Programm die Lizenzdatei finden kann, wird diese in der Konfigdatei im Abschnitt "global" hinterlegt. Der Standardwert lautet "lizfile = tse.lic", wobei die Datei im gleichen Ordner wie das Pro­gramm selbst gesucht wird.

Zum Testen und für Demo-Zwecke gibt es eine besondere Lizenz, die für alle Entwickler-TSE gültig ist. Wenn Sie nach Ablauf der Demo-Lizenz (i.d.R. drei Monate) Ihre Entwickler-TSE weiter benutzen möchten, benötigen Sie auch dafür eine gültige Lizenz, die Sie (kostenpflichtig) erwerben müssen.

Wichtig! Nach Ablauf der Lizenz könnte man theoretisch die Uhrzeit des Rechners zurückstellen, um weiterhin mit der Lizenz arbeiten zu können, allerdings werden dann natürlich auch alle Transaktionen mit der falschen Uhrzeit erzeugt. Ebenso verweigert das Programm die Prüfung von Signaturen und/oder den Export von Transaktionen, die außerhalb des Lizenzzeitraumes liegen.

V. Hinweise vor dem Start

Wichtig! Es sollte unbedingt beachtet werden, daß bei allen produktiven TSE's (also alle außer den TSE's im Entwicklerpaket) kein "FactoryReset" möglich ist, d.h. eine einmal gesperrte TSE ist nicht wieder zu entsperren. Dies ist auch nicht zu umgehen!

Wodurch kann die TSE gesperrt werden. Dafür gibt es (leider) gleich mehrere Möglichkeiten:

1. der CredentialSeed ist falsch
2. die Admin- (oder TimeAdmin-) PIN wird dreimal falsch eingegeben, das geht schnell, wenn diese z.B. in der Konfigdatei falsch hinterlegt und das Programm dreimal gestartet wird (das läßt sich zum Glück mit der PUK reparieren).
3. die PUK wird beim Entsperren des Admin oder TimeAdmin dreimal falsch eingegeben

Der Fall (1) kann in unserer Software nicht passieren, da der CredentialSeed im Programm fest ein­kompiliert ist. Die Möglichkeiten (2) und (3) können nur auftreten, wenn in der Konfigdatei falsche Wer­te stehen oder wenn bei der Änderung von PIN/PUK aktiv falsche Werte übergeben werden.

Zudem gibt es noch eine weitere wichtige Funktion bzgl. Datum/Uhrzeit. Da die Zertifikate bei den Ent­wickler-TSE nur sechs Monate gültig sind, kann man einen Time-Versatz angeben, so daß der TSE immer ein "aus Zertifikats-Sicht gültiges" Datum übermittelt wird, ohne daß man das Systemdatum än­dern muß. Dieses Feature ist nur aktiv, wenn das Programm eine Entwickler-TSE erkennt.

Zur Demonstration der Kassenzugriffe dient das kleine Perl-Programm "client.pl". Aus dessen Quellco­de kann man recht gut die einfache Implementierung der Clients (nur vier Zeilen Quellcode pro Zugriff) entnehmen. Außerdem lassen sich damit auch alle Funktionen des Serverprogramms testen.

Wichtig! Das gleichzeitige Ausführen von tse_admin und tse_server sollte vermieden werden, da beide exklu­siv auf die TSE zugreifen und zudem das Admin-Programm am Ende alle aktiven Clients abmeldet.

Wichtig! Der Tar-Export der TSE ist im Rahmen der Datensicherung möglichst regelmäßig auszuführen, um im Falle eines Defektes oder Verlustes der TSE keine Daten zu verlieren. Vor dem Wechsel der TSE bzw. deren Außerbetriebsetzung ist dieser verpflichtend auszuführen.

VI. Admin-Programm

Mit dem Admin-Programm werden die Einricht- und Wartungsarbeiten der TSE durchgeführt. Da es für den normalen täglichen Betrieb nicht benötigt wird, ist es auch als extra Modul entworfen worden. So­mit kann man nämlich bei Bedarf den Zugriff auf den Administrator einschränken.Die Adminprogram­me (tse_admin) der GUI- und der Konsolenanwendung bieten exakt dieselbe Funktionalität, unter­scheiden sich aber signifikant in der Bedienung. Während bei der GUI sämtliche Eingaben interaktiv über graphische Buttons und Eingabefelder erfolgen, können und müssen bei der Konsolenvariante alle Kommandos und Parameter auf der Kommandozeile übergeben werden. Deshalb kann diese Va­riante (wie bei Linux üblich) auch in (Bash-)Scripte eingebunden werden.

1. GUI-Version

Die GUI-Version sucht ihre Konfigurationsdatei per Default im Programmverzeichnis unter dem Na­men "tse_admin.conf". Dies kann über einen Aufrufparameter übersteuert werden:

-c | --cfgfile <Dateiname> der Name (und optional der Pfad) der Konfigdatei

Weitere Kommandozeilenparameter sind aktuell nicht definiert. Alle Info-Ausgaben erfolgen bei der GUI-Version in ein Textobjekt (und teilweise zusätzlich in die Zwischenablage). Da die Applikation als Multithreading-Anwendung entworfen ist, treten auch bei länger laufenden Aktionen (z.B. bei der Initialisierung oder beim Tar-Export) keine Einschränkungen der Interaktion ("keine Rückmeldung" o.ä.) auf. Die Bedienung der GUI erfolgt über Buttons und ist damit auch per Tablet gut möglich. Zuerst wird der Aktionstyp gewählt (Info, Setup, Extras), danach innerhalb dieser Aktion der Subtyp (z.B. TSE-Set­up), danach wird die Aktion per Okay-Button gestartet. Dies ist eine klassische Windows-Bedienung, die sicher keiner weiteren Er­klärung bedarf. Folgende Funktionen können z.Zt. ausgeführt werden:

• Info | TSE-Infos
  alle Infos zur TSE werden in ein Textobjekt ausgegeben
• Info | Liz-Infos
  alle Infos zur Lizenz werden in ein Textobjekt ausgegeben
• Info | Copy SN
  die Seriennummer (Hex-String) der TSE wird in ein Textobjekt und in die Zwischenablage ausge­geben
• Info | Copy PKey
  der PublicKey der TSE wird im PEM-Format in ein Textobjekt und in die Zwischenablage ausgege­ben
• Info | Copy Cert
  die Zertifikats-Chain der TSE wird im PEM-Format in ein Textobjekt und in die Zwischenabla­ge ausgegeben
• Setup | AdminPin | Okay
  ändert die Admin-PIN der TSE, die alte und die neue PIN müssen eingegeben werden
• Setup | TAdminPin | Okay
  ändert die Time-Admin-PIN der TSE, die alte und die neue PIN müssen eingegeben werden
• Setup | Puk | Okay
  ändert die Super-PIN (PUK) der TSE. die alte und die neue PUK müssen eingegeben werden
• Setup | Admin | Okay
  entsperrt den Admin mit Hilfe der PUK und setzt die neue Admin-PIN, die PUK und die neue PIN müssen eingegeben werden
• Setup | TAdmin | Okay
  entsperrt den Time-Admin mit Hilfe der PUK und setzt die neue TimeAdmin-PIN, die PUK und die neue PIN müssen eingegeben werden
• Setup | TSE-Setup | Okay
  führt das initiale Setup der TSE aus, die neue PUK und die neuen PIN's für Admin und TimeAdmin müssen eingegeben werden
• Setup | TSE löschen | Okay
  löscht alle Daten der TSE, die PIN muß eingegeben werden
• Setup | FactoryReset | Okay
  setzt die TSE komplett zurück (nur Entwickler-TSE), die PIN muß eingegeben werden
• Setup | FW-Update | Okay
  prüft, ob ein Firmware-Update für die TSE vorliegt und führt die­ses nach Rückfrage aus (die neue Firmware ist lokal in der Dll enthalten)
• Extras | Tar-Export | Okay
  exportiert den gesamten Inhalt der TSE in das angegebene Tar-File, das Tar-Export-File muß angegeben werden
• Extras | Msg-Export | Okay
  exportiert alle Log-Messages der TSE in ein File, das Msg-Export-File muß angegeben werden
• Extras | TSE-Check | Okay
  liest und verifiziert alle Messages und Signaturen der TSE, ein Protokoll-Export-File muß angegeben werden, es werden nur Fehler protokolliert
• Extras | Close-Trans | Okay
  schließt eine offene Transaktion für den jeweiligen Client, die Transaktionsnummer muß angegeben werden
• Extras | Msg prüfen | Okay
  verifiziert die Signatur des angegebenen externen Message-Files i.V. mit dem PKey, das Msg-Input-File und das PKey-Input-File muß angegeben werden
• Extras | Tar-Check | Okay
  prüft das angegebene externe Tar-File und verifiziert alle darin enthalte­nen Signaturen, das Tar-Input-File und das Protokoll-Export-File muß angegeben werden
• Extras | Cert2PKey | Okay
  extrahiert den PublicKey im PEM-Format aus dem Zertifikat im PEM-Format, das Zertifikat-Input-File und das PKey-Export-File muß angegeben werden
• Extras | Add-Client | Okay
  registriert einen zusätzlichen Client in der TSE (nur zum Testen), die Client-ID muß eingegeben werden
• Extras | Del-Client | Okay
  löscht einen registrierten Client in der TSE (nur zum Testen), die Client-ID muß eingegeben werden

Wichtig! Nach einem Wechsel der Admin-PIN mittels "Setup / AdminPin" muß die neue PIN unbedingt vor dem nächsten Neustart des Admin-Programms in der Konfigdatei korrekt hinterlegt werden. Beim Versuch, die PIN mittels "Setup / TSE-Setup" oder "Setup / Admin" neu zu setzen, muß diese aus Sicherheits­gründen mit der in der Konfigdatei hinterlegten PIN übereinstimmen. Ebenso wird bei den Funktionen "Setup / AdminPin", "Setup / FactoryReset" und "Setup / TSE löschen" zur Sicherheit nochmals die PIN abgefragt.

2. Konsolen-Version (nur Linux)

Die Konsolen-Version sucht ihre Konfigurationsdatei ebenfalls per Default im Programmverzeichnis unter dem Namen "tse_admin.conf". Die Info-Ausgaben erfolgen dabei direkt nach stdout (also auf die Konsole).

Usage: tse_admin [std_opt] [ext_opt]

Die nachfolgenden Standardoptionen (std_opt) können unabhängig von der auszuführenden Aktion immer verwendet werden:

• -c | --cfgfile <Dateiname>
  der Name (und optional der Pfad) der Konfigdatei
• -d | --loglevel { 0, 1, 2, 3, 4 }
  der Loglevel (Defaultwert s. Konfigdatei)
• -f | --logfile <Dateiname>
  der Pfad und Name des Log-Files (Defaultwert s. Konfigdatei)
• --logappend { 1 | 0 }
  soll das Log-File bei jedem Start überschrieben oder erweitert werden (Defaultwert s. Konfigdatei)
• -l | --lizfile <Dateiname>
  das Lizenz-File (Defaultwert s. Konfigdatei)
• -m | --mountpoint <Pfad>
  der Mountpoint der TSE (Defaultwert s. Konfigdatei)
• -v | --version
  die Ausgabe von Programmversion und Copyright-Info, dies schließtalle anderen Optionen aus
• -h | --help
  diese Hilfeanzeige, dies schließt alle anderen Optionen aus

Alle erweiterten Optionen (ext_opt) sind, abhängig von der Aktion, nur spezifisch gültig. Folgende Auf­rufe sind z.Zt. definiert:

• tse_admin print_info
  es werden alle Infos zur TSE ausgegeben
• tse_admin print_liz
  es werden alle Infos zur Lizenz ausgegeben
• tse_admin print_sn
  die Seriennummer (Hex-String) der TSE wird ausgegeben
• tse_admin print_pkey
  der PublicKey der TSE wird im PEM-Format ausgegeben
• tse_admin print_cert_chain
  die Zertifikats-Chain der TSE wird im PEM-Format ausgegeben
• tse_admin change_admin_pin --oldpin <PIN> --newpin <PIN>
  ändert die Admin-PIN der TSE
• tse_admin change_time_pin --oldpin <PIN> --newpin <PIN>
  ändert die Time-Admin-PIN der TSE
• tse_admin change_puk --oldpuk <PUK> --newpuk <PUK>
  ändert die Super-PIN (PUK) der TSE
• tse_admin unblock_admin --adminpin <PIN> --puk <PUK>
  entsperrt den Admin mit Hilfe der PUK und setzt die neue Admin-PIN
• tse_admin unblock_time --timepin <PIN> --puk <PUK>
  entsperrt den Time-Admin mit Hilfe der PUK und setzt die neue TimeAdmin-PIN
• tse_admin setup_tse --adminpin <PIN> --timepin <PIN> --puk <PUK>
  führt das initiale Setup der TSE aus
• tse_admin delete_data --tarfile <Dateiname>
  löscht alle Daten der TSE und exportiert direkt vorher alle Daten in das angegebene Tarfile (dieser Export wird vom SDK erzwungen)
• tse_admin factory_reset
  setzt die TSE komplett zurück (nur Entwickler-TSE)
• tse_admin firmware_update [--adminpin <PIN>]
  prüft auf eine neue Firmware für die TSE und führt bei Angabe der PIN das Update aus
• tse_admin add_client --client <Ident>
  registriert einen zusätzlichen Client in der TSE
• tse_admin del_client --client <Ident>
  löscht einen registrierten Client in der TSE
• tse_admin close_trans --client <Ident> --transnr <TrNr>
  schließt eine geöffnete Transkation des jeweiligen Clients
• tse_admin export_tar --tarfile <Dateiname>
  exportiert den gesamten Inhalt der TSE in das angegebene Tar-File
• tse_admin export_msg --msgfile <Dateiname>
  exportiert alle Log-Messages der TSE in ein File
• tse_admin check_tse
  liest und verifiziert alle Messages und Signaturen der TSE
• tse_admin check_ext_msg --msgfile <Dateiname> --pkeyfile <Dateiname>
  verifiziert die Signatur des angegebenen externen Message-Files i.V. mit dem PKey
• tse_admin check_ext_tar --tarfile <Dateiname>
  prüft das angegebene externe Tar-File und verifi­ziert alle darin enthaltenen Signaturen
• tse_admin cert_to_pkey --certfile <Dateiname> --pkeyfile <Dateiname>
  extrahiert den PublicKey im PEM-Format aus dem Zertifikat im PEM-Format

Wichtig! Nach einem Wechsel der Admin-PIN mittels "change_admin_pin" muß die neue PIN unbedingt vor dem nächsten Neustart des Admin-Programms in der Konfigdatei korrekt hinterlegt werden. Beim Ver­such, die PIN mittels "setup_tse" oder "unblock_admin" neu zu setzen, muß diese aus Sicherheits­gründen mit der in der Konfigdatei hinterlegten PIN übereinstimmen. Ebenso wird bei den Funktionen "change_admin_pin", "factory_reset" und "delete_data" zur Sicherheit nochmals die PIN abgefragt.

VII. Server-Programm

Die Serverkomponente der TSE-Middleware ist das Kernstück für die tägliche Arbeit. Das ERP- oder Kassensystem kommuniziert über eine Socketverbindung mit dem TSE-Server. Dabei werden nur wenige Daten auf unterster Ebene ausgetauscht, so daß die Verarbeitung einfach und hocheffizient erfolgt. Die Serverprogramme der GUI- und der Konsolenanwendung bieten exakt dieselbe Funktiona­lität. Da sie kaum Interaktion mit dem Benutzer erfordern, unterscheidet sich hier auch die Bedienung nicht wesentlich. Lediglich die Sicherheitsaspekte sind bei der Linux-Lösung höher, da hier aufgrund des Betriebssystems andere Abstraktionsschichten möglich sind. Sowohl die GUI, als auch die Konso­lenversion sind zum dauerhaften Betrieb im Hintergrund vorgesehen.

Das Server-Programm kümmert sich auch um die laufende Aktualisierung der Uhrzeit und um den täg­lichen Selbsttest. Dieser wird zu einer konfigurierbaren Zeit aufgerufen, was ein weiteres Alleinstel­lungsmerkmal unserer TSE-Middleware ist.

Sobald sich ein Client (Kasse) verbindet, wertet der Server das gesendete Token (GUID) aus, registriert bei Erfolg die Kasse und startet die angeforderte Aktion.

Aus Sicherheitsgründen können hierüber keine destruktiven administrativen Aufgaben (z.B. Setup oder Daten lö­schen) erledigt werden, dies übernimmt das Admin-Programm. Folgende Befehle sind z.Zt. im Server-Programm implementiert:

• eine Transaktion starten
• eine Transaktion updaten
• eine Transaktion beenden
• die Verfügbarkeit der TSE prüfen (KeepAlive)
• den PublicKey der TSE auslesen (z.B. für den Bondruck)
• die SerialNumber der TSE auslesen (z.B. für den Bondruck)
• den Signatur-Algorithmus und das LogTimeFormat der TSE auslesen (z.B. für den Bon­druck)
• die TSE- und Programm-Infos auslesen (Zertifikatsende, freie Blöcke, verbleibende Signaturen, nächster Selbst­test, SDK-Version, Programm-Version, Plattform)
• die offenen Transaktionen des aktiven Clients auslesen (z.B. für Kassenabschluß)
• den Tar-Export aufrufen
• einen Client registrieren und löschen (wird nur intern benötigt)
• den Serverprozess sauber beenden

Aus dem vom Client gesendeten Request werden vorab abschließende CR, LF und Leerzeichen ausgefiltert.

Die Clients müssen beim Verbinden einen Aufrufcode (ein Groß-Buchstabe), gefolgt von einem Binde­strich und der GUID, sowie optional danach die evtl. Nutzdaten als Request senden. Die Response er­folgt immer mit "@" als Trennzeichen. Folgende Aufrufcodes sind aktuell definiert:

• A
  startet eine Transaktion, es werden die Transaktions-Nr und die TSE-Zeit zurückgeliefert, (das Zeit-Format kann über den Konfigeintrag "timeformat" eingestellt werden)
  Response: "<TransNr>@<StartTime>"
• B
  macht ein Transaktions-Update, es muß nach der GUID und einem Bindestrich die Transakti­ons-Nr angegeben werden, die ClientID muß identisch zum Aufruf "A" sein, es werden die Transakti­ons-Nr, die TSE-Zeit, der Signaturzähler und die Signatur selbst zurückgeliefert, (das Signatur-Format kann über den Konfigeintrag "signatur", das ZeitFormat über den Konfigeintrag "timeformat" eingestellt werden), je nach Einstellung des Konfigeintrages "checkprocdata" werden die übergebenen Nutzdaten vorher analysiert und ggf. auf Syntax und Semantik geprüft, die Werte für ProcessType und ProcessData sind mit einem "@" zu trennen
  Beispiele für Requests:
  B-<GUID>-456@Bestellung-V1@2;"Radeberger Pils";4.85
  Response: "<TransNr>@<UpdTime>@<SigNr>@<Signatur>"
• C
  beendet eine Transaktion, es müssen nach der GUID und einem Bindestrich die Transaktions-Nr und die Nutzdaten angegeben werden, die ClientID muß identisch zum Aufruf "A" sein, es werden die Transaktions-Nr, die TSE-Zeit, der Signaturzähler und die Signatur selbst zurückgeliefert, (das Signatur-Format kann über den Konfigeintrag "signatur", das Zeit-Format über den Konfigeintrag "timeformat" eingestellt werden), je nach Einstellung des Konfigeintrages "checkprocdata" werden die übergebenen Nutzdaten vorher analysiert und ggf. auf Syntax und Semantik geprüft, die Werte für ProcessType und ProcessData sind mit einem "@" zu trennen
  Beispiele für Requests:
  C-<GUID>-9@Kassenbeleg-V1@Beleg^120.00_0.00_0.00_0.00_0.00^120.00:Bar
  C-<GUID>-10@Kassenbeleg-V1@AVTransfer^0.00_0.00_0.00_0.00_55.55^55.55:Unbar
  C-<GUID>-456@Bestellung-V1@2;"Radeberger Pils";4.85
  Response: "<TransNr>@<EndTime>@<SigNr>@<Signatur>"
• D
  testet, ob der TSE-Server erreichbar ist (keepalive), Response:
  "ping okay" (oder "TSE busy")
• E
  liefert den PublicKey der TSE als Base64-String zurück
• F
  liefert die SerialNumber der TSE als Octet-String zurück
• G
  liefert einige statische Daten als String zurück:
  den TSE-Signatur-Algorithmus, das LogTimeFormat der TSE, die SDK-Version (direkt aus der Worm-Library), die Programmversion (direkt aus der Software), das System (Windows, Linux, Arm) und die Architektur (32 oder 64 Bit), bei System und Architektur handelt es sich um den einkompilierten Wert der Software, nicht um das aktuelle Betriebssystem
  Response: "<SigAlgo>@<TimeFormat>@Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein..2@WINDOWS@64"
• H
  liefert einige aktuelle TSE-Infos zurück:
  das Zertifikatsende, den Stand des Signaturzählers, die Anzahl verwendeter Blöcke der TSE, die Zeit des nächsten Selbsttests (das Zeit-Format kann über den Konfigeintrag "timeformat" eingestellt werden)
  Response: "<ZertifikatEnde>@<Signaturen>@<Blöcke>@<Selftest>"
• I
  liefert die Anzahl und die Nummern der offenen Transaktionen des aktuellen Clients zurück
  Response: "<Anzahl>@<TransNr1>;<TransNr2>"
• J
  ruft den Tar-Export der TSE auf, nach der GUID und einem Bindestrich muß angegeben werden, ob der Server nach dem Export beendet werden soll (1) oder nicht (0) und nach dem Trennzeichen '@' die Exportdatei (optional mit Pfad), dabei ist bei allen Plattformen einheitlich als Pfadseparator ein Schrägstrich ("/") zu verwenden, die hier angegebene Exportdatei ist immer relativ zum Pfad in der Konfigdatei, aus diesem Grund ist der Parameter "tarexportdir" in der Konfigdatei verpflichtend
  Request: J-<GUID>-0@subdir/export.tar
• K
  liefert die Anzahl und die Namen der aktuell angemeldeten Clients zurück, zu beachten ist hierbei, daß Clients, die noch offene Transaktionen besitzen, von der TSE nicht
  wieder abgemeldet werden (auch nicht bei Beendigung des Serverprozesses)
  Response: "<Anzahl>@<Client1>;<Client2>"
• Z
  beendet den Serverprozess sauber
  Response: "shutdown initiated"

Wichtig! Da es leider in der Firmware der TSE keine Möglichkeit gibt, auszulesen, welche ClientID eine Trans­aktion geöffnet hat und die TSE aber ein "finishTransaction" nur von derselben ClientID akzeptiert, sollte man sich unbedingt die offenen Transaktionen im ERP/Kasse genau merken.

1. GUI-Version

Das Server-Programm wird entweder per Aufruf aus dem Startmenü oder per Autostart ausgeführt. Die GUI-Version sucht ihre Konfigurationsdatei per Default im Programmverzeichnis unter dem Na­men "tse_admin.conf". Dies kann über einen Aufrufparameter übersteuert werden:
-c | --cfgfile <Dateiname>
der Name (und optional der Pfad) der Konfigdatei

Weitere Kommandozeilenparameter sind aktuell nicht definiert. Die GUI öffnet standardmäßig (die Po­sition ist konfigurierbar) in der rechten unteren Ecke des Desktops ein kleines Fenster, welches den Status der Initialisierung anzeigt. Sobald die Lizenz geprüft ist, wird ein Icon im SystemTray erstellt, welches beim Start rot dargestellt wird. Nach der Initialisierung wechselt dieses Icon auf grün und das Fenster wird nach weiteren 30 Sekunden ausgeblendet. Es kann jederzeit mit einem Rechtsklick auf das Icon wieder eingeblendet werden. Ebenso läßt sich darüber auch der Server beenden. Ein Linksklick wechselt die Anzeige des Serverprogramms direkt zwischen ein- und ausgeblendet. Das Server-Programm lauscht auf dem konfigurierten Port auf Zugriffe von Clients und dient damit gleichzeitig als Semaphore für den (synchronisierten) Zugriff mehrerer Kassen auf eine TSE, indem es die gesamte Kommunikation mit der TSE übernimmt.

Wichtig! Das Server-Programm sollte nach Möglichkeit entweder über den Aufrufcode "Z" oder über die GUI beendet werden, damit es seine Aufräumarbeiten (Logfile schreiben, Clients abmelden) korrekt erledi­gen kann.

2. Konsolenversion (nur Linux)

Das Server-Programm sollte später dauerhaft als Daemon laufen. Man kann es aber ebenso, z.B. zum Testen, manuell in einer Konsole starten. Es muß in jedem Falle als root gestartet werden und wechselt anschließend (nach dem Öffnen des Ports) in den Kontext des konfigurierten TSE-Users. Zum Beenden des Programms kann man diesem ein SIGTERM oder SIGINT-Signal senden. Dazu benötigt man die Prozess-Nummer, die man einfach aus dem PID-File ermitteln kann (z.B. "kill $(cat <pidfile>)"). Wenn das Programm in der Konsole läuft, kann man zum Beenden auch einfach "Ctrl-C" drücken.

Die Konsolen-Version sucht ihre Konfigurationsdatei per Default im Programmverzeichnis unter dem Namen "tse_server.conf". Das Server-Programm lauscht auf dem konfigurierten Port auf Zugriffe von Clients (beliebig viele, max. fünf zur exakt gleichen Zeit) und dient damit gleichzeitig als Semaphore für den (synchronisierten) Zugriff mehrerer Kassen auf eine TSE, indem es die gesamte Kommunikati­on mit der TSE übernimmt.

Sollten Sie zusätzliche Hilfe bei der Integration der Software in Ihren Server benötigen (Mount-Script, Start-/Stop-Scripte, Monitoring etc.), kontaktieren Sie uns bitte. Wir können Ihnen eine Vielzahl an Scripten, bis hin zu fertigen OpenVPN- und DynDNS-Lösungen über unsere eigenen Server anbieten.

Usage: tse_server [std_opt]

Die nachfolgenden Standardoptionen (std_opt) können verwendet werden:

• -c | --cfgfile <Dateiname>
  der Name (und optional der Pfad) der Konfigdatei
• -d | --loglevel { 0 | 1 | 2 | 3 | 4 }
  der Loglevel (Defaultwert s. Konfigdatei)
• -f | --logfile <Dateiname>
  der Pfad und Name des Log-Files (Defaultwert s. Konfigdatei)
• --logappend { 1 | 0 }
  soll das Log-File bei jedem Start überschrieben oder erweitert werden (Defaultwert s. Konfigdatei)
• -l | --lizfile <Dateiname>
  das Lizenz-File (Defaultwert s. Konfigdatei)
• -m | --mountpoint <Pfad>
  der Mountpoint der TSE (Defaultwert s. Konfigdatei)
• -v | --version
  die Ausgabe von Programmversion und Copyright-Info, dies schließt alle anderen Optionen aus
• -h | --help
  diese Hilfeanzeige (schließt alle anderen Optionen aus)
• -D | --daemon
  das Programm wird im Hintergrund als Daemon ausgeführt

Wichtig! Das Server-Programm sollte nach Möglichkeit entweder über den Aufrufcode "Z" oder über das Signal "SIGTERM" beendet werden, damit es seine Aufräumarbeiten (Logfile schreiben, Clients abmelden) korrekt erledigen kann.

VIII. Konfiguration

Die meisten Parameter für den normalen Betrieb werden aus der Konfigdatei gelesen. Diese Konfigda­tei wird standardmäßig im aktuellen Programmverzeichnis gesucht. Der Vorgabename lautet

• tse_admin.conf für das Adminprogramm
• tse_server.conf für das Serverprogramm

Per Kommandozeilenparameter (-c oder --cfgfile) kann auch ein anderer beliebiger Name und Pfad für die Konfigdatei angegeben werden. Die Konfigdatei ist nach dem üblichen Schema für Konfigurations­dateien aufgebaut. Es gibt Sektionen (in eckigen Klammern) und innerhalb dieser Sektionen Key-Va­lue-Einträge (key = value). Dabei sind beliebig viele Leerzeichen vor und hinter dem Key, dem Gleich­heitszeichen und dem Value erlaubt. Die Datei ist in drei Sektionen gegliedert:

• "global" (hier stehen allgemeine Werte)
• "log" (die Angaben zu Logfile, Loglevel etc.)
• "clients" (nur in der Server-Konfig, die Angaben zu den Kassen, die sich verbinden dürfen)

1. Einträge der Sektion "global":

1.1 Linux

• mountpoint
  der Mountpoint der TSE
  mandatory, eine absolute Pfadangabe
• lizfile
  das zugehörige Lizenzfile
  mandatory, entweder relativ zum Programmdirectory oder eine absolute Pfadangabe
• adminpin
  die Admin-PIN der TSE
  mandatory, muß unbedingt korrekt gesetzt sein
• timeofset
  der Zeitversatz der TSE gegenüber der Systemuhr
  optional, nur bei Entwickler-TSE möglich
  mit diesem Eintrag kann ein Zeitversatz angegeben werden, um den die interne TSE-Uhr gegenüber der Systemzeit nachgehen soll, der Wert wird in Sekunden angegeben, also 1 Jahr = 31536000
• transnullok
  gibt an, ob die Transaktionsnummer 0 gültig ist
  optional, nur beim Server möglich
  0 = default, die Transaktionsnummer 0 ist ungültig
  1 = alle Transaktionsnummern sinfd gültig
  sollte i.d.R. mit unserer Software nicht notwendig sein, hier wird dieser Firmwarebug umgangen, indem die Transaktionsnummer direkt bei der Initialisierung vergeben wird
• user
  der User, unter dem der TSE-Server laufen soll
  mandatory, nur beim Server notwendig
  es kann ein Name oder eine UID angegeben werden (Nutzer mit uid=0 müssen per Name spezifiziert werden), dieser User sollte mit dem Mount-Befehl korrespondieren
• group
  die Gruppe, unter der der TSE-Server laufen soll
  optional, nur beim Server möglich
  es kann ein Name oder eine gid angegeben werden (Gruppen mit gid=0 müssen per Name spezifiziert werden), wenn die Gruppenangabe fehlt, wird die primäre Gruppe des Users genutzt
• port
  der Port, auf dem der Server "lauscht"
  mandatory, nur beim Server notwendig
  da der Server den Port als root öffnet, können hier auch beliebige freie Ports unterhalb von 1024 genutzt werden
• daemon
  legt fest, ob sich das Programm von der Konsole abkoppelt
  optional, nur beim Server möglich
  0 = default, das Programm bleibt im Vordergrund und protokolliert in die Konsole
  1 = das Programm wird "deamonisiert", d.h. es wird von der Konsole abgekoppelt und läuft im Hintergrund weiter, die Konsole kann geschlossen werden
• pidfile
  das File, welches die PID des Prozesses enthält
  mandatory, nur beim Server notwendig
  relativ zum Programmdirectory oder eine absolute Pfadangabe, das Serverprogramm erzeugt diese Datei zwar beim Start, da sie jedoch erst nach dem Switch in den User-Kontext beschrieben wird, muß sie auch für den konfigurierten User schreib- und löschbar sein
  Wichtig! das PID-File wird unabhängig von dem Wert im Eintrag "daemon" erzeugt
• selftest
  die Uhrzeit, zu welcher der Selbsttest täglich (bevorzugt) ausgeführt werden soll
  optional
  spätestens aller 25 Stunden muß ein Selbsttest der TSE angestoßen werden, ansonsten verweigert die TSE den Dienst, da der Selbsttest bis zu 60 Sekunden dauert, kann man diesen z.B. auf die Nachtstunden verlegen, so vermeidet man eine Störung oder Verzögerung innerhalb der Kernarbeitszeit, sollte der nächste notwendige Selbsttest der TSE vor dieser Uhrzeit liegen, wird direkt beim Start des Programms ein einmaliger Selbsttest ausgeführt
• response
  legt die Antwort bei fehlerhaften Kommandos fest
  optional, nur beim Server möglich
  0 | 2 = default, der Fehlercode (je nach Request) wird als Response gesendet
  1 = keine Antwort bei Fehlern (kein Response)
• responsechar
  bestimmt die Zeichen, die an jeden Response angehangen werden
  optional, nur beim Server möglich
  leer = default, der Response wird "as it is" gesendet
  LF = es wird an jeden Response ein LF ("\n") angehängt
  CR = es wird an jeden Response ein CR ("\r") angehängt
  CRLF = es wird an jeden Response ein CRLF ("\r\n") angehängt
  Wichtig! beim Request werden unabhängig von dieser Einstellung in jedem Fall alle abschließenden CR, LF und Leerzeichen entfernt
• signatur
  bestimmt die Kodierung der vom Befehl "C" zurückgelieferten Signatur
  optional, nur beim Server möglich
  0 = default, die Signatur wird ab v0.99 in Base64-Kodierung, vorher in Octet-Kodierung zurückgeliefert
  1 = die Signatur wird in jedem Fall in Octet-Kodierung zurückgeliefert
• tarexportdir
  das Basis-Verzeichnis für den Tar-Export, der über den Server ausgeführt wird
  für das Kommando "J" mandatory, nur beim Server notwendig
  hier muß unbedingt ein gültiges Verzeichnis (relativ zum Programmdirectory oder ein absoluter Pfad) angegeben werden, aus Sicherheitsgründen ist es dem tse_server-Prozess nicht erlaubt, Daten oberhalb dieses Verzeichnisses abzulegen, somit bestimmt diese Angabe das Wurzelverzeichnis für den Tar-Export
• timeformat
  bestimmt das Format, in dem die Uhrzeit im Response zurückgegeben wird
  optional, nur beim Server möglich
  0 = default, der Response wird (wie bisher) als Unix-Timestamp (UTC) übermittelt
  1 = es wird die lokale Zeit im Format "dd.mm.yyyy hh:mm:ss +0100", also mit Angabe der Abweichung zu UTC, übermittelt, die Darstellung entspricht dabei der deutschen Locale, nicht aber der ISO-Norm
  2 = es wird die lokale Zeit im Format "yyyy-mm-ddThh:mm:ss+0100" nach ISO 8601-1:2019, also mit Angabe der Abweichung zu UTC, übermittelt
  3 = es wird die UTC-Zeit im Format "yyyy-mm-ddThh:mm:ssZ" nach ISO 8601-1:2019 übermittelt, das "Z" steht dabei für Zulu-Zeit (also UTC)
• checkprocdata
  schaltet eine zusätzliche Prüfung der übergebenen Nutzdaten vor der Weiterleitung an die TSE ein
  optional, nur beim Server möglich
  0 = default, keine Prüfung
  1 = das Feld "processtype" wird gegen die möglichen Typen laut DSFiNV-K geprüft
  2 = wie 1, zusätzlich wird die Syntax im Feld "processdata" laut DSFiNV-K geprüft (z.B. die erlaubten Transaktionstypen, die Zahlenformate, die Trennzeichen, die Reihenfolge der Zahlungen)
  3 = wie 2, zusätzlich werden bei "processtype=Kassenbeleg-V1" die Bruttosummen-Felder gegen die Felder mit den Zahlungen auf Gleichheit geprüft (außer bei Zahlung in Fremdwährung)

Die meisten Werte können auch per Kommandozeilenparameter übersteuert werden.

1.2 Windows

• mountpoint
  der Mountpoint der TSE
  mandatory, nur der Laufwerksbuchstabe gefolgt von einem Doppelpunkt
• init_timeout
  die Zeit in Sekunden, den das Serverprogramm auf die Bereitschaft des Mountpoint wartet, bevor es zu einem Fehler kommt
  optional, nur beim Server möglich
  damit kann der Server auch problemlos gestartet werden, wenn ein USB-Port oder -Hub erst verzögert aktiviert wird (z.B. im "Autostart")
• lizfile
  das zugehörige Lizenzfile
  mandatory, entweder relativ zum Programmdirectory oder eine absolute Pfadangabe
• adminpin
  die Admin-PIN der TSE
  mandatory, muß unbedingt korrekt gesetzt sein
• timeofset
  der Zeitversatz der TSE gegenüber der Systemuhr
  optional, nur bei Entwickler-TSE möglich
  mit diesem Eintrag kann ein Zeitversatz angegeben werden, um den die interne TSE-Uhr gegenüber der Systemzeit nachgehen soll, der Wert wird in Sekunden angegeben, also 1 Jahr = 31536000
• transnullok
  gibt an, ob die Transaktionsnummer 0 gültig ist
  optional, nur beim Server möglich
  0 = default, die Transaktionsnummer 0 ist ungültig
  1 = alle Transaktionsnummern sinfd gültig
  sollte i.d.R. mit unserer Software nicht notwendig sein, hier wird dieser Firmwarebug umgangen, indem die Transaktionsnummer direkt bei der Initialisierung vergeben wird
• port
  der Port, auf dem der Server "lauscht"
  mandatory, nur beim Server notwendig
• selftest
  die Uhrzeit, zu welcher der Selbsttest täglich (bevorzugt) ausgeführt werden soll
  optional
  spätestens aller 25 Stunden muß ein Selbsttest der TSE angestoßen werden, ansonsten verweigert die TSE den Dienst, da der Selbsttest bis zu 60 Sekunden dauert, kann man diesen z.B. auf die Nachtstunden verlegen, so vermeidet man eine Störung oder Verzögerung innerhalb der Kernarbeitszeit, sollte der nächste notwendige Selbsttest der TSE vor dieser Uhrzeit liegen, wird direkt beim Start des Programms ein einmaliger Selbsttest ausgeführt
• response
  legt die Antwort bei fehlerhaften Kommandos fest
  optional, nur beim Server möglich
  0 | 2 = default, der Fehlercode (je nach Request) wird als Response gesendet
  1 = keine Antwort bei Fehlern (kein Response)
• responsechar
  bestimmt die Zeichen, die an jeden Response angehangen werden
  optional, nur beim Server möglich
  leer = default, der Response wird "as it is" gesendet
  LF = es wird an jeden Response ein LF ("\n") angehängt
  CR = es wird an jeden Response ein CR ("\r") angehängt
  CRLF = es wird an jeden Response ein CRLF ("\r\n") angehängt
  Wichtig! beim Request werden unabhängig von dieser Einstellung in jedem Fall alle abschließenden CR, LF und Leerzeichen entfernt
• signatur
  bestimmt die Kodierung der vom Befehl "C" zurückgelieferten Signatur
  optional, nur beim Server möglich
  0 = default, die Signatur wird ab v0.99 in Base64-Kodierung, vorher in Octet-Kodierung zurückgeliefert
  1 = die Signatur wird in jedem Fall in Octet-Kodierung zurückgeliefert
• tarexportdir
  das Basis-Verzeichnis für den Tar-Export, der über den Server ausgeführt wird
  für das Kommando "J" mandatory, nur beim Server notwendig
  hier muß unbedingt ein gültiges Verzeichnis (relativ zum Programmdirectory oder ein absoluter Pfad) angegeben werden, aus Sicherheitsgründen ist es dem tse_server-Prozess nicht erlaubt, Daten oberhalb dieses Verzeichnisses abzulegen, somit bestimmt diese Angabe das Wurzelverzeichnis für den Tar-Export
• windowposx
  bestimmt die x-Koordinate des Serverfensters
  optional, nur beim Server möglich
  0 = default, das Fenster wird ganz recht unten angezeigt
  -1 = das Fenster wird horizontal zentriert auf dem Bildschirm angezeigt
  >0 = Anzahl Pixel vom linken Bildschirmrand bis zur linken Fensterkante
  <0 = Anzahl Pixel vom rechten Bildschirmrand bis zur rechten Fensterkante
• windowposy
  bestimmt die y-Koordinate des Serverfensters
  optional, nur beim Server möglich
  0 = default, das Fenster wird ganz recht unten angezeigt
  -1 = das Fenster wird vertikal zentriert auf dem Bildschirm angezeigt
  >0 = Anzahl Pixel vom oberen Bildschirmrand bis zur oberen Fensterkante
  <0 = Anzahl Pixel vom unteren Bildschirmrand bis zur unteren Fensterkante
• timeformat
  bestimmt das Format, in dem die Uhrzeit im Response zurückgegeben wird
  optional, nur beim Server möglich
  0 = default, der Response wird (wie bisher) als Unix-Timestamp (UTC) übermittelt
  1 = es wird die lokale Zeit im Format "dd.mm.yyyy hh:mm:ss +0100", also mit Angabe der Abweichung zu UTC, übermittelt, die Darstellung entspricht dabei der deutschen Locale, nicht aber der ISO-Norm
  2 = es wird die lokale Zeit im Format "yyyy-mm-ddThh:mm:ss+0100" nach ISO 8601-1:2019, also mit Angabe der Abweichung zu UTC, übermittelt
  3 = es wird die UTC-Zeit im Format "yyyy-mm-ddThh:mm:ssZ" nach ISO 8601-1:2019 übermittelt, das "Z" steht dabei für Zulu-Zeit (also UTC)
• checkprocdata
  schaltet eine zusätzliche Prüfung der übergebenen Nutzdaten vor der Weiterleitung an die TSE ein
  optional, nur beim Server möglich
  0 = default, keine Prüfung
  1 = das Feld "processtype" wird gegen die möglichen Typen laut DSFiNV-K geprüft
  2 = wie 1, zusätzlich wird die Syntax im Feld "processdata" laut DSFiNV-K geprüft (z.B. die erlaubten Transaktionstypen, die Zahlenformate, die Trennzeichen, die Reihenfolge der Zahlungen)
  3 = wie 2, zusätzlich werden bei "processtype=Kassenbeleg-V1" die Bruttosummen-Felder gegen die Felder mit den Zahlungen auf Gleichheit geprüft (außer bei Zahlung in Fremdwährung)

2. Einträge der Sektion "log" :

• logfile
  legt das File fest, wohin die Log-Daten ausgegeben werden
  optional
  muß bei Linux mit daemon=1 immer eine absolute Pfadangabe sein, wenn die Angabe fehlt oder das File nicht schreibbar ist, erfolgt die Ausgabe entweder auf die
  Konsole (unter Linux bei daemon=0) oder ins "Nirwana"
• logappend
  bestimmt die Erzeugung des Logfiles
  optional
  0 = default, das Logfile wird bei jedem Start neu erstellt (vermeidet zu große Logdateien)
  1 = das Logfile wird jeweils fortgeschrieben (kann sehr groß werden)
• loglevel
  legt den Loglevel fest
  optional
  folgende Loglevel sind definiert:
  0 = default, kein Log (es werden nur Fehler ausgegeben)
  1 = produktiv (wenige Ausgaben, für den produktiven Einsatz empfohlen)
  2 = info (mehr informative Ausgaben)
  3 = notice (sehr viele detaillierte Ausgaben)
  4 = debug (nur zur Debugzwecken, es werden sehr viele Daten ausgegeben)
  Wichtig! da während des laufenden Betriebes eine Menge an Daten anfallen können, wählen Sie für den produktiven Einsatz unbedingt einen loglevel von 1 oder 0

Bei der Konsolenversion können die meisten Werte per Kommandozeilenparameter übersteuert werden.

3. Einträge der Sektion "clients":

In der Sektion "clients" werden die Kassen eingetragen, die sich verbinden dürfen. Dabei ist der Key die eindeutige ClientID, also die Seriennummer der Kasse, wie sie vom Kassenhersteller vergeben und von der TSE gefordert wird. Der Value (Wert) ist eine frei wählbare, aber ebenfalls (pro TSE) eindeutige GUID. Der Aufbau entspricht dem bekannten Format von GUID's (s. Glossar). Diese GUID dient ausschließlich der Kommunikation und Authentifizierung zwischen dem ERP/Kasse und dem Serverprogramm. Dadurch ist der Request (unabhängig von der Länge der ClientID) immer gleich lang und die Sicherheit ist ebenfalls immer gleich hoch. Anschließend "übersetzt" das Serverprogramm die-
se GUID wieder in die ClientID, welche dann an die TSE gesendet wird.
Beispiel:
Kasse-0815 = 3CCEB42E-99CD-49D6-8B8A-536B8C3BE1D2
hierbei ist "Kasse-0815" die SN der Kasse (ClientID), welche auf dem Bon und in der TSE benutzt wird

Wichtig (nur Linux)!
Die Konfigdatei sollte nur für den User, der das Programm tse_admin ausführt, also z.B. root oder den TSE-User, les- und schreibbar sein, denn darin steht die PIN im Klartext.
chown tse:tse /opt/tse/tse.conf; chmod 0600 /opt/tse/tse.conf

IX. Glossar

• TSE
  Technische Sicherheitseinrichtung, als Technische Sicherheitseinrichtung wird ein Sicherheitsmodul in elektronischen Registrierkassen bezeichnet, das der lückenlosen und unveränderbaren Aufzeichnung aller Kassenvorgänge dient.
• KassenSichV
  deutsche Kassensicherungsverordnung, welche ab 1. Januar 2020 die vollständige, unveränderte und manipulationssichere Speicherung von Geschäftsvorfällen und einiger weiterer Vorgänge verlangt
• tse_server
  das Server-Programm der TSE-Middleware
• tse_admin
  das Admin-Programm der TSE-Middleware
• tse_server.conf
  die Konfigdatei für das Server-Programm der TSE-Middleware
• tse_admin.conf
  die Konfigdatei für das Admin-Programm der TSE-Middleware
• ClientID
  die Identifikation der Kasse gegenüber der TSE, i.d.R. die Seriennummer der Kasse, darf nur die folgenden Zeichen enthalten: a-z, A-Z, 0-9, Bindestrich
  wird vom tse_server-Programm anhand der Konfigdatei aus der GUID ermittelt
• AdminPIN
  die 5-stellige PIN des TSE-Administrators, wird für verschiedene Befehle benötigt (default=12345)
• TimeAdminPIN
  die 5-stellige PIN des TSE-Time-Administrators, wird für die TSE-Middleware nicht benötigt (default=12345)
• PUK
  die 6-stellige Notfall-PIN der TSE, hierüber kann man die Admin- und die TimeAdmin-PIN neu vergeben und so geblockte User wieder entsperren, nach dreimaliger Falscheingabe ist die TSE für immer gesperrt (default=123456)
• TSE-Selbstest
  eine interne Routine der TSE, die von deren Firmware ausgeführt wird, damit soll die korrekte Funktion der TSE sichergestellt werden
• TSE-TarExport
  ein Export aller TSE-Daten in einem genau definierten Format, es wird dabei von der TSE pro Message eine Datei erzeugt, anschließend werden diese Dateien in einem kompakten File abgelegt, der Tar-Export ist z.B. für Prüfvorgänge (Finanzamt) oder vor dem Löschen der TSE-Daten notwendig, zusätzlich sollte der Tar-Export im Rahmen einer Datensicherung zyklisch ausgeführt werden
• FactoryReset
  eine Möglichkeit, die TSE komplett auf Werkseinstellungen zurückzusetzen, geht nur bei sog. Entwickler-TSE's mit einer Developement-Firmware
• Signatur
  mit Hilfe eines kryptographischen Vorgangs wird eine Nachricht "signiert", später kann anhand dieser Signatur zweifelsfrei erkannt werden, ob die Nachricht nachträglich verändert wurde
• Transaktion
  eine Verarbeitung der TSE, bei der eine vom Client gesendete Zeichenfolge in der TSE gespeichert und signiert wird, diese Zeichenfolge ist damit nachträglich nicht mehr veränderbar, ohne daß die Signatur ungültig wird
• ProcessType
  beim Abschluß der Transaktion werden der TSE die zugehörigen (Nutz-)Daten übergeben, dabei gibt es z.Zt. drei Typen: "Bestellung", "Kassenbeleg" und "Sonstiger Vorgang"
• ProcessData
  beim Abschluß der Transaktion werden der TSE die zugehörigen (Nutz-)Daten übergeben, dabei gibt es (abhängig vom ProcessType) verschiedene Formate der Nutzdaten: bei "Bestellung" müssen Menge, Artikel und Preis, bei "Kassenbeleg" Transaktionstyp, Summen und Zahlungen übergeben werden, während beim "Sonstigen Vorgang" die Daten frei wählbar sind
• GUI
  Graphical-User-Interface, ein Programm mit einer "Fensterausgabe"
• SDK
  Software-Developement-Kit, ein Programmpaket, welches (meist vom Hersteller) mitgeliefert wird und in die Anwendungssoftware integriert ("einkompiliert") werden muß, diese SDK werden i.d.R. nur in ausgewählten Programmiersprachen bereitgestellt (bei der Swissbit-TSE sind dies C/C# und Java)
• Qt
  ein Anwendungsframework und GUI-Toolkit zur plattformübergreifenden Entwicklung von Programmen und grafischen Benutzeroberflächen
• ERP
  Programm für "Enterprise-Ressource-Planning", also eine "Warenwirtschaft" im weiteren Sinne
  QR-Code
• ein QR-Code (2D-Barcode) besteht aus einer quadratischen Matrix von schwarzen und weißen Quadraten, die die kodierten Daten binär darstellen. Eine spezielle Markierung in drei der vier Ecken des Quadrats gibt die Orientierung vor. Die Daten im QR-Code sind durch einen fehlerkorrigierenden Code erweitert. Dadurch wird der Verlust von bis zu 30% des Codes toleriert
• UTC
  Universal Coordinated Time, früher auch GMT (Greenwich Mean Time) genannt, hierbei handelt es sich um die sogenannte Normalzeit, d.h. eine weltweit eindeutige Uhrzeit, die auf dem Null-Meridian von Greenwich basiert
• LocalTime
  die lokale Uhrzeit, die sich aus der Verschiebung der aktuellen Region zur UTC ergibt, Deutschland nutzt eine Verschiebung von einer Stunde (UTC +1), diese Zone wird auch als MEZ (Mitteleuropäische Zeit) bezeichnet
• ISO 8601
  diese Norm ist ein internationaler Standard, der Empfehlungen über numerische Datumsformate und Zeitangaben enthält. Der (eingedeutschte) Titel der Norm lautet: "Datenelemente und Austauschformate - Informationsaustausch - Darstellung von Datum und Uhrzeit"
• Unix-Timestamp
  eine in der Unix-Welt gebräuchliche Darstellung für die Uhrzeit, hierbei werden die Sekunden seit dem 01.01.1970 in einer Zahl angegeben, dieser Wert ist immer in UTC (Universal Coordinated Time)
• Sommerzeit
  während des Winterhalbjahres (Standard) beträgt die Differenz der lokalen Zeit in Deutschland genau plus eine Stunde zur UTC-Zeit zur Sommerzeit, wenn also die Uhren vorgestellt sind und wir uns in der MESZ (Mitteleuropäische Sommerzeit) befinden, wächst diese Differenz auf plus zwei Stunden an die Winterzeit wird auch als CET (CentralEuropeanTime) und die Sommerzeit als CEST (CentralEuropeanSummerTime) bezeichnet
• SHA-2 / SHA-256
  Hash oder Prüfwert, beliebig lange Daten erzeugen immer die gleiche, kompakte Größe des Hashs, die Änderung an nur einem Bit hingegen führt dazu, dass ein komplett anderer Hashwert entsteht
• Octet
  besondere Darstellung von (nichtdruckbaren) ASCII-Zeichen, hierbei wird jedes Zeichen im Bereich von 0...255 durch seinen Hexcode dargestellt, es ergibt sich damit eine (durch zwei teilbare) Folge von Hex-Werten z.B. "B1A2\n" = "423141320A"
• Base64
  ein Verfahren zur Kodierung von 8-Bit-Binärdaten in eine Zeichenfolge, die nur aus lesbaren, Codepage-unabhängigen ASCII-Zeichen besteht, es wird z.B. für Mail-Anhänge benutzt, dabei werden aus jeweils drei Zeichen Input vier Zeichen Output erzeugt, weshalb die kodierten Daten ca. 33% mehr Platz beanspruchen
• GUID
  https://de.wikipedia.org/wiki/Globally_Unique_Identifier, eine 128 Bit (also 36 Zeichen) lange Zeichenfolge, die (praktisch) weltweit einmalig ist, die Darstellung erfolgt i.d.R. im Format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, die GUID wird nur für die Kommunikation zwischen Kasse/ERP und Middleware genutzt, von der Middleware wird später die "übersetzte" ClientID an die TSE gesendet
• Daemon
  ein bekannter Begriff unter Linux, mit dem Dienste bezeichnet werden, die im Hintergrund, losgelöst von der Konsole, arbeiten
• PID-File
  eine Datei, die bei Linux von Daemons erzeugt wird und die Prozessnummer des Dienstes enthält, sie wird u.a. zum Beenden des Dienstes verwendet
• Firmware
  die TSE besitzt eine eigene Software, die für die "Intelligenz" der TSE verantworltich ist, diese ist fest in der TSE verankert; mit unserer TSE-Middleware ist ein Update dieser Firmware ohne Internetzugriff möglich

 Dokumentation als PDF herunterladen