API Dokumentation

Unsere RESTful API kann mit jeder Programmiersprache verwendet werden, die HTTP beherrscht.

Allgemeines

Mit der KeyTrac API steht Ihnen ein leistungsfähiger, RESTful Webservice zur Verfügung, der es Ihnen ermöglicht das Tippverhalten Ihrer Anwender für Authentifizierungszwecke nutzbar zu machen. Die KeyTrac API beinhaltet verschiedene Möglichkeiten um das Authentifizierungsverhalten Ihrer Anwender nachverfolgen und auszuwerten zu können.

API-Hostname

Unsere API ist unter https://api.keytrac.net verfügbar. Sämtliche Kommunikation mit dem API-Webservice ist nur über diesen Hostnamen möglich. Aus Sicherheitsgründen steht die KeyTrac API nur über HTTPS zur Verfügung. (Mehr erfahren)

HTTP Anfragen absenden

Zur besseren Veranschaulichung der Kommunikation mit der KeyTrac-API, kommt im weiteren Verlauf der Dokumentation der einfach zu nutzende und für viele Betriebssysteme verfügbare Konsolen HTTP-Client curl zum Einsatz. Da die KeyTrac-API nur wenig Konfiguration erfordert, sind nur folgende Optionen nötig:

Optionsschalter Bedeutung des Optionsschalters
-H Fügt einen HTTP-Header ein, der an die KeyTrac API gesendet wird (mehr erfahren)
-d Sendet die angegebenen Daten an die KeyTrac API (mehr erfahren)

Sicherheit und Authentifizierung

1) Übertragungssicherheit

Aus Gründen der Sicherheit ist die KeyTrac API nur über eine SSL-gesicherte HTTPS-Verbindung erreichbar. Unverschlüsselte HTTP-Verbindungen werden nicht unterstützt.

2) API-Zugriff und Art der Authentifizierung

Um mit der KeyTrac API kommunizieren zu können ist es notwendig, den 36 Zeichen langen API-Token als HTTP-Header (mehr erfahren) zu integrieren. Der API-Token muss in jeder Anfrage enthalten sein, die Sie an den Webservice senden.

Sie finden den Token in Ihrer Management Konsole. Bitte beachten Sie, dass bei den Schlüsselnamen im HTTP-Header zwischen Groß- und Kleinschreibung unterschieden wird. Deshalb ist es zwingend notwendig, dass das A von Authorization groß geschrieben wird. Sollten Sie den API-Token nicht oder fehlerhaft in Ihren HTTP-Header integriert haben, erhalten Sie einen 401 Unauthorized Antwort von der API.

HTTP-Header Name Beispiel HTTP-Header Information
Authorization Authorization: a4c0dc53-e763-4ef3-bd19-cc92734e8691 Der API-Token muss bei jeder API Anfrage enthalten sein.

Authentifizierungsbeispiel

$ curl -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/status

API-Konvention

1) Parameterkodierung

Alle Endpoints der API arbeiten nur mit JSON enkodierten Parametern (Mehr erfahren). Um Daten mit der API austauschen zu können, müssen Sie den Content-Type bei jeder Übertragung auf den Content-Type: application/json setzen. Andere oder leere Content-Types werden nicht berücksichtigt und mit einer Fehlermeldung beantwortet. Für eine vollständige Kompatibilität stellen Sie bitte sicher, dass Ihr Webservice ebenfalls in der Lage ist mit JSON-Daten umzugehen. Dazu empfiehlt es sich neben dem Content-Type auch noch den Accept: application/json Header in alle Anfragen zu integrieren.

2) Zeichenkodierung

Allen Daten die Sie mit der API austauschen sind und werden in UTF8 enkodiert. Bitte stellen Sie ebenfalls sicher, dass Ihr Webservice mit UTF8 enkodierten Daten umgehen kann.

3) Zeit- and Datumsformate

Zeitstempel und Datumswerte werden im UTC Format behandelt. Alle Zeitstempel die Sie an die API senden werden in UTC konvertiert.

Erlaubte Zeitstempel-Formate
2015-06-29 07:31:01 UTC
2015-06-29T07:31:01Z -> bevorzugtes Format

Fehlerkonventionen

1) Formatierungsinformation

Das Standard Fehler-Format ist ein einfaches JSON-Objekt, welches einen error Schlüssel und die jeweilige Fehlermeldung enthält.

{"error":"User not found"}

2) Globale API-Fehlermeldungen

HTTP Status Fehlermeldung Bedeutung der Fehlermeldung
400 {"error":"Attributes missing"} Sie haben ungültige oder korrupte JSON-Daten an die API gesendet.
401 {"error":"Authentication token missing"} Sie versuchen ohne einen API-Token auf die API zuzugreifen.
401 {"error":"Client unauthorized"} Sie versuchen mit einem ungültigen API-Token auf die API zuzugreifen.
403 {"error":"Account is not verified"} Sie versuchen auf die API zuzugreifen, haben aber Ihren Zugang noch nicht bestätigt.
404 {"error":"Entity not found"} Sie versuchen auf eine unbekannte Ressource zuzugreifen.
500 {"error":"Unable to parse data"} Die API kann die von Ihnen übergebenen Daten nicht auswerten.

