Knowledge Base

REACH API – Konzepte und Sicherheit

Die Konzepte der REACH API fallen letzten Endes in drei Anwendungsfälle:

• Registrierung von Geräten, die über die REACH API verwaltet werden, auch als Rollout-Phase bezeichnet.
• Aufhebung der Registrierung von Geräten, um den Zugriff über die REACH API zu beenden.
• Die Steuerungsphase gestattet die Initiierung unbeaufsichtigter Sitzungen (Verbindung auf Geräte ohne Eingreifen von Benutzern an den entfernten Geräten) und beaufsichtigter Sitzungen (Benutzer an den entfernten Geräten erlauben die Verbindung manuell) auf registrierte Geräte.
• Beide Sitzungsmodi können Fernsteuerungssitzungen mit vollem Funktionsumfang umfassen oder auf Verbindungen mit reinen Leserechten beschränkt sein (nur auf bestimmten Plattformen unterstützt).

Registrierung von Geräten

Beim Rollout werden die Verschlüsselungscodes zwischen den Geräten und der Verwaltungslösung ausgetauscht. Diese Verschlüsselungscodes werden für die Phasen der Steuerung und der Aufhebung der Registrierung verwendet. Sie gewährleisten, dass die gesamte Kommunikation mit einem Gerät sicher ist.

Integrationsbeispiel – die VendorExampleApp

Voraussetzungen

Um dieser Anleitung zu folgen und die Integration tatsächlich durchzuführen, sind während der verschiedenen Integrationsphasen einige Informationen erforderlich. Diese umfassen

• Hersteller-ID
• Tenant-Konto
• Skript-Token mit Fernsteuerungsberechtigungen

Die Hersteller-ID wurde dem ISV von einem TeamViewer Repräsentanten mitgeteilt.

Das Tenant-Konto kann mithilfe eines Skript-Tokens des Hersteller-Kontos mit Berechtigungen für die Tenant-Verwaltung erstellt werden.

Beispielsweise könnte ein Tool wie Postman verwendet werden, um die WebAPI-Aufrufe auszugeben.

Schließlich wird ein Skript-Token vom Tenant-Konto benötigt, das die Berechtigungen hat, Geräteschlüssel zu erstellen, die Steuerung anzufordern und Geräteschlüssel zu löschen.

Anweisungen für die Erstellung eines Skript-Tokens finden Sie unter https://www.teamviewer.com/de/for-developers/teamviewer-api/#create-script-section.

Die für diese Beispielintegration bereitgestellten Code-Beispiele nutzen die folgenden Technologien und Bibliotheken:

• C# und .NET Runtime
• Bibliothek BouncyCastle mit kryptographischen Programmierschnittstellen

Für Android werden darüber hinaus folgende Informationen benötigt:

• APK-Signaturwert für Ihren MSA
• ID für APK-Signatur (durch WebAPI von TeamViewer ausgegeben)
• Konto-ID des TeamViewer Kontos

Der AppKey ist die Signatur des MSA auf dem Android-Gerät, die AppKeyID wird zusammen mit der Konto-ID als Index verwendet. Beide Werte werden mit der Antwort des WebAPI-Aufrufs für die Registrierung des AppKey in der Webkonsole zurückgesendet.

💡 Tipp: Bitte beachten Sie, dass alle in diesem Beispiel verwendeten Werte im konkreten Anwendungsfall durch Ihre eigenen Werte ersetzt werden müssen.

Übersicht über die Implementierung der herstellerseitigen Integration

Die folgende Grafik gibt eine kurze Übersicht über die Elemente auf Herstellerseite, bei denen die Integration erfolgen muss (auf Englisch):

Rollout eines Geräts für REACH API

Der API-Aufruf kann mit jeder beliebigen Klasse an HTTP-Clients erfolgen.

Die Voraussetzung für diesen WebAPI-Aufruf ist das Lesen der Rollout-Datei, die vom TeamViewer Client geschrieben wird.

Diese Datei ist auf den Betriebssystemen Windows und macOS mit Administratorrechten lesbar.

Auf Android-Geräten ist eine Registrierung der MSA App erforderlich, bevor der Zugriff auf die Rollout-Daten versucht wird. Dies wird im Kapitel Android-Integration weiter unten eigens beschrieben.

