Base de Conocimiento

API REACH - Conceptos y seguridad

El concepto base de la API REACH se divide en tres casos de uso:

• Registro de dispositivos que se administrarán con la API REACH, o la llamada fase de despliegue.
• Eliminación del registro de dispositivos para eliminar el acceso a través de la API REACH.
• Fase de control que permite iniciar sesiones no presenciales (conexión a un dispositivo sin interacción de usuario en el lado remoto) y presenciales (el usuario del dispositivo remoto acepta manualmente la conexión) con dispositivos registrados. 
• Ambos modos de sesión pueden ser sesiones de control remoto con funcionalidad completa, o bien conexiones como mero espectador (solo compatibles con plataformas específicas).
•  

Registro de dispositivos

El despliegue se utiliza para intercambiar claves de cifrado entre un dispositivo y la solución de gestión. Estas claves de cifrado se utilizan para las fases de control y eliminación del registro y para garantizar que todas las comunicaciones con el dispositivo sean seguras. 

El siguiente diagrama describe el flujo del registro: 

Ejemplo de integración: la AplicaciónDeEjemplo

Requisitos

Para seguir los pasos de esta guía y realizar la integración real, se necesitan ciertos datos a lo largo de las distintas fases de la integración:

• ID del proveedor
• Cuenta de inquilino
• Token del script con permisos de control remoto

El VIS ha recibido el ID del proveedor a través de un representante de TeamViewer.

A continuación, puede crearse la cuenta del inquilino con un token de script de la cuenta del proveedor con permisos de gestión de inquilino.

Por ejemplo, puede utilizar una herramienta como Postman para realizar las llamadas de la WebAPI.

Finalmente, se necesita un token de script de la cuenta del inquilino que tenga permisos para crear claves de dispositivo, solicitar control y eliminar claves de dispositivos.

Si necesitas instrucciones para crear un token de script, consulta https://www.teamviewer.com/es/for-developers/#create-script-section.

Para el ejemplo de integración, los ejemplos de código proporcionados emplean las siguientes tecnologías y bibliotecas:

• Tiempo de ejecución C# y .NET
• Librería de seguridad BouncyCastle 

Para Android se requiere adicionalmente la siguiente información:

• Valor de firma del APK para su MSA 
• ID de la firma del APK (generado por la WebAPI desde TeamViewer)
• ID de la cuenta de TeamViewer

La clave de aplicación (AppKey) es la firma del MSA del dispositivo Android y el ID de la clave de la aplicación (AppKeyID) se utiliza como índice junto con el ID de la cuenta. Ambos valores se devuelven con la respuesta a la llamada de la WebAPI para el registro de la AppKey en la consola web.

Consejo: Ten en cuenta que debes sustituir todos los valores empleados en la explicación por sus propios valores.

Resumen de la implementación del lado del proveedor

El siguiente diagrama muestra un breve resumen de las partes del lado del proveedor en las que debe realizarse la integración. 

Despliegue de un dispositivo para la API REACH

La llamada de la API puede realizarse con cualquier clase de cliente HTTP.

La precondición para esta llamada de la WebAPI es la lectura de la información del archivo del despliegue escrito por el cliente de TeamViewer.

Este archivo es legible en plataformas Windows y macOS con permisos de administrador.

En dispositivos Android, se requiere el registro de la aplicación del MSA antes de acceder a la información del despliegue. Esto se explica separadamente en el capítulo siguiente, que describe la integración con Android. 

Para nuestro ejemplo, nos referimos al código tal como se muestra en la AplicaciónDeEjemplo, que está disponible en el código fuente. En primer lugar, debes crear el cuerpo de JSON, por ejemplo utilizando una clase de datos, como en el ejemplo siguiente de creación de clase de datos.

Ten en cuenta que la información del RemotecontrolID (ID de control remoto) y el RequestID (ID de solicitud) se origina en el archivo del despliegue: 

Creación del cuerpo de la solicitud

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

Una vez creada esta clase de datos y rellenada con la información, la llamada de la WebAPI puede realizarse especificando la URL y el método, rellenando el encabezado de solicitud HTTP con la información de autenticación requerida y posteriormente adjuntando el cuerpo de JSON que contiene la clase de datos anterior.

Para añadir la autorización del encabezado HTTP es necesario crear un token de script desde la Management Console de TeamViewer (Classic).

Es necesario comprobar que este token tenga los permisos correctos para ejecutar las llamadas de la WebAPI.

Solo pueden otorgarse estos permisos al token de script si la cuenta a la que corresponde el token pertenece a un inquilino.

En el siguiente cuadro te mostramos un ejemplo de código para emitir la llamada que analiza la respuesta y devuelve la clase de datos sin serializar que contiene los valores de respuesta. El ejemplo de código se ha extraído de la aplicación del proveedor. 

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

Con la respuesta de la API, se obtiene la DeviceKey encriptada.