Neue Benutzer erstellen

Faustregel: Für jeden Benutzer in Ihrer Anwendung müssen Sie auch in KeyTrac einen Benutzer erstellen.

1) Sequenz-Diagramm zur Benutzererstellung

Sequenz-Diagramm zur Benutzererstellung

  1. Ein Benutzer registriert sich einen Zugang auf Ihrer Website.
  2. Sie erzeugen nun für diesen Benutzer einen KeyTrac-Benutzer.
  3. Die KeyTrac API antwortet mit einem Bezeichner, der mit den anderen Benutzerdaten gespeichert werden muss.

2) Definition

Ein Benutzer in KeyTrac spiegelt einen tatsächlichen Benutzer in Ihrer Webanwendung wider. Einen solchen KeyTrac-Benutzer können Sie sich als eine Art Speichereinheit vorstellen, mit der die jeweiligen Tippverhalten verbunden sind. Jeder dieser sog. KeyTrac-Benutzer besitzt dabei zwei unterschiedliche Profil-Typen:

  • AnyText - Wird für die Authentifizierung mit beliebigen Texten verwendet
  • Password Hardening - Wird für die Authentifizierung mittels der Passworteingabe genutzt

Damit es nicht zu kompliziert wird, müssen nicht beide Profil-Typen trainiert werden. So ist es problemlos möglich für einen Benutzer entweder nur das AnyText-Profil, nur das Passwort-Hardening-Profil oder eben beide Profil-Typen zu trainieren. Um einen neuen Benutzer in KeyTrac zu erzeugen, müssen Sie den /users Endpoint der API mittels einer POST Anfrage aufrufen. Das veranlasst die API einen neuen Benutzer zu erzeugen und den eindeutigen Bezeichner des Benutzers an Ihre Anwendung zurückzuliefern.

3) Beispiel-Anfrage

$ curl -d '' -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/users

{"id":"8f5a2308-90b5-4afa-8847-ebf2b99f4082"}

Die Benutzer-ID 8f5a2308-90b5-4afa-8847-ebf2b99f4082 wird exemplarisch in der gesamten Dokumentation verwendet und muss nicht einer tatsächlichen Benutzer-ID entsprechen!

Alle Benutzer anzeigen

1) Definition

Um alle Benutzer anzuzeigen, die Ihrem Zugang zugeordnet sind, müssen Sie den /users Endpoint der API mit Hilfe einer GET Anfrage aufrufen. Die KeyTrac API antwortet dann mit einer Liste aller Benutzer. Jeder Benutzer wird dabei mittels dessen eindeutigen Bezeichner, dem Erstelldatum und (wenn verfügbar) dem Zeitstempel der letzten Aktivität dargestellt.

2) Beispiel-Anfrage

$ curl -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/users

[
  {"identifier":"8f5a2308-90b5-4afa-8847-ebf2b99f4082","created_at":"2016-03-24T11:45:24.812Z","last_activity":"2016-03-24 11:53:07.902Z"},
  {"identifier":"b26bdaef-2377-41db-9f73-b3bae1c6fb4a","created_at":"2016-03-24T11:45:09.603Z"}
]

3) Mögliche API-Fehlermeldungen

HTTP Status Fehlermeldung Bedeutung der Fehlermeldung
500 {"error":"Unable to compute user overview"} Die API kann die Liste der Benutzer, die mit Ihrem Zugang verknüpft sind, nicht erstellen.

Benutzer trainieren

Faustregel: Bevor Sie einen Benutzer trainieren können, müssen Sie diesen zunächst anlegen!

1) Sequenz-Diagramm zum Training

Sequenz-Diagramm zum Training

  1. Ihre Website, wo der KeyTrac JavaScript Recorder integriert ist, wird geladen.
  2. Beim Absenden des Formulars wird das aufgezeichnete Tippverhalten an Ihr Backend gesendet.
  3. Kombinieren und senden Sie die Tippproben sowie die KeyTrac Benutzer-ID an die KeyTrac API.
  4. Die KeyTrac API erzeugt aus den Tippproben ein neues Benutzerprofil.

2) Definition

Bevor KeyTrac Benutzer zuverlässig identifizieren kann, muss KeyTrac zunächst die Art und Weise erlernen wie ein Benutzer etwas auf der Tastatur tippt. Dieses Training kann beispielsweise während des normalen Registrierungsprozesses vorgenommen werden. Das Tippverhalten, welches vorher mit Hilfe des KeyTrac JavaScript Recorders (Dokumentation ansehen) aufgezeichnet wurde, wird hier in ein KeyTrac Benutzerprofil überführt, das dem jeweiligen Benutzer in KeyTrac zugeordnet und gespeichert wird. Sie erzeugen ein solches Profil indem Sie den /anytext/enrol oder den /password/enrol API-Endpoint (hängt von der Variante ab, die Sie verwenden möchten) mittels einer POST Anfrage aufrufen und so die JSON Daten an die API übermitteln.

3) Wichtige Informationen

