Mittels dieser Schnittstelle können Sie als Drittsystemanbieter Alarmdaten, Fahrzeugstatus sowie Fahrzeugpositionen an FE2 übermitteln. Die Übertragung erfolgt über unseren RabbitMQ-HA-Cluster, daher müssen die empfangenden Systeme über keine https:// Freigabe über das Internet verfügen (im Gegensatz zur externen Schnittstelle). Dadurch ist für die Zielsysteme eine sehr komfortable Anbindung möglich. Die Übermittlung der Nutzdaten erfolgt vollständig Ende-zu-Ende verschlüsselt.

Inhalt

1 API-Schlüssel
2 Zugriffspunkte / REST Endpoints
3 Datenformat
- 3.1 Anmerkungen zum Datenformat
- 3.2 Topic, Felder und Kunden-Identifikation
  - 3.2.1 Beispiel
- 3.3 Verschlüsselung
- 3.4 Base64 Encoding
- 3.5 Austausch der Werte von Drittanbieter mit Kunde

API-Schlüssel

Für die Anbindung benötigen Sie einen API-Schlüssel.

API-Schlüssel können nur von Unternehmen, nicht von Privatpersonen angefordert werden.

Ein API-Schlüssel kann per E-Mail an kontakt (at) alamos-gmbh.com unter Angabe der folgenden Daten angefordert werden:

Name des Drittanbieters	Gewünschter, für die Erstellung genutzter Name, z.B. abcgmbh Zeichensatz [a-zA-Z0-9]
Ansprechpartner E-Mail, Telefonnummer & Firmen-Website	Für Rückfragen und spätere Kommunikation.
Beabsichtigter Einsatzzweck	Eine kurze Beschreibung, wie die Schnittstelle genutzt werden soll.
Geschätzte Nutzung pro 24 Stunden	Ungefähres Aufkommen an Meldungen (Alarme, inkl. Status und Positionen) pro Tag. Grobe Schätzung.
Nutzungsbedingungen unterschrieben

API-Schlüssel können kostenfrei genutzt werden, wenn die beabsichtigten Empfänger im BOS-Umfeld angesiedelt sind. Für eine kommerzielle Nutzung bitte über die o.g. E-Mail-Adresse anfragen.

Zugriffspunkte / REST Endpoints

Die Übermittlung der Daten findet über REST-Schnittstellen statt.

Die konkreten Pfade sowie Beispieldaten können über Swagger UI eingesehen und getestet werden.

OpenAPI Dokumentation

Für den Zugriff auf Swagger UI verwenden Sie folgende Benutzerdaten:

Benutzername:

user

Passwort:

user@alamosopenapi

Datenformat

Das unverschlüsselte Datenformat der Nutzdaten finden Sie unter:

Datenformat Externe Schnittstelle

Anmerkungen zum Datenformat

Das Feld authorization im Datenformat muss nicht gefüllt werden.
Das Array units enthält eine Liste von allen Einheiten, welche alarmiert werden. address entspricht hierbei dem Code bzw. der Kennung der Einheit.
- Sie müssen sich immer mit dem Kunden austauschen, damit die richtige Einheit im System des Kunden existiert und auch alarmiert werden kann. Wenn Sie versuchen, Einheiten zu alarmieren, deren Kennung nicht im Zielsystem existiert, erhalten Sie in der Response selbst keine Fehlermeldung, sondern ausschließlich im Log des FE2-Kunden-Systems.

Der enthaltene Alarmabschluss wird bei der Drittsystemanbindung nicht unterstützt.

Im Topic dürfen nur Kleinbuchstaben, Zahlen sowie die Zeichen - und _ enthalten sein. Für das untere Beispiel wurde das Passwort 12345 zur Verschlüsselung verwendet. Final werden die verschlüsselten Daten im folgenden Format übermittelt. Auf die Verschlüsselungsverfahren wird in den darauf folgenden Punkten näher eingegangen.