In unserem Beispiel beziehen wir uns auf den Code, da dieser auch in der VendorExampleApp bereitgestellt wird, die im Quellcode verfügbar ist. Zunächst müssen Sie einen JSON-Anforderungsbody erstellen. Dies kann zum Beispiel durch Verwendung einer Datenklasse erfolgen, wie die folgende beispielhafte Erstellung einer solchen Datenklasse.

Beachten Sie, dass die Informationen für RemotecontrolID und RequestID aus der Rollout-Datei stammen:

Erstellung eines Anforderungsbodys

var createDeviceKeyRequest = new CreateDeviceKeyRequest
{
    key_permissions = "unattended",
    remotecontrol_id = "r124124124",
    request_id = "{8c4fa1a7-9d1c-41e9-be17-70e95c289080}",
    tenant_id = "t0001"
};

Nach Erstellung dieser Datenklasse und gefüllt mit Informationen kann der WebAPI-Aufruf ausgegeben werden. Hierzu werden die URL und die Methode angegeben, der HTTP-Anforderungsheader mit den benötigten Authentifizierungsinformationen befüllt und anschließend der JSON-Anforderungsbody mit der serialisierten Datenklasse von oben angefügt.

Um eine Autorisierung zum HTTP-Header hinzuzufügen, muss in derTeamViewer (Classic) Management Console ein Skript-Token der Anwendung erstellt werden.

Dieses Skript-Token muss die korrekten Berechtigungen haben, um die WebAPI-Aufrufe auszuführen.

Diese Berechtigungen können nur für das Skript-Token vergeben werden, wenn das zum Skript-Token zugehörige Konto ein Tenant ist.

Das folgende Feld zeigt einen Beispielcode, der einen Aufruf zur Antwortanalyse ausgibt und die deserialisierte Datenklasse mit den Antwortwerten zurücksendet. Dieser Beispielcode entstammt der Anbieter App.

Fordern Sie den DeviceSecretKey an

HttpWebRequest webReq = (HttpWebRequest)WebRequest.Create(apiUrl + "/api/v1/oem/devices/createdevicekey");

webReq.Method = "POST";
webReq.ContentType = "application/json";
webReq.Headers.Add("Authorization", "Bearer "+accessToken);