Para descifrar la DeviceKey encriptada en formato PEM, hemos escogido la biblioteca BouncyCastle , dado que facilita bastante el proceso.

BouncyCastle también está disponible para Java. No obstante, existen muchas bibliotecas para cada lenguaje capaces de leer archivos PEM. 

El algoritmo de cifrado se indica directamente en el archivo PEM que se obtiene de la solicitud de la API.

Ejemplo: 

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

Por razones de seguridad, ES MUY RECOMENDABLE utilizar una biblioteca para gestionar el trabajo, ya que normalmente tienen la capacidad de identificar automáticamente el algoritmo correcto. 

En caso de producirse un problema de seguridad con el algoritmo, lo modificaremos.

Si se utiliza una biblioteca adecuada, no se requerirán cambios en el lado del VIS, mientras que una implementación manual es menos flexible.

Utilizando Bouncy Castle, el descifrado de la clave PEM se reduce al código del ejemplo siguiente.

Para simplificar el proceso, guardamos la deviceKey en forma de cadena en formato PEM, ya que la biblioteca BouncyCastle funciona bien con él y es almacenable como cadena.

Descifrado de clave 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;

Después de este paso, es importante que guardes la DeviceKey junto con el DeviceKeyID y el RemotecontrolID devueltos en la respuesta de la llamada de la WebAPI en el contexto de tu solución de gestión.

Del mismo modo, debes guardar el token de desinstalación, ya que se requerirá más adelante para eliminar el registro de una DeviceKey. 

Establecer una sesión de control remoto

Con los datos de la fase anterior, la DeviceKey y el DeviceKeyID, puede establecerse una sesión de control remoto en el dispositivo registrado.

Es esencial que en la solicitud de control remoto utilice el mismo tipo de control para el que ha solicitado permiso en la fase de despliegue.

Nuevamente, en primer lugar se rellena una instancia de la clase de datos con la información requerida para la llamada de la WebAPI.

Clase de datos de solicitud de control

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

Con esta instancia de datos, la llamada de la WebAPI puede realizarse como en el siguiente código en C#.

De nuevo se añade en primer lugar la URL, después el encabezado de autorización HTTP con el token de script y finalmente la instancia de la clase de datos serializada como cuerpo de JSON.

Una vez que se devuelva la solicitud con una respuesta, los datos pueden deserializarse a una instancia de clase de datos propia que proporcione la plantilla para el enlace de TeamViewer.

Este enlace se completará con un código de autenticación de mensajes en clave-hash (HMAC).

Llamada de control remoto

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

Dado que la respuesta de la API solo devuelve una plantilla de enlace, debe completarse con el HMAC. 

El valor secreto para crear el HMAC se devuelve encriptado en la respuesta de la API, por lo que el primer paso es descifrarlo.

La clave de descifrado es la DeviceKey recibida en la respuesta de la API durante la fase de despliegue.

Como la DeviceKey se almacena en forma de cadena en formato PEM, la primera parte del código convierte esta cadena en una estructura adecuada para BouncyCastle (la variable de tipo «AsymmetricCipherKeyPair»). 

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

 Con el DeviceSecret desencriptado, el ID del inquilino (TenantID), el RemotecontrolID del objetivo y los nonces del objetivo y el inquilino, puede generarse el HMAC como en el ejemplo siguiente, que de nuevo se implementa utilizando la biblioteca de seguridad BouncyCastle. 

Generación del 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();

El resultado se incorpora a la plantilla de enlace de TeamViewer sustituyendo a la cadena YOURMASTERSECRET.

Con la cadena completada, la sesión de control remoto puede establecerse abriendo el enlace en el navegador web de un sistema en el que haya instalado un client de empresa de TeamViewer, o bien introduciendo el enlace en la línea de comandos de una llamada a TeamViewer.exe 

Eliminación del registro del dispositivo

La llamada de eliminación del registro del dispositivo requiere los siguientes parámetros para ejecutar la eliminación del registro con éxito:

• Token de script válido con los permisos correctos (eliminar clave del dispositivo)
• Token de desinstalación 
• ID de la clave del dispositivo
• ID de control remoto
• ID de inquilino

Al igual que en las fases anteriores, hay que crear una instancia de clase de datos para esta llamada específica con los datos concretos para realizar la consiguiente llamada a la WebAPI:

Creación de estructura de datos

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

De nuevo se sigue el mismo patrón de implementación, tal y como se muestra anteriormente: se añade la URL de la llamada de la WebAPI, el método y el token de script de la aplicación al encabezado de autorización HTTP y, finalmente, se adjunta el contenido serializado de la clase de datos previamente creada en formato JSON.

Eliminación del registro

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

En este caso, el resultado devuelto no contendrá datos.

El éxito de la operación solo puede confirmarse comprobando el valor devuelto, que debe ser 204 (véase también Valores devueltos comunes de HTTP).