API - Drittsystemanbindung
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
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 |
Ansprechpartner | 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
| 
|
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.
Für den Zugriff auf Swagger UI verwenden Sie folgende Benutzerdaten:
Benutzername:
userPasswort:
user@alamosopenapiDatenformat
Das unverschlüsselte Datenformat der Nutzdaten finden Sie unter:
Datenformat Externe Schnittstelle
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.
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:
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.
Exemplarisch kann die iv mit einer Länge von 16 Bytes ohne Offset definiert werden.
Schlussendlich können die Daten im Beispielcode mit den unteren Aufrufen die Cipher initialisiert und die Verschlüsselung durchgeführt werden.
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.