Für jeden der beiden verfügbaren KeyTrac-Varianten (AnyText oder Password Hardening) ist ein unabhängiger Lernprozess notwendig. Trainieren Sie beispielsweise das AnyText-Profil eines Benutzers, wird nicht automatisch auch das Profil für Password Hardening trainiert und umgekehrt. Für das Training des Password Hardening Profils ist es zudem erforderlich, dass alle Tippproben im sog. maskierten Format aufgezeichnet werden. Dies stellt sicher, dass keine sensiblen sPasswortdaten in der Tippprobe enthalten ist. (Für mehr Informationen hier klicken)

4) Trainingsvoraussetzungen

Bei jedem Training (AnyText oder Password Hardening) werden folgende Daten benötigt:

  • Der 36 Zeichen lange Benutzer-Bezeichner
  • Min. eine aktuelle Aufnahme des Tippverhaltens, aufgezeichnet mit dem KeyTrac Recorder JavaScript

Diese beiden Informationen sind notwendig, um die JSON-Datenstruktur aufzubauen, welche die KeyTrac API erwartet. Das folgende Beispiel zeigt eine JSON-Datenstruktur die für das Training eines Benutzerprofiles verwendet wird. Die Daten im samples Array ist das vom KeyTrac Recorder JavaScript aufgezeichnete Tippverhalten.

{
  "user_id":"826efc1d-78e5-4e69-b144-de090de6094b",
  "samples":[
    "firefox/38.0#m=0#2016-01-29 17:50:51|0dRSHIFT|320d84|48uRSHIFT",
    "firefox/38.0#m=0#2016-01-29 17:50:59|0dRSHIFT|310d84|40uRSHIFT",
    "firefox/38.0#m=0#2016-01-29 17:51:29|0dRSHIFT|280d84|42uRSHIFT"
  ]
}

5) Die Trainingsanfrage

Der Einfachheit halber wird das Schema der JSON-Datenstruktur für alle Trainingsanfragen beibehalten. Lediglich der API-Endpoint ändert sich entsprechend der Variante von KeyTrac die Sie trainieren möchten.

5.1) Beispiel-Anfrage - AnyText

Der API-Endpoint der für das Training der AnyText Variante verwendet wird lautet: https://api.keytrac.net/anytext/enrol

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"user_id":"<<BENUTZER-ID VON SCHRITT [Neue Benutzer erstellen]>>","samples":[
    "firefox/38.0#m=0#2016-04-25 09:22:52|336dRSHIFT|80d68|64uRSHIFT|32u68|32d73|80u73|8d69|72dSPACE|16u69|88uSPACE|64d66|72u66|64d69|80d78|18u69|62u78|104d85|72u85|32d84|64d90|8u84|88u90|8d84|48d69|48u84|72u69|8dSPACE|88uSPACE|96dRSHIFT|40d77|64uRSHIFT|24d69|40u77|40u69|120d84|72u84|16d72|88d79|17u72|31d68|72u68|8u79|56d69|88u69|72dSPACE|80uSPACE|48d66|56u66|72d69|80u69|56d83|56d84|40u83|40d69|48u84|64u69|168d72|104u72|32d84|72u84|72dSPACE|72uSPACE|48d73|96d78|64dSPACE|32u73|16u78|40d68|40uSPACE|32u68|72d69|48d82|64u69|8dSPACE|32u82|48uSPACE|88dLSHIFT|96d77|32uLSHIFT|56u77|48d69|72u69|152d83|72u83|96d83|88u83|8d85|72u85|112d78|80d71|8u78|56u71|40dSPACE|56d68|40uSPACE|32u68|88d69|40d82|40u69|40u82|8dSPACE|64dLSHIFT|16uSPACE|80d76|64uLSHIFT|16u76|88d85|16d70|48u85|40u70|72d84|64u84|32d190|48u190",
    "firefox/38.0#m=0#2016-04-25 09:24:58|128dRSHIFT|568d68|64uRSHIFT|32u68|192d73|40u73|88d69|88u69|160dSPACE|88uSPACE|8d66|72u66|40d69|88d78|8u69|96u78|104d85|80d84|8u85|88u84|40d90|80d84|16u90|56d69|32u84|64u69|64dSPACE|80uSPACE|72dRSHIFT|64d77|72uRSHIFT|8d69|48u77|16u69|40d84|80u84|32d72|88d79|32u72|32d68|32u79|40u68|88d69|64dSPACE|8u69|88uSPACE|40d66|96u66|496d69|72u69|88d83|88d84|40u83|48d69|40u84|40d72|16u69|96u72|40d84|80u84|72dSPACE|96uSPACE|104d73|64d78|56u73|24dSPACE|56u78|8d68|56uSPACE|32u68|80d69|48d82|48u69|56u82|16dSPACE|64dLSHIFT|32uSPACE|120d77|8uLSHIFT|80d69|8u77|64u69|88d83|56u83|96d83|64d85|16u83|56u85|104d78|80d71|8u78|56u71|8dSPACE|88d68|16uSPACE|72u68|80d69|48d82|56u69|56u82|8dSPACE|72uSPACE|32dLSHIFT|64d76|72uLSHIFT|0u76|88d85|25d70|55u85|16u70|80d84|56u84|56d190|24u190"]}' \
  https://api.keytrac.net/anytext/enrol

{"OK":true}