using (var streamWriter = new StreamWriter(webReq.GetRequestStream()))
{
    var createSecretKeyRequestJson = JsonConvert.SerializeObject(createDeivceKeyRequest);

    streamWriter.Write(createDeviceKeyRequestJson);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse = (HttpWebResponse) await webReq.GetResponseAsync();
if (httpResponse == null)
{
    throw new InvalidDataException("No response received");
}

var responseStream = httpResponse.GetResponseStream();
if (responseStream == null)
{
    throw new InvalidDataException("No response stream received.");
}

using (var streamReader = new StreamReader(responseStream))
{
    var result = streamReader.ReadToEnd();
    return JsonConvert.DeserializeObject<CreateDeviceKeyResponse>(result);
}

Mit der API-Antwort sind Sie nun im Besitz des verschlüsselten DeviceKeys.

Zur Entschlüsselung des im PEM-Format verschlüsselten DeviceKeys wählen wir BouncyCastle als Bibliothek, da dadurch vieles einfacher wird.

BouncyCastle ist auch für Java verfügbar. Doch es gibt zahlreiche weitere Bibliotheken für jede Programmiersprache, die mit PEM-Dateien arbeiten können.

Der Verschlüsselungsalgorithmus wird direkt in der PEM-Datei angegeben, die Sie von der API-Anfrage erhalten.

Beispiel:

"-----BEGIN RSA PRIVATE KEY-----\nProc-Type: 4,ENCRYPTED\nDEK-Info: AES-256-CBC,309AA16\n-----END RSA PRIVATE KEY-----\n"

Aufgrund von Sicherheitsbedenken EMPFEHLEN WIR DRINGEND, dass Sie eine Bibliothek für diese Arbeit verwenden, da solche Bibliotheken den korrekten Algorithmus in der Regel automatisch erkennen.

Im Falle eines Sicherheitsproblems mit dem Algorithmus selbst, können und werden wir ihn ändern.

ISV-seitig sind keine Änderungen erforderlich, wenn eine geeignete Bibliothek verwendet wird. Eine manuelle Implementierung wäre niemals so flexibel.

Durch Verwendung von BouncyCastle besteht der PEM-Schlüssel nunmehr lediglich aus einem Code wie im folgenden Beispiel.

Zur Vereinfachung speichern wir den DeviceKey als entschlüsselten String im PEM-Format, da die Bibliothek BouncyCastle damit gut zurecht kommt und die Speicherung als String möglich ist.

Entschlüsseln Sie den PEM-Schlüssel

TextReader textReader = new StringReader(encryptedDeviceKey);
PemReader pemReader = new PemReader(textReader, new PasswordFinder(password));
object deviceKeyObject = pemReader.ReadObject();

AsymmetricCipherKeyPair rsaPrivatekey = (AsymmetricCipherKeyPair)deviceKeyObject;

TextWriter tw = new StringWriter();
var pemWriter = new PemWriter(tw);
pemWriter.WriteObject(rsaPrivatekey.Private);
pemWriter.Writer.Flush();
string deviceKey = tw.ToString();
return deviceKey;

Es ist wichtig, dass Sie nach diesem Schritt den DeviceKey zusammen mit der DeviceKeyID und der RemotecontrolID im Kontext Ihrer Verwaltungslösung speichern, die in der Antwort auf den WebAPI-Aufruf zurückgesendet wurden.

Darüber hinaus müssen Sie das Stilllegungstoken aufbewahren, das schließlich erforderlich ist, um die Registrierung des DeviceKeys wieder aufzuheben.

Aufbau einer Fernsteuerungssitzung

Mit den Daten aus der bisherigen Phase, dem DeviceKey und der DeviceKeyID kann eine Verbindung auf das registrierte Gerät aufgebaut werden.

Es ist wichtig, dass Sie bei der Anforderung der Fernsteuerung denselben Steuerungstyp verwenden, für den Sie beim Rollout Berechtigungen angefordert haben.

Auch hier wird zunächst eine Datenklasseninstanz mit den benötigten Informationen für den WebAPI-Aufruf befüllt.

Fordern Sie die Steuerungsdatenklasse an

var requestControlRequest = new RequestControlRequest()
{
    control_type = "attended",
    device_key_id = "{114fa1a7-abab-41e9-be17-70e95c289080}",
    remotecontrol_id = "r124124124",
    tenant_id = "t0001",
    tenant_nonce = "243dd78d07324ab7befa41390d08d35f"             
};

Mit dieser Dateninstanz kann der WebAPI-Aufruf wie im folgenden C#-Code ausgegeben werden.

Wieder wird zunächst die URL hinzugefügt, dann der HTTP-Autorisierungsheader mit dem Skript-Token und schließlich die serialisierte Datenklasseninstanz als JSON-Body.

Sobald die Anfrage mit einer Antwort zurückgegeben wurde, können die Daten in eine eigene Datenklasseninstanz deserialisiert werden, die die Vorlage für den TeamViewer Link bildet.

Dieser Link wird anschließend durch einen HMAC (Hashed Method Authentication Message) vervollständigt.

Fernsteuerungsaufruf

HttpWebRequest webReq = (HttpWebRequest)WebRequest.Create(apiUrl + "/api/v1/oem/devices/requestcontrol");

webReq.Method = "POST";
webReq.ContentType = "application/json";
webReq.Headers.Add("Authorization", "Bearer " + accessToken);


using (var streamWriter = new StreamWriter(webReq.GetRequestStream()))
{
    var requestControlRequestJson = JsonConvert.SerializeObject(requestControlRequest);

    streamWriter.Write(requestControlRequestJson);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse =  (HttpWebResponse)(await webReq.GetResponseAsync());

if (httpResponse == null)
{
    throw new InvalidDataException("No response received");
}

var responseStream = httpResponse.GetResponseStream();

if (responseStream == null)
{
    throw new InvalidDataException("No response stream received.");
}

using (var streamReader = new StreamReader(responseStream))
{
    var result = streamReader.ReadToEnd();

    return JsonConvert.DeserializeObject<RequestControlResponse>(result);

}

Nachdem die API-Antwort nur eine Linkvorlage zurückgibt, muss der Link mit dem HMAC vervollständigt werden.

Das Secret zur Erstellung des HMAC wird verschlüsselt in der API-Antwort zurückgegeben. Daher besteht der erste Schritt darin, das Secret zu entschlüsseln.

Zur Entschlüsselung wird der DeviceKey verwendet, der beim Rollout mit der API-Antwort empfangen wurde.

Da der DeviceKey als String im PEM-Format gespeichert wurde, verwandelt der erste Teil des Codes den String in eine Struktur, die für BouncyCastle geeignet ist (die Variable vom Typ „AsymmetricCipherKeyPair“).

Entschlüsseln Sie das PreMasterSecret

using (var reader = new StringReader(DeviceKey))
{
    //Convert to right format
    var bytesToDecrypt = encryptedDeviceSecret.FromBase64SafeUrl();

    //--------DECRYPT WITH PEM DEVICE KEY-------------//
    AsymmetricCipherKeyPair keyPair = (AsymmetricCipherKeyPair) new PemReader(reader).ReadObject();
    var decryptEngine = new OaepEncoding(new RsaEngine());
    decryptEngine.Init(false, keyPair.Private);
    var decryptedDeviceSecret = decryptEngine.ProcessBlock(bytesToDecrypt, 0, bytesToDecrypt.Length);
}

Mit dem entschlüsselten DeviceSecret, der TenantID, der RemotecontrolID auf den Ziel- und Tenant-Nonces kann der HMAC wie im folgenden Beispiel erstellt werden. Auch dieses wurde mithilfe der Sicherheitsbibliothek BouncyCastle implementiert.

Generieren Sie das Mastersecret

//---------HMAC Values to be hashed, recombined in a string ------------//
var hashVerifier = $"{tenantNonce}{targetNonce}{tenantId.Substring(1)}{remotecontrolId.Substring(1)}";


HMACSHA512 hmacsha512 = new HMACSHA512(decryptedDeviceSecret);
byte[] hashmessage = hmacsha512.ComputeHash(Encoding.UTF8.GetBytes(hashVerifier));
var masterSecret =  hashmessage.ToBase64SafeUrl();

Das Ergebnis wird anstelle des Strings YOURMASTERSECRET in die Vorlage des TeamViewer Links eingefügt.

Mit dem vollständigen String kann die Fernsteuerungssitzung nun aufgebaut werden, entweder durch Öffnen des Links im Webbrowser eines Systems, auf dem der TeamViewer Enterprise-Client installiert ist, oder durch Weitergabe dieses Links an die Befehlszeile eines Aufrufs an TeamViewer.exe

Registrierung des Geräts aufheben

Der Geräteaufruf zur Aufhebung der Registrierung benötigt folgende Parameter, um die Aufhebung der Registrierung erfolgreich durchzuführen:

• Gültiges Skript-Token mit der korrekten Berechtigung (Geräteschlüssel löschen)
• Stilllegungstoken
• Device Key ID
• Remote control ID
• Tenant ID

Wie in den vorangegangenen Phasen muss eine Datenklasseninstanz für diesen konkreten Aufruf erstellt werden. Diese muss mit den konkreten Daten für den eingehenden Aufruf zur WebAPI befüllt werden:

Datenstruktur erstellen

var unregisterDeviceRequest = new UnregisterDeviceRequest
{
    tenant_id = "t0001",
    remotecontrol_id = "r124124124",
    device_key_id = "{114fa1a7-abab-41e9-be17-70e95c289080}",
    decommission_token = _mState.LastDecommissionToken
};

Auch hier wird das zuvor dargestellte Implementierungsmuster verwendet. Dabei werden die URL des WebAPI-Aufrufs, die Methode und das Skript-Token für die Anwendung zum HTTP-Autorisierungsheader hinzugefügt. Schließlich wird der serialisierte Inhalt der zuvor erstellten Datenklasse im JSON-Format angefügt.

Registrierung aufheben

HttpWebRequest webReq = (HttpWebRequest)WebRequest.Create(apiUrl + "/api/v1/oem/devices");

webReq.Method = "DELETE";
webReq.ContentType = "application/json";
webReq.Headers.Add("Authorization", "Bearer " + accessToken);

using (var streamWriter = new StreamWriter(webReq.GetRequestStream()))
{
    var unregisterDeviceRequestJson = JsonConvert.SerializeObject(unregisterDeviceRequest);

    streamWriter.Write(unregisterDeviceRequestJson);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse = (HttpWebResponse)await webReq.GetResponseAsync();
if (httpResponse == null)
{
    throw new InvalidDataException("No response received");
}

var responseStream = httpResponse.GetResponseStream();
if (responseStream == null)
{
    throw new InvalidDataException("No response stream received.");
}

using (var streamReader = new StreamReader(responseStream))
{
    var result = streamReader.ReadToEnd();
    return;
}

In diesem Fall enthält das zurückgegebene Ergebnis keine Daten.

Der Erfolg dieses Vorgangs kann nur durch die Überprüfung des Rückgabewerts verifiziert werden, der 204 betragen sollte (siehe auch gebräuchliche HTTP-Rückgabewerte).