{
    "iv": "gyAU1msOltlawCecaIX70Q==",
	"salt": "hmWDwA7W2ezmM58NNM41QBfh4VF3qbxWE7go7gtG2cZp4QPaQ5W2EtPtM45HS5dNjeB0BubvLMMjS/q2iPzkMQ==",
	"encryptedMessage": "16VjtTTqURB4ene5GL9OUZ16oDZ9NBVGrshLRNSkwy5JTsw7FEdY00B51Pt85rJMt9nY18ld2TaYNKbZlu8uYRSTnCfxggujChU0GSEgpnEKK6tK/ubkfQ6EcK0ZJ70e4NN1y0W0Dnu5/3iovUpQ2aQ1nc/nIZXHVFncTu7dY4X+E+eLYiEXBt5iSFavMN8D82seDWFGpsCmZ7ZTbh8HImbUzqSykQGX3U7wfoV78GxYFv89nE+GShvEWu5R9Ivkv+hZ5LSg4JIdnNPxlz6qNJAtbbGQciXeIWkwfqSUCL8GC+YNcFAjG3THxQc4V2UUOsKIzLIurovm4R2AGORKebzsM0/f99StDEfmIYIwox2x+Hpy/QWcnuXfl3Yr5iwCCt9J/j8cmCi1KlnPy8vL+MKpgdxZXuQEeFr1PWn+rzx3iabAUUqnXeVAvMeWf2GpQRq9IrtWMPN7pXGjqLHCbCf6r3gY0/LvhiB0lDwXzSVcf06cWZr4az4twBCUUHj/LYvy9YgeSzoCuqfEoVCLKoocl8ZIf2g74y6d5w3sVZSLnoAWG98z3GHIFAjzhdN0VJjL1giA4u/it1Ku3ND/ullSCvtVXn6y39A92I+k7bSftgUk6klYH5sE99aL5w3UK+gK5l0Swi8CedCDyRnUVTSZ4D8EWhrygC0AI8MUwgQ5XYx+y2SsBcDTib7VlLaEUCR0kqydUcFKvqmj1T5Et3EAzhtkb6GpsQgjzF2tU/9BfL+o97ADQaGVfeyOnx1gzNp4PvSNtYCZUnzTq3ygxMFt2PQt6z+s0KrDZFkNpgUxaQROOqhRrpr0H4BYIU4gMU1w22dd52k2FcNY5j1YGjqxrfhDzEZ6sYWAVT3P2zP2yFlXmQNLL++RhNzc9lmm9Q08dj2OZYfdtSAuCRMhzSb5A0DVKne0er5HxwyTRU1gv5p0KvwBZnRnxKmESNuBnqaDqcqiGzvKoH+qS2w7ICC3xXIjr22ew+UG3tfLjysNpPEcIQ7l8xd6Zv4deHofHRsjIp/urixkpJ8QV7/xtZ7PJStdSqPATS5iBa3cfJovtFoENvgBD4EI3+GSTzYC5+fxEaxlf5M2K0jamUwexUSAz6SxIETLAOHYftp7fKweuBL7t5yh9ruwzq6iQyPu3FLHZHWmHE9nlYB56c5gQmRmFzIZ82EZRSaBJoFlB2fMOm+XbDRB51cpZgD76V4AUBjX6MPXsrM+6Alo7+/U7vEo/+CMPbt22OyAFn846L5gWFMbcY/fhU1TqBQC7rx42uPyJgpJcAPcTRYv+lQ/icHhSXG1+hf1fJq6GAZMHfwmoiZ6wEKy9QRy4Q44khulDSTatWrzbVqu57bgGSA8cx/Y/+JvIlANaqMFnGG8KT558OqUzXN8X0HTcgZeZ2nTWEuZQgUXO3iKs/aWEdimSJQuE/vDtxRb4Cewx8nN5GBc3HbNHf7CGYIr3Z1cTCta",
    "nameOfPartner" : "partner name",
    "apiKey" : "api-key",
    "topic" : "topic_addition", 
    "messageIdentifier" : "unique message id"
}

Der Wert in "encryptedMessage" entspricht dem Datenformat der externen Schnittstelle (siehe oben) in JSON nach erfolgter Verschlüsselung und anschließendem Base64 Encoding.

Topic, Felder und Kunden-Identifikation

Das Feld topic setzt sich wie folgt zusammen:

[FE2-Identifikation][Kunden-Identifikation]

FE2-Identifikation	Dieser Wert wird im Alarmeingang durch FE2 automatisch generiert. Sie erhalten diesen Wert direkt vom Kunden.
Kunden-Identifikation	Dieser Wert muss der Kunden in seinem FE2-Alarmeingang hinterlegen. Diese Kunden-Identifikation wird durch den Drittanbieter definiert und muss dem Kunden übermittelt werden. Verwenden Sie nur Kleinbuchstaben oder Zahlen, ohne Sonderzeichen.
Beschreibung weiterer Felder
messageIdentifier	Ein eindeutiger Wert (UUID), mit welchem Sie später den Zustand der Übermittlung abrufen können.