5.2) Beispiel-Anfrage - Password Hardening

Der API-Endpoint der für das Training der Password Hardening Variante verwendet wird lautet: https://api.keytrac.net/password/enrol

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"user_id":"<<BENUTZER-ID VON SCHRITT [Neue Benutzer erstellen]>>","samples":[
    "firefox/38.0#m=0#2016-04-25 09:25:37|l=7|0dI0|72uI0|32dI1|72uI1|120dI2|120uI2|112dI3|64uI3|64dI4|112uI4|32dI5|96uI5|40dI6|88uI6",
    "firefox/38.0#m=0#2016-04-25 09:25:40|l=7|0dI0|56uI0|72dI1|64uI1|112dI2|128uI2|128dI3|56uI3|72dI4|72dI5|24uI4|80dI6|32uI5|48uI6"]}' \
  https://api.keytrac.net/password/enrol

{"OK":true}

6) Erneutes Training von Benutzerprofilen

Wenn Sie bei einem bereits bestehenden Benutzerprofil, gleich ob AnyText oder Password Hardening, ein erneutes Training durchführen, wird das bisher gespeicherte Profil überschrieben. Dieses Verhalten kann dafür genutzt werden, um das Tippverhalten eines Benutzer erneut zu trainieren. Dazu müssen Sie lediglich eine neue Trainingsanfrage an den jeweiligen API-Endpoint senden.

7) Mögliche API Fehlermeldungen

HTTP Status Fehlermeldung
400 {"error":"Samples contain mixed device types"}
Die übermittelten Tippproben stammen von unterschiedlichen Geräten (Mobil/Desktop).
400 {"error":"Insufficient number of unique samples submitted"}
Die Anzahl an einzigartigen Tippproben reichen nicht aus. Duplikate einer einzigen Tippprobe sind nicht zulässig.
400 {"error":"Sample #1 is corrupted or format is not valid"}
Die erste der übermittelten Tippproben ist korrupt oder nicht im erwarteten Format.
400 {"error":"Unable to determine text length of sample"}
Das API-System kann die Länge der Tippprobe nicht ermitteln.
400 {"error":"Combined text length of given samples are insufficient. The minimum text length of the combined samples is set to X characters. To change this setting, please log in to your KeyTrac Console - https://console.keytrac.net"}
Die kombinierte Textlänge aller Tippproben liegt unterhalb der konfigurierten Textlänge. Gilt nur für AnyText.
400 {"error":"Sample #1 is invalid and can’t be used with this type of enrollment/authentication"}
Die erste der übermittelten Tippproben kann nicht für diesen Trainings-/Authentifizierungstyp verwendet werden. Für die/das passwortbasierte Authentifizierung/Training sind nur Tippproben im maskierten Format erlaubt.
400 {"error":"Sample #1 does not contain a sample length"}
Die erste der übermittelten Tippproben enthält keine Länge z.B. [l=12]. Möglicherweise hat der Anwender versucht die Tippprobe zu manipulieren. Gilt nur für Password Hardening.
400 {"error":"Sample #1 does not contain any user inputs"}
Die erste der übermittelten Tippproben ist “leer" und beinhaltet keine Eingaben des Anwenders.
400 {"error":"Sample size is ambiguous"}
Eine oder mehrere Tippproben weisen unterschiedliche Längen auf. Bei Password Hardening müssen alle Tippproben dieselbe Länge besitzen. Besteht das Passwort eines Anwenders beispielsweise aus 10 Zeichen, so muss auch die Tippprobe die Länge 10 besitzen.
400 {"error":"Insufficient number of submitted samples. The minimum sample count is set to X samples. To change this setting, please log in to your KeyTrac Console - https://console.keytrac.net"}
Sie haben zu wenige Tippproben übermittelt. Diese Einstellungen können Sie selbst in der Management-Konsole anpassen. Gilt nur für Password Hardening.
400 {"error":"Given samples are out of specification"}
Sie haben Tippproben übermittelt, welche von KeyTrac nicht verarbeitet werden können, da sie z.B. korrupt, zu kurz sind etc.
500 {"error":"Unable to enroll profile for user"}
Die KeyTrac API kann kein Benutzerprofil für den gewünschten Benutzer erstellen.

Benutzer authentifizieren

Faustregel: Bevor Sie Benutzer authentifizieren können, müssen Sie sie erst trainieren!

1) Sequenz-Diagramm der Authentifizierung

Sequenz-Diagramm der Authentifizierung

  1. Ihre Website, wo der KeyTrac JavaScript Recorder integriert ist, wird geladen.
  2. Beim Absenden des Formulars wird das aufgezeichnete Tippverhalten an Ihr Backend gesendet.
  3. Kombinieren und senden Sie die Tippproben sowie die KeyTrac Benutzer-ID an die KeyTrac API.
  4. Die KeyTrac API erzeugt aus den Tippproben ein neues Benutzerprofil.
  5. Verwenden Sie den Wahr/Falsch-Wert für die Entscheidung ob Sie der Authentifizierung vertrauen.

2) Definition

