Implementierung Verschlüsselung im HIT-Protokoll für .NET

Im Rahmen der Neuentwicklung des HIT-Webs mit ASP.NET (als "HIT3") wurde auch die Implementierung des HIT-Protokolls ("HITP") als solches aus dem ebenfalls mit ASP.NET implementierten "ZID2"-Web übernommen. Die dortige Implementierung der Verschlüsselung jedoch wurde durch ein größtenteils automatisiertes Verfahren aus dem Java-Code erzeugt und war daher mäßig performant. Für "HIT3" wurden daher die Verschlüsselungsverfahren nativ in C# (basierend auf der Java-Logik) implementiert.

TODO - Dokument und .NET-Assembly sind out-of-date!!
Muss leider umfangreich umgestellt werden und wird für .NET-Anwendungen nicht abwärtskompatibel sein!
Das Assembly unten kann dennoch weiterhin genutzt werden.

Die Verschlüsselung in der Kommunikation mit HIT läuft über zwei Ebenen:

	Anmeldung an HIT mit asymmetrischer Verschlüsselung
	Datenaustausch mit HIT (und Abmeldung von HIT) mit symmetrischer Ver- und Entschlüsselung

Mehr Details dazu hier.

Ein verschlüsselter Datenaustausch erfordert eine erfolgreiche verschlüsselte Anmeldung an HIT. Umgekehrt jedoch erfordert eine erfolgreiche verschlüsselte Anmeldung nicht zwingend einen verschlüsselten Datenaustausch, ist aber zu empfehlen!

Nur mit verschlüsseltem Datenaustausch: war eine verschlüsselte Anmeldung erfolgreich, dann bleibt die Verschlüsselung bis zur nächsten neuen verschlüsselten Anmeldung oder zum expliziten Abmelden aktiv - sowohl für HITP-Befehle als auch für HITP-Antworten. Eine nicht erfolgreiche Anmeldung aktiviert keine Verschlüsselung, d.h. es können dann (ausser einer neuen Anmeldung) nur unverschlüsselte Befehle gesendet und unverschlüsselte Antworten erhalten werden.

In den folgenden Beispielen werden C#-Codestücke, HIT-Befehle und -Antworten aus optischen Gründen teilweise mehrzeilig angezeigt.
Technisch sind sie ohne Zeilenumbruch als eine einzelne Zeile aufzufassen!

Verwendung

Das Assembly ist so ausgelegt, dass sie bereits zum Versand fertig vorliegende Befehle, die an HIT-Server gesendet werden sollen, verschlüsseln und umgekehrt die vom HIT-Server erhaltenen verschlüsselten Antworten entschlüsseln kann. Das Erzeugen der HIT-Befehle und Auswerten der HIT-Antworten ist somit der eigentlichen Anwendung vorbehalten, die die Assembly nutzt.

Nach dem Einbinden der Assembly in ein eigenes Projekt in eigenen C#-Programmen dessen Namespace einbinden:

using HIT3.Secure;

Hexstrings

Da mit Bytes in einem text-basieren Datenaustauschprotokoll nicht gearbeitet werden kann, werden binäre Daten im HIT-Protokoll als Hexstrings aufgefasst. Ein Byte (8 bit) wird in sein entsprechendes hexadezimales Äquivalent in Form einer 2-stelligen Zeichenkette mit dem Zeichensatz 0 bis 9 und A bis F und Bytearrays (= byte[]) dementsprechend in eine Zeichenkette mit der doppelten Länge des Bytearray gewandelt.
Hexstrings sind nicht zu verwechseln mit dem ebenfalls im HIT-Protokoll verfügbaren Hex-Encoding in der %xx-Schreibweise!

Das Assembly bietet zwei Hilfsfunktionen, um in beide Richtungen wandeln zu können: von Bytearray zu Hexstring und zurück.

Beispiel: das Byte mit dem Wert 72 als Hexstring

using HIT3.Secure;

