Base de connaissance

API REACH - Concepts et sécurité

Les concepts derrière l'API REACH sont finalement divisés en trois cas d'utilisation :

• Enregistrement des appareils qui seront gérés avec l'API REACH, également appelé la phase de déploiement.
• Annulation de l'enregistrement des appareils pour supprimer l'accès à distance via l'API REACH.
• Phase de contrôle qui permet d'initier les sessions non surveillées (connexion à un appareil sans interaction de l'utilisateur sur l'appareil distant) et les sessions surveillées (l'utilisateur de l'appareil distant accepte manuellement la connexion) sur des appareils enregistrés. 
• Les deux modes de sessions peuvent être des sessions de contrôle à distance avec toutes les fonctionnalités nécessaires ou restreintes pour être des connexions en affichage seulement (uniquement prises en charge sur des plateformes spécifiques).

Enregistrer des appareils

Le déploiement est utilisé pour échanger des clés de cryptage entre un appareil et la solution de gestion. Ces clés permettent de contrôler et d'annuler l'enregistrement. De plus, elles garantissent que toutes les communications avec un appareil sont sécurisées. 

La figure ci-dessous explique le flux d'enregistrement : 

Intégration par exemple : VendorExampleApp

Exigences

Pour suivre ce guide et effectuer réellement l'intégration, certaines informations sont requises pendant les différentes phases de l'intégration, à savoir :

• ID du fournisseur
• Compte du locataire
• Jeton de script avec autorisations de contrôle à distance

L'ID du fournisseur a été fourni par un représentant TeamViewer à l'éditeur de logiciels indépendant.

Le compte du locataire peut alors être créé à l'aide d'un jeton de script du compte du fournisseur avec les autorisations de gestion du locataire.

Vous pouvez, par exemple, utiliser un outil comme Postman pour émettre les appels WebAPI.

Enfin, un jeton de script à partir du compte du locataire est nécessaire, disposant des autorisations de créer des clés d'appareils, de demander le contrôle et de supprimer les clés d'appareils.

Veuillez cliquer sur le lien Créer un script - Premiers pas pour obtenir des instructions sur la création d'un jeton de script.

Pour l'exemple d'intégration, les exemples de codes fournis utilisent les technologies et bibliothèques suivantes :

• C# et .NET Runtime
• bibliothèque de sécurité BouncyCastle

Pour Android, les informations suivantes sont également nécessaires :

• Valeur de la signature APK pour votre MSA 
• ID pour la signature APK (émise par WebAPI à partir de TeamViewer)
• ID du compte TeamViewer

AppKey est la signature de MSA sur l'appareil Android, AppKeyID est utilisé avec l'ID de compte sous forme d'index. Les deux valeurs sont renvoyées avec la réponse de l'appel WebAPI pour enregistrer AppKey dans la console Web.

💡 Astuce : Gardez à l'esprit que toutes les valeurs utilisées pendant l'explication doivent être remplacées par vos valeurs concrètes.

Aperçu de la mise en œuvre de l'intégration côté fournisseur

La figure suivante offre un aperçu des parties côté fournisseur, dans lesquelles l'intégration doit être effectuée. 

Déploiement d'un appareil pour l'API REACH

L'appel API peut être effectué avec n'importe quelle classe client HTTP.

La précondition de cet appel WebAPI est de lire les informations à partir du fichier de déploiement écrit par le client TeamViewer.

Ce fichier est lisible sur les plateformes Windows et macOs avec des droits d'administration.

Sur les appareils Android, un enregistrement de l'application MSA est requis avant d'essayer d'accéder aux données de déploiement. Cela fait l'objet d'une description distincte dans le chapitre Intégration d'Android ci-dessous. 

Pour notre exemple ici, nous nous référons au code, car il est également fourni dans VendorExampleApp disponible dans le code source. Vous devez d'abord créer le corps JSON, qui peut, par exemple, se produire à l'aide de la classe de données, comme l'exemple de création suivant d'une telle classe de données.

Gardez à l'esprit que les informations sur RemotecontrolID et RequestID proviennent du fichier de déploiement : 

Création du corps de la demande

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

Avec cette classe de données créée et remplie avec les informations, l'appel WepAPI peut être émis en spécifiant l'URL et la méthode, en remplissant l'en-tête de la requête HTTP avec les informations d'authentification requises, puis en ajoutant le corps JSON contenant la classe de données sérialisées mentionnée ci-dessus.

Pour ajouter l'autorisation à l'en-tête HTTP, un jeton de script d'application doit être créé via TeamViewer (Classic) Management Console.

Vous devez vérifier que ce jeton de script dispose des permissions correctes pour exécuter les appels WebAPI.

Ces permissions peuvent uniquement être accordées pour ce jeton de script si le compte qui possède le jeton de script est un locataire.

Consultez un exemple de code dans la zone suivante émettant l'appel, analysant la réponse et renvoyant la classe de données sérialisées contenant les valeurs de réponses. Cet exemple de code provient de l'application du fournisseur. 

Demander DeviceSecretKey

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); }

Avec la réponse de l'API, vous êtes maintenant en possession du DeviceKey crypté.

Pour décoder le DeviceKey crypté qui est au format PEM, nous avons choisi BouncyCastle comme bibliothèque ici, car elle facilement considérablement les choses.