Die Authentifizierung von Benutzern verläuft ähnlich der bereits oben näher beschriebenen Trainingsphase. Auch bei der Authentifizierung muss der für den Benutzer einzigartige Bezeichner mit den Tippproben, welche vom KeyTrac JavaScript Recorder aufgezeichnet wurden, zusammengefasst als JSON-Daten an die KeyTrac-API übertragen werden. Dazu muss je nach KeyTrac-Variante der /anytext/authenticate oder der /password/authenticate Endpoint der API mittels einer POST Anfrage aufgerufen werden.

Jede Authentifizierung eines Benutzers gegenüber dem KeyTrac-Webservice wird entweder mit einem true Wert beantwortet, sollte die übertragene Tippprobe mit dem gespeicherten Benutzerprofil übereinstimmen. Wurde keine Übereinstimmung festgestellt, liefert die KeyTrac-API einen false Wert zurück. Zusätzlich zu diesem sog. boolschen Wert fügt die KeyTrac-API noch einen prozentualen Wert in die JSON-Antwort ein. Dieser Wert stellt die Genauigkeit der Übereinstimmung mit dem gespeicherten Benutzerprofil dar. Je höher der prozentuale Übereinstimmungswert, desto größer die Übereinstimmung. Der minimale Wert kann hier bei 0 und der maximale Wert bei 100 liegen. Alle Werte sind vom Typ Integer.

Wurde ein Benutzer erfolgreich authentifiziert, integriert die KeyTrac-API die neue Tippprobe automatisch in das gespeicherte Benutzerprofil.

3) Wichtige Informationen

Um Password Hardening verwenden zu können, müssen alle Tippproben im sog. maskierten Format aufgezeichnet werden. Dieses Format stellt sicher, dass keine sensiblen Passwortdaten in der Tippprobe enthalten sind. (Für mehr Informationen hier klicken)

4) Authentifizierungsvoraussetzungen

Bei jeder Authentifizierung (AnyText oder Password Hardening) werden folgenden Daten benötigt:

  • Der 36 Zeichen lange Benutzer-Bezeichner
  • Min. eine aktuelle Aufnahme des Tippverhaltens, aufgezeichnet mit dem KeyTrac Recorder JavaScript

Diese beiden Informationen sind notwendig, um die JSON-Datenstruktur aufzubauen, welche die KeyTrac API erwartet um eine Authentifizierung durchzuführen. Das folgende Beispiel zeigt eine JSON-Datenstruktur die zur Authentifizierung eines Benutzers notwendig ist. Die Daten im samples Array ist das vom KeyTrac Recorder JavaScript aufgezeichnete Tippverhalten.

{
  "user_id":"826efc1d-78e5-4e69-b144-de090de6094b",
  "samples":[
    "firefox/38.0#m=0#2016-01-29 18:50:51|0dRSHIFT|320d84|48uRSHIFT"
  ]
}

5) Die Authentifizierungsanfrage

Der Einfachheit halber wird das Schema der JSON-Datenstruktur für alle Authentifizierungsanfragen beibehalten. Lediglich der API-Endpoint ändert sich entsprechend der Variante von KeyTrac die Sie authentifizieren möchten.

5.1) Beispiel-Anfrage - AnyText

Der API-Endpoint der für die Authentifizierung der AnyText Variante verwendet wird lautet: https://api.keytrac.net/anytext/authenticate

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"user_id":"<<BENUTZER-ID VON SCHRITT [Neue Benutzer erstellen]>>","samples":["firefox/38.0#m=0#2016-04-25 09:26:37|400dRSHIFT|88d68|25uRSHIFT|55u68|32d73|64d69|8u73|80u69|8dSPACE|72uSPACE|48d66|72u66|80d69|88u69|96d78|80u78|96d85|80d84|1u85|79u84|16d90|64d84|24u90|8d69|56u84|56u69|32dSPACE|56uSPACE|224dLSHIFT|88d77|48uLSHIFT|48u77|24d69|64u69|104d84|72u84|24d72|120d79|8u72|40d68|48u79|32u68|72d69|80u69|24dSPACE|96uSPACE|24d66|56u66|88d69|80u69|96d83|104d84|16d69|32u83|48u84|32u69|8d72|112u72|40d84|64u84|136dSPACE|96uSPACE|120d73|88d78|72dSPACE|8u73|32u78|32d68|32uSPACE|24u68|72d69|56d82|48u69|32dSPACE|16u82|64uSPACE|176dLSHIFT|80d77|72uLSHIFT|0u77|80d69|64u69|104d83|56u83|80d83|104u83|1d85|63u85|104d78|72d71|8u78|64u71|32dSPACE|64d68|16uSPACE|56u68|80d69|40d82|40u69|48u82|616dSPACE|72uSPACE|16dLSHIFT|88d76|64uLSHIFT|1u76|112d85|47d70|8u85|48u70|80d84|64u84|40d190|32u190"]}' \
  https://api.keytrac.net/anytext/authenticate

{"authenticated":true,"score":95}

5.2) Beispiel-Anfrage - Password Hardening