byte   demo      = 72;
String hexstring = Helper.hexEncode(new byte[] { demo });     // das einzelne Byte in ein Bytearray verpacken
Console.WriteLine(hexstring);

Wird der Code ausgeführt, erhält man "48".

Decodieren läuft ähnlich:

using HIT3.Secure;

String hexstring = "49485470";
byte[] demo = Helper.hexDecode(hexstring);

Öffentlicher Schlüssel

Der öffentliche Schlüssel für die asymmetrische Verschlüsselung ist hier veröffentlicht.

Dieser kann in der Assembly als Bytearray oder als Hexstring vewendet werden:

using HIT3.Secure;

String pubkeyHex = "4801525001000...0003010001";
HitSecurityKey pubkey = new HitSecurityKey(pubkeyHex);

pubkey wird später dann für die Verschlüsselung des Anmeldebefehls verwendet.

Verbindungsaufbau

Unabhängig von unverschlüsseltem oder verschlüsseltem Datenaustausch müssen nach dem Verbindungsaufbau die Antworten als erstes gelesen werden. Nur wenn die Antworten keine Fehler anzeigen (erkennbar an <Schwere> in der Antwortstruktur), darf fortgesetzt werden. Anderenfalls ist zu einer anderen HIT-Serverinstanz zu verbinden.

Die Antwortzeile mit dem <AntwortCode> (=Plausinummer) 2600 ist für verschlüsselten Datenaustausch relevant und somit zwischenzuspeichern!

UTF-8

Der HIT-Server kann inzwischen sowohl den Standard-Zeichensatz als auch UTF-8 verstehen. Man sollte daher beim Anlegen eines StreamReader und StreamWriter über den Netzwerkstream zum Lesen und Schreiben von Zeichenketten die gewünschte Codierung für die Umwandlung zwischen bytes und chars mitgeben.
Wichtig dabei: Der HIT-Server versteht UTF-8 nur ohne den Byte Order Mark (BOM).

Beispiel:

using System.IO;
using System.Text;

Encoding UTF8_noBOM = new UTF8Encoding(false);	    // false = ohne BOM
StreamReader in  = new StreamReader(networkStream,UTF8_noBOM);
StreamWriter out = new StreamWriter(networkStream,UTF8_noBOM);

(networkStream ist die Verbindung zum HIT-Server)

Ohne UTF-8 wäre dies lediglich:

using System.IO;
using System.Text;

StreamReader in  = new StreamReader(networkStream);
StreamWriter out = new StreamWriter(networkStream);

Wird UTF-8 verwendet, dann muss beim Anmelden die Spalte UTF8 mit dem Wert 1 (unabhängig von Verschlüsseln oder nicht) mitgesendet und auch in der Folge im Verschlüsselungs- und Entschlüsselungsprozess mitberücksichtigt werden!

Asymmetrisch Verschlüsseln für Anmeldung