Beispiel

Wenn die FE2-Identifikation abc und die Kunden-Identifikation efg lautet, so muss das Topic wie folgt gesetzt werden:

...
"topic": "abcefg",
...

Verschlüsselung

Die Nutzdaten in JSON sollen via AES verschlüsselt und als Base64 Payload übermittelt werden. In der Tabelle können die zu verwendenden Parameter für die Verschlüsselung entnommen werden.

ALGORITHM	AES/CBC/PKCS5Padding
KEYLENGTH	256
KEYSPEC	PBKDF2withHmacSHA1
ITERATIONS	5000

Die nachfolgenden Codebeispiele sind erstellt mithilfe von javax.crypto (Java JDK 17) und kann verwendet werden, um die oben definierten Spezifikationen umzusetzen. So können beispielsweise das Kryptografie-Verfahren, sowie das Verfahren zum Generieren der Schlüssel, wie folgt implementiert werden:

// javax cryptography library providing the cipher with the defined specs
Cipher AESCipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
KeySpec spec = new PBEKeySpec("encryptPasswort12345".toCharArray(), salt, 5000, 256);
// defines how the secret key should be generated use the required methods
SecretKeyFactory AESKeyFactory = SecretKeyFactory.getInstance("PBKDF2withHmacSHA1");
SecretKey tmp = AESKeyFactory.generateSecret(spec);
// key used for encryption
SecretKey secret = new SecretKeySpec(tmp.getEncoded(), "AES");

Wie die Parameter iv und salt generiert werden, können dem unteren Java Beispielcode entnommen werden. Dabei wird das salt über einen für Kryptografie geeigneten Zufallsgenerator erstellt. In Java kann das mit SecureRandom wie folgt aussehen.

byte[] salt = new byte[64];
// class from package java.security providing a cryptographical strong random number
SecureRandom secureRandom = new SecureRandom();
secureRandom.nextBytes(salt);

Exemplarisch kann die iv mit einer Länge von 16 Bytes ohne Offset definiert werden.

// iv generation with 16 bytes
byte[] iv = new byte[16];
SecureRandom secureRandomIV = new SecureRandom();
secureRandomIV.nextBytes(iv);
// defining the parameters for the iv with length 16 and no offset
IvParameterSpec ivParameterSpec = new IvParameterSpec(iv, 0, 16);

Schlussendlich können die Daten im Beispielcode mit den unteren Aufrufen die Cipher initialisiert und die Verschlüsselung durchgeführt werden.

AESCipher.init(Cipher.ENCRYPT_MODE, secret,ivParameterSpec);
// method call to encrypt the data
byte[] ciphertext = AESCipher.doFinal(ExampleData.TEXT_TO_ENCRYPT.getBytes(StandardCharsets.UTF_8));

Base64 Encoding

Vor der Übertragung muss die verschlüsselte Nutzlast, iv und salt Base64 encodiert werden. Das Encoding basiert auf den RFC 4648 Standard. Hier beispielhaft das Encoding der Parameter mit der Encoder-Klasse aus java.util, welches auf Line Feeds oder das sichere Alphabet für URL/Dateinamen verzichtet.

//  RFC4648 based Base64 Encoder
// 1. without URL/Filename safe Alphabet
// 2. with padding of the encoded data
// 3. without line feeds (MIME)
Base64.Encoder base64Encoder = Base64.getEncoder();
// Base64 encoded iv
byte[] encodedIv = base64Encoder.encode(iv);
// Base64 encoded salt
byte[] encodedSalt = base64Encoder.encode(salt);
// Base64 encoded ciphertext
byte[] encodedCiphertext = base64Encoder.encode(ciphertext);

Austausch der Werte von Drittanbieter mit Kunde

Nachfolgend finden Sie eine Übersicht über Werte und Daten, welche Sie mit Ihrem Kunden gemeinsam austauschen müssen:

Datensatz	Quelle	Hinweis

Datensatz	Quelle	Hinweis
FE2-Identifikation	Kunde
Kunden-Identifikation	Drittanbieter	Nur Buchstaben, keine Sonderzeichen
Verschlüsselungspasswort	Drittanbieter	Mindestens 16 Zeichen

Technische Unterstützung für die Umsetzung wird nur kostenpflichtig zum jeweils gültigen Stundensatz gewährt. Nur Programmiersprachen, in denen wir über Kenntnisse verfügen, können dabei zum Einsatz kommen.

API - Drittsystemanbindung