Der API-Endpoint der für die Authentifizierung der Password Hardening Variante verwendet wird lautet: https://api.keytrac.net/password/authenticate

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"user_id":"<<BENUTZER-ID VON SCHRITT [Neue Benutzer erstellen]>>","samples":["firefox/38.0#m=0#2016-04-25 09:27:05|l=7|872dI0|56uI0|64dI1|72uI1|128dI2|104uI2|117dI3|43uI3|72dI4|104uI4|24dI5|72dI6|40uI5|40uI6"]}' \
  https://api.keytrac.net/password/authenticate

{"authenticated":true,"score":97}

6) Mögliche API Fehlermeldungen

HTTP Status Fehlermeldung
400 {"error":"Samples contain mixed device types"}
Die übermittelten Tippproben stammen von unterschiedlichen Geräten (Mobil/Desktop).
400 {"error":"Sample #1 is corrupted or format is not valid"}
Die erste der übermittelten Tippproben ist korrupt oder nicht im erwarteten Format.
400 {"error":"Unable to determine text length of sample"}
Das API-System kann die Länge der Tippprobe nicht ermitteln.
400 {"error":"Sample #1 is invalid and can’t be used with this type of enrollment/authentication"}
Die erste der übermittelten Tippproben kann nicht für diesen Trainings-/Authentifizierungstyp verwendet werden. Für die/das passwortbasierte Authentifizierung/Training sind nur Tippproben im maskierten Format erlaubt.
400 {"error":"Sample #1 does not contain a sample length"}
Die erste der übermittelten Tippproben enthält keine Länge z.B. l=12. Möglicherweise hat der Anwender versucht die Tippprobe zu manipulieren. Gilt nur für Password Hardening.
400 {"error":"Sample #1 does not contain any user inputs"}
Die erste der übermittelten Tippproben ist “leer" und beinhaltet keine Eingaben des Anwenders.
400 {"error":"Sample size is ambiguous"}
Eine oder mehrere Tippproben weisen unterschiedliche Längen auf. Bei Password Hardening müssen alle Tippproben dieselbe Länge besitzen. Besteht das Passwort eines Anwenders beispielsweise aus 10 Zeichen, so muss auch die Tippprobe die Länge 10 besitzen.
400 {"error":"Authentication rejected, mismatch of sample and profile size"}
Die übermittelte(n) Tippprobe(n) sind nicht kompatibel mit dem gespeicherten Profil des Benutzers. Wurde etwa das Profil eines Benutzers mit einem 6 Zeichen langen Passwort trainiert, aber eine Authentifizierung mit einer z.B. 10 Zeichen langen Tippprobe versucht, erscheint dieser Fehler. Dies kommt z.B. dann vor, wenn der Benutzer sein Passwort geändert hat, jedoch vergessen wurde sein Profil mit dieser Änderung neu zu trainieren. Gilt nur für Password Hardening.
400 {"error":"Insufficient number of submitted samples. The minimum sample count is set to X samples. To change this setting, please log in to your KeyTrac Console - https://console.keytrac.net"}
Sie haben zu wenige Tippproben übermittelt. Diese Einstellungen können Sie selbst in der Management-Konsole anpassen. Gilt nur für Password Hardening.
400 {"error":"Given samples are out of specification"}
Sie haben Tippproben übermittelt, welche von KeyTrac nicht verarbeitet werden können, da sie z.B. korrupt, zu kurz sind etc.
404 {"error":"User is not yet enrolled for this authentication type"}
Eine Authentifizierung des angegebenen Benutzers ist nicht möglich, da für den gewählten Authentifizierungs-Typ (AnyText oder Password Hardening) noch kein Profil trainiert wurde.
500 {"error":"Unable to deserialize profile of user"}
Die KeyTrac-API kann das gespeicherte Profil nicht laden.
500 {"error":"Unable to adapt profile of user"}
Die KeyTrac-API kann die Aktualisierung des Benutzerprofils nicht durchführen.
500 {"error":"Unable to authenticate user"}
Die KeyTrac-API kann aus internen, technischen Gründen keine Authentifizierung durchführen.

Benutzer identifizieren

Faustregel: Bevor Sie Benutzer identifizieren können, müssen diese bereits trainiert sein!

1) Sequenz-Diagramm der Identifikation

Sequenz-Diagramm der Identifikation

  1. Ihre Website, wo der KeyTrac JavaScript Recorder integriert ist, wird geladen.
  2. Beim Absenden des Formulars wird das aufgezeichnete Tippverhalten an Ihr Backend gesendet.
  3. Senden Sie diese Tippprobe(n) kombiniert mit der Zahl der gewünschten Ergebnisse an die KeyTrac API.
  4. Die KeyTrac API vergleicht die gesendet(en) Tippprobe(n) mit Ihren Benutzern.
  5. Verwenden Sie den prozentualen Übereinstimmungen um die Identität festzulegen.

2) Definition

Die Identifikation von Benutzern verläuft ähnlich der oben bereits näher beschriebenen Authentifizierung. Anders als bei der Trainingsphase oder der Authentifizierung muss hier jedoch lediglich eine Tippprobe eines Benutzers sowie optional die gewünschte Länge der Ergebnisliste als JSON-Daten an die KeyTrac-API übergeben werden. Die Identifikation ist nur für die AnyText-Variante verfügbar, deshalb muss der /anytext/identify Endpoint der API mittels einer POST Anfrage aufgerufen werden.

