Skip to content

SaaS Encryption Webservice API Gateway Überblick Beschreibung der Software-as-a-Service Application-Programming-Interface (API)

Überblick unserer Webservice API und ihrer Funktionen für die Verschlüsselung (Encryption), Entschlüsselung (Decryption) und Umschlüsselung (Rekey).


Übersicht aller Webservices und ihrer Funktionen

Die Webservices sind in die Kategorien Verschlüsselung-, Entschlüsselung- und Wiederverschlüsselungsfunktionen unterteilt.

Dabei wird das HTTP-Protokoll zugrunde gelegt und die Nutzung der Media-Types erforderlich. Alle Webservices arbeiten mit HTTP-POST.

Für den berechtigten Zugriff auf die Webservice-API muss der HTTP-Header Authorization mit einem gültigen ACCESS_TOKEN gesetzt werden. Eine ACCESS_TOKEN wird über den Webservice get-access-token bereit gestellt.

In unserer Webservice-API Referenz finden Sie zu jedem Aufruf ein Beispiel mit CURL.

Verschlüsselungsfunktionen (encryption)

Mit diesen Funktionen können Daten verschlüsselt werden.

Funktion Beschreibung
encrypt Verschlüsselt die Eingangsdaten und gibt diese strukturiert zurück. Die Eingangsdaten werden dabei mit einem automatisch ausgewählten Key aus dem aktuellsten Keystore verschlüsselt.
encrypt-with/<KEYSTORE_ID> Verschlüsselt die Eingangsdaten wie encrypt, jedoch mit vorgegebenen Keystore.
encrypt-with/<KEYSTORE_ID>/<KEY_ID> Verschlüsselt die Eingangsdaten wie encrypt-with/<KEYSTORE_ID>, jedoch mit zusätzlich vorgegebenen Key.
encrypt-raw-with/<KEYSTORE_ID>/<KEY_ID> Verschlüsselt die Eingangsdaten wie encrypt-with/<KEYSTORE_ID>/<KEY_ID>, jedoch werden die verschlüsselten Daten binär zurückgegeben.

Entschlüsselungsfunktion (decryption)

Mit diesen Funktionen können Daten entschlüsselt werden.

Funktion Beschreibung
decrypt Umkehrfunktion von encrypt bzw. allen Funktionen die verschlüsselte Daten struktuiert zurück geben. Zur Entschlüsselung wird die Keystore/Key-Kombination aus den Eingangsdaten verwendet.
decrypt-raw-with/<KEYSTORE_ID>/<KEY_ID> Umkehrfunktion von encrypt-raw-with/<KEYSTORE_ID>/<KEY_ID> bzw. allen Funktionen die verschlüsselte Daten binär zurück geben. Dazu werden die binären Eingangsdaten mit dem vorgegebenen Keystore-/Key-Kombinationen entschlüsselt und zurückgegeben.

Wiederverschlüsselung (recryption/rekeying)

Mit diesen Funktionen werden verschlüsselte Daten erneut verschlüsselt. Dazu werden diese entschlüsselt und mit einer neuen Keystore/Key Kombination erneut verschlüsselt, ohne das die unverschlüsselten Daten transportiert werden. Das wird zum rekeying, also dem verschlüsseln von Daten mit einem anderen Key verwendet.

