Technische Sicherheitseinrichtung für Kassensysteme in Deutschland - Kassensignatur.de

Funktionen der Technischen Sicherheitseinrichtung (TSE)

Die "Technische Sicherheitseinrichtung" wird als Software-Dienst bereitgestellt. Die Verbindung erfolgt über das Internet. Für die Kommunikation wird eine REST API über eine verschlüsselte HTTPS-Verbindung genutzt. Folgende Funktionen stehen über die Technische Sicherheitseinrichtung zur Verfügung:

Administrations-Funktionen der Technischen Sicherheitseinrichtung

REST API-Funktion: initialize

Die Technische Sicherheitseinrichtung muss vor der produktiven Verwendung durch das Kassensystem initialisiert werden. Eine Beschreibung der Technischen Sicherheitseinrichtung muss vom Kassensystem übermittelt werden.

Der Aufruf der API erfolgt über die folgende URL:

https://name-des-signaturservers/v1/initialize/{clientID}

Beim Aufruf der REST-API ist die Seriennummer {clientID} des Kassensystems (INT) in der URL anzugeben.

Entsprechend der BSI TR-03151 ist für den Aufruf der Funktion initialize nur der folgende Parameter erforderlich:

  • Input-Parameter [POST]: description (string) - Kurze Beschreibung der Sicherheitseinrichtung