Nachdem die Tippprobe eines Benutzers an die KeyTrac-API übertragen wurden, vergleicht die API das übermittelte Tippverhalten gegen das Ihrer anderen Benutzer und zeichnet neben der eindeutigen Benutzer-ID auch den prozentualen Übereinstimmungswert auf und gibt diese Ergebnisliste entsprechend der von Ihnen gewünschten Länge an Ihr Backend zurück. Die höchste Übereinstimmung zuerst, die niedrigste zuletzt. Dabei gilt, je höher der Match-Score, desto größer die Übereinstimmung. Der minimale Wert kann hier bei 0 und der maximale Wert bei 100 liegen.

Sie haben selbst die Freiheit zu entscheiden, ab welchem Übereinstimmungsgrad Sie einen Benutzer als einen bestimmten Benutzer identifizieren möchten.

3) Wichtige Informationen

Die Benutzer-Identifikation ist nur für die AnyText-Variante verfügbar. Es ist deshalb notwendig, dass Tippproben, welche Sie an die KeyTrac-API übergeben, im sog. unmaskierten Format aufgezeichnet wurden. (Für mehr Informationen hier klicken)

4) Identifikationsvoraussetzungen

Zu jeder Identifikation werden folgenden Daten benötigt:

  • Min. eine aktuelle Aufnahme des Tippverhaltens, aufgezeichnet mit dem KeyTrac Recorder JavaScript
  • Eine Beschränkung der Ergebnisliste (optional)

Diese Informationen sind notwendig, um die JSON-Datenstruktur aufzubauen, welche die KeyTrac API erwartet um eine Identifikation durchzuführen. Das folgende Beispiel zeigt eine JSON-Datenstruktur die zur Identifikation eines Benutzers notwendig ist. Die Daten im samples Array ist das vom KeyTrac Recorder JavaScript aufgezeichnete Tippverhalten.

{
  "limit":3,
  "samples":[
    "firefox/38.0#m=0#2016-01-29 18:50:51|0dRSHIFT|320d84|48uRSHIFT"
  ]
}

5) Die Identifikationsanfrage

Der API-Endpoint welcher für eine AnyText Identifikation verwendet wird lautet: https://api.keytrac.net/anytext/identify

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"limit":3,"samples":["firefox/38.0#m=0#2016-04-25 09:26:37|400dRSHIFT|88d68|25uRSHIFT|55u68|32d73|64d69|8u73|80u69|8dSPACE|72uSPACE|48d66|72u66|80d69|88u69|96d78|80u78|96d85|80d84|1u85|79u84|16d90|64d84|24u90|8d69|56u84|56u69|32dSPACE|56uSPACE|224dLSHIFT|88d77|48uLSHIFT|48u77|24d69|64u69|104d84|72u84|24d72|120d79|8u72|40d68|48u79|32u68|72d69|80u69|24dSPACE|96uSPACE|24d66|56u66|88d69|80u69|96d83|104d84|16d69|32u83|48u84|32u69|8d72|112u72|40d84|64u84|136dSPACE|96uSPACE|120d73|88d78|72dSPACE|8u73|32u78|32d68|32uSPACE|24u68|72d69|56d82|48u69|32dSPACE|16u82|64uSPACE|176dLSHIFT|80d77|72uLSHIFT|0u77|80d69|64u69|104d83|56u83|80d83|104u83|1d85|63u85|104d78|72d71|8u78|64u71|32dSPACE|64d68|16uSPACE|56u68|80d69|40d82|40u69|48u82|616dSPACE|72uSPACE|16dLSHIFT|88d76|64uLSHIFT|1u76|112d85|47d70|8u85|48u70|80d84|64u84|40d190|32u190"]}' \
  https://api.keytrac.net/anytext/identify

[
  {"user_id":"50f675c1-ca50-4be0-9745-7ed7beae215a","score":99},
  {"user_id":"27834245-c960-49be-b801-adf97cff3b2c","score":27},
  {"user_id":"c75c2689-7a85-41fe-988c-c84196ec4a5a","score":3}
]

6) Mögliche API Fehlermeldungen

HTTP Status Fehlermeldung
400 {"error":"Samples contain mixed device types"}
Die übermittelten Tippproben stammen von unterschiedlichen Geräten (Mobil/Desktop).
400 {"error":"Sample #1 is corrupted or format is not valid"}
Die erste der übermittelten Tippproben ist korrupt oder nicht im erwarteten Format.
400 {"error":"Sample #1 is invalid and can’t be used with this type of enrollment/authentication"}
Die erste der übermittelten Tippproben kann nicht für diesen Trainings-/Authentifizierungstyp verwendet werden. Es sind nur Tippproben im unmaskierten Format erlaubt.
400 {"error":"Unable to determine text length of sample"}
Das API-System kann die Länge der Tippprobe nicht ermitteln.
400 {"error":"Combined text length of given samples are insufficient. The minimum text length of the combined samples is set to X characters. To change this setting, please log in to your KeyTrac Console - https://console.keytrac.net"}
Die kombinierte Textlänge aller Tippproben liegt unterhalb der konfigurierten Textlänge. Gilt nur für AnyText.
400 {"error":"Given samples are out of specification"}
Sie haben Tippproben übermittelt, welche von KeyTrac nicht verarbeitet werden können, da sie z.B. korrupt, bzw. zu kurz sind etc.
404 {"error":"Unable to execute identification as no user is enrolled"}
Eine Identifikation des angegebenen Benutzers ist nicht möglich, da noch kein Benutzer existiert und/oder noch kein Profil trainiert wurde.
500 {"error":"Unable to identify user"}
Die KeyTrac-API kann aus internen, technischen Gründen keine Identifikation durchführen.