Für die verschlüsselte Anmeldung sind beim Senden der Entität LOGON neben den Anmeldeinformationen auch die Spalten SVR_HELO, SESS_KEY und RAND_CLI von Bedeutung. Auch die Spalte UTF8 spielt eine Rolle. Diese Vorarbeit ist zu leisten, bevor der komplette Anmelde-Befehl verschlüsselt wird!

	SVR_HELO: erforderlich ist exakt der komplette Text des <Textelemente> der Antwort vom HIT-Server mit dem <AntwortCode> 2600, wenn die Verbindung aufgebaut wurde (siehe Verbindungsaufbau) beginnt mit HitServer bereit. Version ... und endet mit der zufälligen Challenge
	RAND_CLI: erforderlich sorgt dafür, dass eine zufällige, nur dem Client bekannte Bytefolge mitverschlüsselt wird, um das "Erraten" der Anmeldung zu erschweren hat Server-seitig keine Relevanz zufällige Bytefolge, die als Hexstring aufbereitet sein muss mindestens 30 Bytes (mind. 60 Zeichen als Hexstring)
	SESS_KEY: optional; wird angegeben, wenn man nach der Anmeldung verschlüsselten Datenaustausch haben möchte zufällige Bytefolge, die als Hexstring aufbereitet sein muss maximal 48 Bytes (also max. 96 Zeichen als Hexstring) muss zwischengespeichert werden für die folgende symmetrische Verschlüsselung des Datenaustausches
	UTF8: optional; wird angegeben, wenn man nach der Anmeldung Daten im Zeichensatz UTF-8 austauschen möchte nur der Wert 1 ist zulässig; will man kein UTF-8, dann die Spalte nicht angeben! wird UTF-8 verwendet, muss das bei den nachfolgenden Verschlüsselungen berücksichtigt werden ohne die Spalte wird der System-Zeichensatz (unter Windows bspw. Windows-1252 verwendet)
	ENC_SYM: optional; wird angegeben, wenn man nach der Anmeldung Daten in einer bestimmten Transformationsvorschrift symmetrisch verschlüsseln will TODO

Anlegen eines zufälligen SESS_KEY:

byte[] sessKeyBytes = HitSecure.getRandomArray(48);
String sessionKey = Helper.hexEncode(sessKeyBytes)

Man erhält dann beispielsweise

DF3D8AAFD57F6601A6700801B725112A869E6542027CAE690E7F5F3B82ED7C5A05D3C1B6B4EF0C4F300DD4E0ACD7D7C8

Genauso kann für RAND_CLI verfahren werden.

Beispiel

Anmeldung unverschlüsselt:

*1:XS:LOGON/BNR15;PIN;MELD_WG;CHA;MAXCERR;TIMEOUT:
09 199 000 0031;Aaaa$900000;3;0;0;1200

erweitert um Spalten für verschlüsselte Anmeldung ohne folgendem verschlüsselten Datenaustausch:

*1:XS:LOGON/BNR15;PIN;MELD_WG;CHA;MAXCERR;TIMEOUT;SVR_HELO;RAND_CLI:
09 199 000 0031;Aaaa$900000;3;0;0;1200
;HitServer bereit. Version 2600, 01.04.2019 00-00. Sie sind mit dem Testsystem T1B_HZ05 verbunden.
 Nur eingeschraenkt verfuegbar, da hier entwickelt wird. (Server benutzt neue Betriebstabellen/NEWADS)
 HI-Tierzeit 11.04.2019, 13-19-38h Challenge -2251982346156064082
;164FD11B482B793CAC1243ED076F731D73A34DB182329EF794C82E8590625B35F16BF3D89A84DA72DC1911ECC53A44B5

erweitert um Spalten für verschlüsselte Anmeldung mit folgendem verschlüsselten Datenaustausch (Spalte SESS_KEY und optional ENC_SYM dazu):

*1:XS:LOGON/BNR15;PIN;MELD_WG;CHA;MAXCERR;TIMEOUT;SVR_HELO;SESS_KEY;RAND_CLI;ENC_SYM:
09 199 000 0031;Aaaa$900000;3;0;0;1200
;HitServer bereit. Version 2600, 01.04.2019 00-00. Sie sind mit dem Testsystem T1B_HZ05 verbunden.
 Nur eingeschraenkt verfuegbar, da hier entwickelt wird. (Server benutzt neue Betriebstabellen/NEWADS)
 HI-Tierzeit 11.04.2019, 13-19-38h Challenge -2251982346156064082
;DF3D8AAFD57F6601A6700801B725112A869E6542027CAE690E7F5F3B82ED7C5A05D3C1B6B4EF0C4F300DD4E0ACD7D7C8
;164FD11B482B793CAC1243ED076F731D73A34DB182329EF794C82E8590625B35F16BF3D89A84DA72DC1911ECC53A44B5;2