Für die Authentifizierung der Funktion initialize sind bei unserer API jedoch zusätzlich folgende Input-Parameter zu per POST zu übergeben:

  • Input-Parameter [POST]: customerID (string) - Kundennummer bei uns (12-stelliger String
  • Input-Parameter [POST]: name (string) - Benutzername für die Technische Sicherheitseinrichtung
  • Input-Parameter [POST]: password (string) - Passwort für die Technische Sicherheitseinrichtung

Die zusätzlichen Input-Paramter customerID, name und password erhalten Sie durch uns und sind für die  Initialisierung erforderlich.

Bei fehlenden Parametern wird eine entsprechende Fehlermeldung zurückgegeben, wie z. B. folgende JSON-Antwort:

{
    "operationType": "initialize",
    "error": "ErrorStoringInitDataFailed",
    "errorDescription": "Name or Password  missing for CashID #666665."
}

Nach Erfolgreicher Initialisierung der Technischen Sicherheitseinrichtung wird z. B. folgende JSON-Meldung zurückgegeben:

{
    "version": 1,
    "certifiedDataType": "bsi-de (0.4.0.127.0.7.0) applications (3) sE-API (7) sE-API-dataformats(1) 2",
    "transactionNumber": 27,
    "logTime": "2019-03-05 19:11:02Z",
    "operationType": "initialize",
    "serialNumber": "6d85b86dfc766fe9c0af6d0b17f0359b9041c219889411b562cbb792a17bbcef",
    "token": "5E00011410FAF6B4C92204455F280B0B",
    "return": "EXECUTION_OK"
}

In der Antwort des Funktionsaufrufs ist die serialNumber der Technischen Sicherheitseinrichtung enthalten, die im Kassensystem zur späteren Verwendung gespeichert werden muss. Der Rückgabeparameter token ist für alle Aufrufe der REST-API erforderlich. 

Durch den Aufruf der Funktion initialize werden in der Speichereinheit entsprechende Verzeichnisse erstellt, sowie ein privater und öffentlicher Schlüssel für die Signierung der Kassendaten erzeugt.

Nach der erfolgreichen Initialisierung ist das Kassensystem mit der Technischen Sicherheitseinrichtung verbunden.

 

 

REST API-Funktion: updateTime

Über die updateTime-Funktion wird die Zeitsynchronisation der technischen Sicherheitseinrichtung aufgerufen. Die Synchronisation erfolgt durch einen deutschen Zeitserver. Alle Zeitangaben werden in UTC angegeben. UTC steht für Universal Time Coordinated, früher auch offiziell als GMT (Greenwich Mean Time) bezeichnet. Ein Überschreiben der Zeit ist nicht möglich, um Zeitmanipulationen zu verhindern. Der Aufruf der Funktion erfolgt über die folgende URL:

https://name-des-signaturservers/v1/updateTime/{clientID}

Beim Aufruf der REST-API ist die Seriennummer {CashID} des Kassensystems (INT) in der URL anzugeben.

Entsprechend der BSI TR-03151 ist für den Aufruf der Funktion updateTime nur der folgende Parameter erforderlich:

  • Input-Parameter [POST]: useTimeSync (bool) - Synchronisation der Uhrzeit TRUE/FALSE

Der Input-Parameter newDateTime ist nicht erforderlich, da die Änderung der Zeit nicht möglich ist.

Für die Authentifizierung der Funktion updateTime muss bei jedem Aufruf der Input-Parameter per POST übergeben werden:

  • Input-Parameter [POST]: token (string) - Security Token (aus der Funktion initialize)

Bei fehlenden oder falschen Parametern wird eine entsprechende Fehlermeldung zurückgegeben, wie z. B. folgende JSON-Antwort:

{
    "operationType": "updateTime",
    "error": "ErrorSetTimeFailed",
    "errorDescription": "Value error of useTimeSync."
}

Bei erfolgreichem Aufruf der updateTime Funktion mit dem Parameter useTimeSync = TRUE wird z. B. folgende Rückmeldung im JSON-Format zurückgegeben:

{
    "systemFunctionData": "0x812019-03-07 18:04:56Z0x822019-03-07 18:04:56Z",
    "protocolData": "updateTime",
    "return": "EXECUTION_OK"
}

Input-Funktionen der Technischen Sicherheitseinrichtung

REST API-Funktion: startTransaction

Die startTransaction-Funktion übernimmt die Parameter des Kassensystems und verarbeitet diese entsprechend den Vorgaben der technischen Richtlinie des BSI.

Die startTransaction-Funktion muss zu Beginn einer Kassenbewegung - z. B. Kassiervorgang, Stornierung, Kassenentnahme, Kassseneinzahlung - durch die Kassensoftware aufgerufen werden.

Wenn also ein Kunde für den Kassiervorgang ausgewählt wird oder die erste Dienstleistung bzw. das erste Produkt für den Kassiervorgang ausgewählt wird, startet eine neue "Transaktion". Jede Transaktion wird ein der technischen Sicherheitseinrichtung verarbeitet und gespeichert.

Zum Start der Protokollierung muss das Kassensystem eine Vorgangs-ID zur Identifikation des Vorgangs generieren. Das Kassenprogramm muss außerdem die Seriennummer des Kassensystems, die Art des Vorgangs (z. B. "Rechnung") und die bereits erzeugten Daten des Vorgangs über die REST API (Einbindungsschnittstelle) an die Technische Sicherheitseinrichutng übermitteln.

Die Technische Sicherheitseinrichtung gibt den Zeitpunkt des Vorgangsbeginns, die Transaktionsnummer, den Signaturzähler und den Hashwert über den öffentlichen Schlüssel, der für die Signatur verwendet wurde, zurück.

REST API-Funktion: updateTransaction

Die updateTransaction-Funktion übernimmt die Parameter des Kassensystems und verarbeitet diese entsprechend den Vorgaben der technischen Richtlinie des BSI.

Die updateTransaction-Funktion muss durch das Kassensystem aufgerufen werden, wenn sich nach dem Start der Transaktion und vor dem Ende der Transaktion Änderungen ergeben. Wenn z. B. weitere Dienstleistungen oder Produkte beim Kassiervorgang ergänzt werden oder die Stückzahlen der ausgewählten Produkte/Dienstleistungen verändert werden, muss die updateTransaction-Funktion aufgerufen werden. Jede Änderung der Transaktion wird ein der technischen Sicherheitseinrichtung verarbeitet und gespeichert.

Das Kassenprogramm muss  die Seriennummer des Kassensystems, die Transaktionsnummer des aktualisierten Vorgangs und die neuen Daten des Vorgangs über die REST API an die Technische Sicherheitseinrichtung übermitteln.

Die Technische Sicherheitseinrichtung speichert die abgesicherten Protokolldaten sowie die zugehörigen Anwendungsdaten auf dem zentralen Speichersystem und gibt den Zeitpunkt des Updates der Transaktion an das Kassensystem zurück.

REST API-Funktion: finishTransaction

Die finishTransaction-Funktion übernimmt die Parameter des Kassensystems und verarbeitet diese entsprechend den Vorgaben der technischen Richtlinie des BSI.

Das Kassensystem muss unmittelbar mit der Beendigung oder dem Abbruch des aufzuzeichnenden Vorgangs  die Protokollierung der Transaktion abschließen.

Das Kassenprogramm muss hierzu die Seriennummer des Aufzeichnungssystems, die Transaktionsnummer, die Art des Vorgangs und die neuen Daten des Vorgangs über die REST API an die Technische Sicherheitseinrichtung übermitteln.

Die Technische Sicherheitseinrichtung speichert die abgesicherten Protokolldaten sowie die zugehörigen Anwendungsdaten auf dem zentralen Speichersystem und gibt den Zeitpunkt der Beendigung der Transaktion an das Kassensystem zurück.

Export-Funktionen der Technischen Sicherheitseinrichtung

REST API-Funktion: export

REST API-Funktion: getLogMessageCertificate

REST API-Funktion: restoreFromBackup

REST API-Funktion: readLogMessage

Durch den Aufruf der Funktion readLogMessage wird die zuletzt protokollierte Lognachricht wieder gegeben.

Der Aufruf der API erfolgt über die folgende URL:

https://name-des-signaturservers/v1/readLogMessage/{clientID}

Beim Aufruf der REST-API ist die Seriennummer {CashID} des Kassensystems (INT) in der URL anzugeben.

Entsprechend der BSI TR-03151 ist für den Aufruf der Funktion readLogMessage kein Parameter erforderlich.

Für die Authentifizierung der Funktion readLogMessage muss bei jedem Aufruf der Input-Parameter per POST übergeben werden:

  • Input-Parameter [POST]: token (string) - Security Token (aus der Funktion initialize)

Bei einem erfolgreichen Aufruf wird die letzte Lognachricht zurückgegeben wie z. B. folgende JSON-Antwort:

{
    "logMessage": "{\"operationType\":\"updateTime\",\"error\":\"ErrorSetTimeFailed\",\"errorDescription\":\"Missing of useTimeSync.\"}",
    "logMessageFile": "666666_0_2019-03-10 15:02:25Z_SYSTEM7.der",
    "return": "EXECUTION_OK"
}

Bei fehlenden oder falschen Parametern wird eine entsprechende Fehlermeldung zurückgegeben, wie z. B. folgende JSON-Antwort:

{
    "operationType": "readLogMessage",
    "error": "ErrorReadingLogMessage",
    "errorDescription": "Token 666665#C4942C3CF0E75024DD3B756AB8EC80D9 not valid."
}