BouncyCastle est également disponible pour Java. Toutefois, il doit exister de nombreuses bibliothèques pour chaque langue en mesure de fonctionner avec des fichiers PEM. 

L'algorithme de cryptage est indiqué directement dans le fichier PEM que vous obtenez de la demande d'API.

Exemple : 

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

À cause des problèmes de sécurité, nous vous RECOMMANDONS FORTEMENT d'utiliser une bibliothèque pour gérer le travail, car les bibliothèques sont généralement fournies avec la capacité d'identifier automatiquement l'algorithme correct. 

En cas de problèmes de sécurité avec l'algorithme lui-même, nous pouvons le changer et nous le ferons.

Aucune modification ne sera requise du côté de l'éditeur de logiciels indépendant si une bibliothèque appropriée est utilisée alors qu'une mise en œuvre manuelle ne serait jamais aussi flexible.

Avec Bouncy Castle, le décryptage de la clé PEM se réduit au code comme dans l'exemple suivant.

Pour des raisons de simplicité, nous stockons deviceKey sous forme de chaîne au format PEM décrypté, car il peut être parfaitement géré par la bibliothèque BouncyCastle et stocké comme une chaîne.

Décrypter la clé PEM

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;

Ce qui est important après cette étape, c'est que vous devez stocker DeviceKey avec DeviceKeyID et RemotecontrolID, renvoyé en réponse à l'appel WebAPI, dans le cadre de votre solution de gestion.

De plus, vous devez également conserver le jeton de retrait qui est finalement requis pour annuler à nouveau l'enregistrement de DeviceKey. 

Établir une session de contrôle à distance

Avec les données de la phase précédente, DeviceKey et DeviceKeyID, une session de contrôle à distance peut être établie sur l'appareil enregistré.

Il est indispensable que pendant la demande de contrôle à distance, vous utilisiez le même type de contrôle pour lequel vous avez demandé les permissions lors de la phase de déploiement.

À nouveau au début, une instance de classe de données est d'abord remplie avec les informations requises pour l'appel WebAPI.

Demander le contrôle de la classe de données

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

Avec cette instance de données en place, l'appel WebAPI peut être émis comme dans le code C# suivant.

Une nouvelle fois, l'URL est d'abord ajoutée, puis l'en-tête d'autorisation HTTP avec le jeton de script et enfin, l'instance de la classe de données sérialisées sous forme de corps JSON.

Une fois que la demande a été renvoyée avec une réponse, les données peuvent être désérialisées en une instance de classe de données, fournissant le modèle du lien TeamViewer.

Ce lien est ensuite complété avec le code d'authentification de message haché (HMAC, Hashed Method Authentication Message).

Appel de contrôle à distance

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);                       }

Comme la réponse de l'API renvoie uniquement un modèle de lien, le lien doit être complété avec HMAC. 

Le secret pour créer HMAC est le renvoi crypté dans la réponse de l'API pour que la première étape consiste à décrypter le secret.

La clé du décryptage est DeviceKey, reçu avec la réponse de l'API lors de la phase de déploiement.

Comme DeviceKey est stocké sous forme de chaîne au format PEM, la première partie du code convertit cette chaîne en une structure adaptée à BouncyCastle (la variable de type AsymmetricCipherKeyPair). 

Décrypter 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); }

 Avec DeviceSecret, TenantID, RemotecontrolID de la cible et les valeurs à usage unique cibles et du locataire, HMAC peut être créé comme dans l'exemple suivant, qui est à nouveau mis en œuvre à l'aide de la bibliothèque de sécurité BouncyCastle. 

Générer 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();

Le résultat est placé dans le modèle du lien TeamViewer au lieu de la chaîne VOTRE_SECRET_PRINCIPAL.

Avec cette chaîne complétée, la session de contrôle à distance peut être établie en ouvrant le lien dans le navigateur Internet d'un système sur lequel un client d'entreprise TeamViewer est installé, ou en passant ce lien à la ligne de commande d'un appel vers TeamViewer.exe 

Annuler l'enregistrement d'un appareil

L'annulation de l'enregistrement d'un appel d'appareil exige les paramètres suivants pour exécuter correctement l'annulation de l'enregistrement :

• Jeton de script valide avec les permissions correctes (supprimer DeviceKey)
• Jeton de retrait 
• ID de clé d'appareil
• ID de contrôle à distance
• ID du locataire

Comme dans les phases précédentes, une instance de classe de données pour cet appel spécifique doit être créée, remplie avec les données concrètes pour le prochain appel vers WebAPI :

Création de la structure de données

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

À nouveau, comme précédemment montré, le même modèle de mise en œuvre est suivi, ajoutant l'URL d'appel WebAPI, ajoutant la méthode, le jeton de script d'application sur l'en-tête d'autorisation HTTP et ajoutant enfin le contenu sérialisé de la classe de données précédemment créée au format JSON.

Annuler l'enregistrement

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; }

Dans ce cas, le résultat renvoyé ne contient aucune donnée.

La réussite de l'opération peut uniquement être vérifiée en contrôlant la valeur de retour, qui doit être 204 (voir aussi Valeurs de retour communes HTTP).