Abschließend wird asymmetrisch verschlüsselt und dem erhaltenen Hexstring ein $ vorangestellt, damit der HIT-Server weiss, dass er diese Anfrage asymmetrisch entschlüsseln muss:

using HIT3.Secure;

String request = "*1:XS:LOGON/BNR15;....11ECC53A44B5;2";                // kompletter String vom Absatz vorher
request  = HitSecure.encodeAsymmetric(request,false,pubkey,true);

pubkey beim Methodenaufruf encodeAsymmetric() ist der öffentliche Schlüssel als Instanz vom Typ HitSecurityKey (siehe oben).
Das false beim zweiten Parameter zeigt an, dass keine UTF-8-Codierung verwendet wird. Gibt man true an, muss beim LOGON auch die Spalte UTF8 mit dem Wert 1 mitverschlüsselt werden.
Das true beim vierten Parameter zeigt an, dass vor dem erhaltenen Hexstring automatisch noch das $ vorangestellt werden soll.

Das erhaltene request sieht dann beispielsweise so aus:

$0202002AC0888754C9E5062134D155...000D2E40BB0C79E8B028647971DA56

(ist inklusive SESS_KEY etwa 1500-1600 Zeichen lang!)

Die gesamte Zeile kann jetzt (abgeschlossen mit CRLF) als Zeichenkette über die bestehende Socket-Verbindung an HIT gesendet werden.

Hat man die Spalte SESS_KEY mitgegeben, erhält man bei einem erfolgreichen LOGON eine symmetrisch verschlüsselte Antwort. Ist die Anmeldung gescheitert oder wurde kein SESS_KEY mitgegeben, dann erhält man eine unverschlüsselte Antwort. Die symmetrisch verschlüsselte Antwort zeigt auch an, dass ab sofort bis zur Abmeldung der Datenaustausch mit Befehlen und Abfragen und deren Antworten symmetrisch verschlüsselt werden müssen und sind.

Übrigens: Client-seitig müssen und können keine asymmetrisch verschlüsselten Zeichenketten decodiert werden, da für den Vorgang der private Schlüssel benötigt wird, den nur die Zentrale Datenbank besitzt.

Symmetrisch ver- und entschlüsseln

Die Antworten einer erfolgreichen verschlüsselten Anmeldung und folgende Anfragen und Antworten sind symmetrisch verschlüsselt, wenn beim LOGON die Spalte SESS_KEY mitgeliefert wurde. Dazu wird eine Anfrage und auch eine Antwort des HIT-Protokolls mit diesem SESS_KEY verschlüsselt und dem erhaltenen Hexstring ein # vorangestellt.

Verschlüsseln, z.B. die Abfrage von bestimmten CODES:

using HIT3.Secure;

String request = "*2:RS:CODES/CODESET;CODENR;CODE;CODETEXT:CODENR;BW;1;4;ORDER;1;2";
request = HitSecure.encodeSymmetric(request,false,sessionKey,2,true);

Der sessionKey wurde zu Beginn vor dem LOGON per Zufall generiert und bleibt während der gesamten Sitzung bis zur Abmeldung gleich.
Das false beim zweiten Parameter steuert das UTF8-Encoding: wenn beim LOGON oben false verwendet wurde, muss das hier indentisch verwendet werden. true beim LOGON heisst auch true hier.
Der 2er ist der Wert der Spalte ENC_SYM vom LOGON, damit die Methode weiss, wie sie symmetrisch verschlüsseln soll.
Das true beim fünften Parameter zeigt an, dass vor dem erhaltenen Hexstring automatisch noch das # vorangestellt werden soll.

Entschlüsseln vom HIT-Server erhaltene Antwortzeilen:

using HIT3.Secure;