Benutzer entfernen

1) Definition

Um Benutzer zu löschen, die Ihrem Zugang zugeordnet sind, müssen Sie den /users/:user_identifier Endpoint der API mit Hilfe einer DELETE Anfrage aufrufen. Die KeyTrac API versucht dann den Benutzer mit dem eindeutigen Bezeichner zu löschen und antwortet mit einer Erfolgsmeldung.

2) Beispiel Benutzer Lösch-Anfrage

$ curl -X DELETE -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/users/8f5a2308-90b5-4afa-8847-ebf2b99f4082

{"OK":true}

3) Mögliche API-Fehlermeldungen

HTTP Status Fehlermeldung Bedeutung der Fehlermeldung
404 {"error":"User not found"} Die API kann den Benutzer mit dem angegebenen Bezeichner nicht finden.
500 {"error":"Unable to delete user"} Die API kann den Benutzer mit dem angegebenen Bezeichner nicht löschen.

Benutzerdetails anzeigen

1) Definition

Sie können für alle aktiven Benutzer, die Ihrem Zugang zugeordnet sind, Details abrufen. Die von der KeyTrac-API zurückgelieferten Daten beinhalten viele statistische Informationen, die Sie beispielsweise für Auswertungszwecke verwenden können. Zur Abfrage der Informationen müssen Sie den /users/:user_identifier Endpoint der KeyTrac-API mittels einer GET Anfrage abrufen.

2) Beispielsanfrage für die Benutzerdetails-Anfrage

$ curl -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/users/8f5a2308-90b5-4afa-8847-ebf2b99f4082

{
  "overview":{
    "enrolment_count":3,
    "authentication_count":232,
    "last_activity":"2015-06-29 07:31:01 UTC"
  },
  "method":{
    "anytext":{
      "last_activity":"2015-06-29 07:31:01 UTC",
    }, ...
  }
}

3) Mögliche API Fehlermeldungen

HTTP Status Fehlermeldung Bedeutung der Fehlermeldung
404 {"error":"User not found"} Der angegebene Benutzer wurde nicht gefunden.
500 {"error":"Unable to calculate status"} Die KeyTrac-API kann den aktuellen Status des Benutzers nicht ermitteln.

Status des Zugangs anzeigen

1) Definition

Ähnlich des Status für Ihre aktiven Benutzer können Sie auch Informationen zum aktuellen Status Ihres Zugangs abfragen. Zur Abfrage der Informationen müssen Sie den /status Endpoint der KeyTrac-API mittels einer GET Anfrage abrufen.

2) Beispielsanfrage für den Zugangsstatus

$ curl -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/status

{
  "overview":{
    "users_created":1245,
    "enrolments":232,
    "authentications":51
  }
}

3) Unterstützte Suchparameter

Neben der Anzeige des gesamten Status Ihres Zugangs können Sie den Zeitraum auf eine bestimmte Zeitperiode eingrenzen.

Das Format der Anfrageparameter muss im Format JJJJ-MM-DD vorliegen. Andere Formate werden nicht berücksichtigt.

Form encoded Parameter Wert
from 2015-06-01
to 2015-12-01

2) Beispielsanfrage für den Zugangsstatus mit Parametern

$ curl -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/status?from=2015-06-01&to=2015-12-01

{
  "overview":{
    "users_created":1245,
    "enrolments":232,
    "authentications":51
  }
}

3) Mögliche API Fehlermeldungen

HTTP Status Fehlermeldung Bedeutung der Fehlermeldung
400 {"error":"Only parameter [from] given. Require both parameters [from] and [to]"} Es muss sowohl ein gültiger [to] als auch ein gültiger [from] Parameter übergeben werden.
400 {"error":"Only parameter [to] given. Require both parameters [from] and [to]"} Es muss sowohl ein gültiger [to] als auch ein gültiger [from] Parameter übergeben werden.
400 {"error":"Format of parameter [from] is invalid: Only accept a format of [YYYY-MM-DD]"} Sie haben ein ungültiges [from] Datum übergeben. Die API erwartet das Format JJJJ-MM-DD.
400 {"error":"Format of parameter [to] is invalid: Only accept a format of [YYYY-MM-DD]"} Sie haben ein ungültiges [to] Datum übergeben. Die API erwartet das Format JJJJ-MM-DD.
400 {"error":"Date window is invalid: Parameter [to] must be greater than or equal to [from]"} Der [to] Parameter ist kleiner als der [from] Parameter. Das Zeitfenster ist damit ungültig.
500 {"error":"Unable to calculate status"} Die KeyTrac-API kann den Status für Ihren Zugang nicht ermitteln.