Funktion Beschreibung
recrypt Kombiniert decrypt und encrypt. Die Verschlüsselung wird mit dem Keystore aus den Eingangsdaten und eimem automatisch ausgewählten Key durchgeführt.
recrypt-with/<KEYSTORE_ID> Verschlüsselt die Daten wie recrypt, jedoch mit vorgegebenen Keystore.
recrypt-with/<KEYSTORE_ID>/<KEY_ID> Verschlüsselt die Daten wie recrypt-with/<KEYSTORE_ID>, jedoch mit zusätzlich vorgegebenen Key.
recrypt-raw-with/<KEYSTORE_ID>/<KEY_ID> Kombiniert die Funktionen von decrypt und encrypt-raw-with/<KEYSTORE_ID>/<KEY_ID>.
decrypt-raw-with/<KEYSTORE_ID>/<KEY_ID>
/and-encrypt
Verschlüsselt die Daten wie recrypt, jedoch sind die Eingangsdaten verschlüsselte Binärdatan.
decrypt-raw-with/<KEYSTORE_ID>/<KEY_ID>
/and-encrypt-with/<KEYSTORE_ID>
Kombiniert die Funktionen von decrypt-raw-with/<KEYSTORE_ID>/<KEY_ID> und encrypt-with/<KEYSTORE_ID>.
decrypt-raw-with/<KEYSTORE_ID>/<KEY_ID>
/and-encrypt-with/<KEYSTORE_ID>/<KEY_ID>
Kombiniert die Funktionen von decrypt-raw-with/<KEYSTORE_ID>/<KEY_ID> und encrypt-with/<KEYSTORE_ID>/<KEY_ID>.
decrypt-raw-with/<KEYSTORE_ID>/<KEY_ID>
/and-encrypt-raw-with/<KEYSTORE_ID>/<KEY_ID>
Kombiniert die Funktionen von decrypt-raw-with/<KEYSTORE_ID>/<KEY_ID> und encrypt-raw-with/<KEYSTORE_ID>/<KEY_ID>.

HTTP-Status-Codes

Hier sind die typischen Status-Codes, die bei der Verwendung der Webservice-API auftreten aufgelistet.

200 Typischerweise antworten alle mit HTTP Ok und signalisiert damit, dass der Aufruf ordnunggemäß gearbeitet hat.
400 Der Aufruf entspricht nicht der Spezifikation. Es sollte geprüft werden, ob URL und Parametrisierung korret sind.
401 ACCESS_TOKEN ist nicht autorisiert oder korrekt, bitte neuen ACCESS_TOKEN mit dem Webservice get-access-token anfordern.
405 Unsere Webservice-API unterstüzt nur HTTP POST. Dies kann auch auftreten wenn die URL nicht korrekt ist.
415 Wir unterstüzen nicht alle Media-Types.
andere Weitere HTTP-Status-Codes sind jederzeit möglich und müssen entsprechend behandelt werden.

Media-Types

HTTP-Header Content-Type für Daten zur Verschlüsselung

Unverschlüsselte Daten können grundsätzlich mit allen Media-Types übertragen werden. Dabei ist immer auf das richtige Character-Encoding zu achten. Insbesondere bei der Verwendung von application/x-www-form-urlencoding ist noch zusätlich auf das URL-Encoding zu achten.

Hinweis: Unsere Systeme arbeiten mit dem Character Encoding UTF-8

Verschlüsselte Daten im strukturierten Format

Die Webservice-API ist dafür ausgelegt, mit strukturierten Formaten für die verschlüsselten Daten zu arbeiten. Das bedeutet, dass zu den verschlüsselten Daten (Base64-Encoded) auch die Attribute KEYSTORE_ID und KEY_ID enthalten sind. Die struktuierten Daten können dann wieder mit den entsprechenden Funktionen entschlüsselt werden. Zur Steuerung des Datenformats müssen die HTTP-Header Content-Type und Accept gesetzt werden.

Liste gültiger Media-Types

  • application/json
  • application/xml
  • application/x-www-form-urlencoded

Beispiel im JSON-Format

{ "keystore_id": "495c1af0-9b41-11e4-afdc-db033c72b9d0", "key_id": "4963bc10-9b41-11e4-afdc-db033c72b9d0", "encrypted_data": "n2SesydBvPwnzjiD5eqIfNHtz+oKEY4UeDJCkli32K0=" }

Tipp: Wir empfehlen die Verwendung von application/json

Verschlüsselte Daten im Binärformat

Einige Webservices arbeiten mit verschlüsselten Daten im Binärformat. Daher wird in diesen Fällen der Media-Type application/octet-stream verwendet. Zu erkennen ist das an dem Begriff raw in der Webservice-URL.