String response;
while ( (response = readline()) != null) {
   // wenn verschlüsselt, dann erst decodieren
   if (response.StartsWith("#"))	{
      response = HitSecure.decodeSymmetric(response.Substring(1),sessionKey,false);   // true, wenn UTF8 beim LOGON verwendet wurde
   }
   // entschlüsselte Antwort auswerten
   HitAntwort antwort = HitAntwort.parse(response);
   // wenn Antwort nicht die letzte, dann lies nächste Zeile von HIT
   if (antwort == null) {
      // es war keine HitAntwort oder entschlüsseln schlug fehl
      throw new IOException();
   }
   else if (antwort.IstLetzteAntwort) {
      // es ist die letzte, also Lesen abbrechen
      break;
   }
   // nächste lesen
}

Eine verschlüsselte HIT-Antwort beginnt mit einem #, also prüft man das ab und decodiert nur dann mit dem bekannten SESS_KEY (ab dem zweiten Zeichen, daher das Substring(1)). Der Decoder erkennt automatisch, welcher ENC_SYM seitens des Servers verwendet wurde und reagiert entsprechend - daher muss der Parameter nicht übergeben werden.

readline() liefert beispielhaft die nächste Zeile von der HIT-Verbindung (z.B. via StreamReader). Die Klasse HitAntwort ist eine beispielhaft selbst zu implementierende Klasse mit einem Parser (parse()) und Eigenschaften zum Abfragen wie z.B. IstLetzteAntwort. Der Lesealgorithmus ist hier näher beschrieben.

Aus einer response

#4C2BE5296EC91A8F1B2BADC9FD1462...14E77FE4B0715582DE23D82D6F7AE7

würde dann beispielsweise

=2%1652:1/121:CODES:Anzahl Datenzeilen - 1651;Select CODESET,...;Dauer=0.242[Sek.]

decodiert. Da die Antwort die letzte in einer Reihe ist (erkennbar am = zu Beginn), bricht hier die Lese-Schleife ab.

Kurz & bündig

Relevante Konstruktoren und Methodenaufrufe in der Assembly

Bytes & Strings:

	Bytes in Hexstring: Hexstring HIT3.Secure.Helper.hexEncode(byte[])
	Hexstring in Bytes: byte[] HIT3.Secure.Helper.hexDecode(Hexstring)

	zufällige Bytes: byte[] HIT3.Secure.HitSecure.getRandomArray(int)
	UTF-8 Encoding ohne BOM: new System.Text.UTF8Encoding(false)
	System-Encoding: System.Text.Encoding.Default (existiert bereits als Eigenschaft)

Schlüssel (für symmetrisch und asymmetrisch gleichermaßen):

new HIT3.Secure.HitSecurityKey(Hexstring)

Asymmetrisch verschlüsseln:

(Achtung: Aufrufsignatur geändert für den unten angebotenen Download!)

HIT3.Secure.HitSecure.encodeAsymmetric(String,bool,HIT3.Secure.HitSecurityKey,bool)

Symmetrisch ver- und entschlüsseln

(Achtung: Aufrufsignaturen geändert für den unten angebotenen Download!)

	Hexstring HIT3.Secure.HitSecure.encodeSymmetric(String,bool,HIT3.Secure.HitSecurityKey,int,bool)
	String HIT3.Secure.HitSecure.decodeSymmetric(Hexstring,HIT3.Secure.HitSecurityKey,bool)

Download

Assembly mit VisualStudio-XML-Dokumentation: 20220614_HitSecureLib.zip für .NET 4 und höher

Es wird trotz ausgiebiger Tests und Einsatz in unserer eigenen Webanwendung keinerlei Gewähr auf Richtigkeit der Funktionalität
und in der Folge auch keine Verantwortung bzgl. möglicher Datenverluste übernommen !

Der Sourcecode in Java, auf dem dieses Assembly basiert, kann aus der HitUpros-Bibliothek entnommen werden,
welcher beim HitBatch-Client als hitbatch-sources.zip verfügbar ist.
Die Klasse de.hi_tier.hitupros.HitSecurity ist der Einstiegspunkt zur Anwendung der Ver- und Entschlüsselung, mehr Details hierzu.