Base de Conhecimento

API REACH - Conceitos e segurança

Os conceitos por trás da API REACH, no final, são divididos em três casos de uso:

• Registro de dispositivos que serão gerenciados com a API REACH, também chamada de fase de implementação.
• Cancele o registro de dispositivos para remover o acesso através da API REACH.
• A fase de controle que permite iniciar sessões não assistidas (conexão a um dispositivo sem interação do usuário no dispositivo remoto) e assistidas (o usuário do dispositivo remoto aceita manualmente a conexão) sessões com os dispositivos registrados. Ambos os modos de sessão podem ser sessões de controle remoto com todos os recursos ou restritos a conexões puras somente para visualização (suportado apenas em plataformas específicas).

 

Registro de dispositivos

A implementação é usada para trocar chaves de criptografia entre um dispositivo e a solução de gerenciamento. Essas chaves de criptografia são usadas nas fases de controle e cancelamento de registro e garantem que toda a comunicação com um dispositivo seja segura. 

O diagrama explica o fluxo de registro: 

Integração por exemplo: o VendorExampleApp

Requisitos

Para seguir este guia e realizar a integração, algumas informações são necessárias ao longo das diferentes fases da integração, que são

• ID do fornecedor
• Conta de locatário
• Token de script com permissões de controle remoto

A ID do fornecedor foi fornecida por um representante TeamViewer ao ISV.

A conta do locatário pode então ser criada com um token de script da conta do fornecedor com permissões de gerenciamento do locatário.

Por exemplo, você poderia usar uma ferramenta como o Postman para emitir as chamadas da WebAPI.

Por fim, é necessário um token de script da conta do locatário que tenha permissões para criar chaves de dispositivo, solicitar controle e excluir chaves de dispositivo.

Por favor, consulte https://www.teamviewer.com/en/for-developers/#create-script-section para obter instruções sobre como criar um token de script.

Para o exemplo de integração, os exemplos de código fornecidos usam as seguintes tecnologias e bibliotecas:

• C# e .NET runtime
• Biblioteca de segurança BouncyCastle

Para Android, as seguintes informações são necessárias adicionalmente:

• Valor da assinatura do APK para sua MSA 
• ID para assinatura de APK (emitida pela WebAPI do TeamViewer)
• ID da conta TeamViewer

O AppKey é a assinatura do MSA no dispositivo Android, a AppKeyID é usada junto com a ID da conta como um índice. Ambos os valores são retornados com a resposta da chamada da WebAPI para registrar a chave do aplicativo no console web.

Dica: Esteja ciente de que todos os valores usados durante a explicação devem ser substituídos por seus valores concretos.

Visão geral da implementação da integração do lado do fornecedor

O diagrama a seguir oferece uma breve visão geral das partes do lado do fornecedor onde a integração deve ser feita. 

Implementação de um dispositivo para REACH API

A chamada de API pode ser feita com qualquer classe de cliente HTTP.

A pré-condição para esta chamada da API da Web é ler as informações do arquivo de distribuição que é escrito pelo cliente TeamViewer.

Este arquivo pode ser lido em plataformas Windows e macOS com direitos de administrador.

Em dispositivos Android, um registro do aplicativo MSA é necessário antes de tentar acessar os dados de implementação. Isso é descrito separadamente no capítulo Integração do Android abaixo. 

Para nosso exemplo aqui, nos referimos ao código, pois ele também é fornecido no

VendorExampleApp, disponível no código-fonte. Primeiro, você tem que criar o corpo JSON, que pode, por exemplo, acontecer usando uma classe de dados, como a seguinte criação exemplar de tal classe de dados.

Esteja ciente de que as informações para RemotecontrolID e RequestID se originam do arquivo de implementação: 

Criação do corpo da solicitação

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

Com essa classe de dados criada e preenchida com informações, a chamada WepAPI pode ser emitida, especificando o URL e o método, preenchendo o cabeçalho da solicitação HTTP com as informações de autenticação necessárias e, em seguida, anexe o corpo JSON contendo a classe de dados serializada acima.

Para adicionar a autorização ao cabeçalho HTTP, um token de script de aplicativo deve ser criado através do Console de Gerenciamento do TeamViewer.

Deve-se ter certeza de que esse token de script possui as permissões corretas para executar as chamadas da WebAPI.

Essas permissões só podem ser concedidas para esse token de script se a conta que possuir o token de script for um locatário.

Veja um exemplo de código na caixa a seguir, emitindo a chamada, analisando a resposta e retornando a classe de dados de serializada contendo os valores de resposta. Este código de exemplo é obtido do aplicativo do fornecedor. 

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

Com a resposta da API, agora você possui a DeviceKey criptografada.

Para decodificar o DeviceKey criptografado que está no formato PEM, escolhemos aqui BouncyCastle como uma biblioteca porque torna muito mais fácil.

BouncyCastle também está disponível para Java. Mas deve haver muitas bibliotecas para cada linguagem, podendo trabalhar com arquivos PEM. 

O algoritmo de criptografia é declarado diretamente no arquivo PEM que você obtém da solicitação da API.

Exemplo: 

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

Por questões de segurança, RECOMENDAMOS ALTAMENTE que você use uma biblioteca para lidar com o trabalho, porque as bibliotecas geralmente vêm com a capacidade de identificar automaticamente o algoritmo correto. 

No caso de um problema de segurança com o próprio algoritmo, podemos e iremos alterá-lo.

Nenhuma mudança será necessária no lado do ISV se uma biblioteca apropriada for usada, enquanto uma implementação manual nunca seria tão flexível.

Usando o Bouncy Castle, a descriptografia da chave PEM se resume a um código, como no exemplo a seguir.

Por razões de simplicidade, armazenamos o deviceKey como uma string de formato PEM descriptografada, pois isso pode ser manipulado pela biblioteca BouncyCastle e pode ser armazenado como uma string.

Descriptografar chave 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;

Importante: após esta etapa é que você deve armazenar a DeviceKey, junto com a DeviceKeyID e A RemotecontrolID, que foi retornada na resposta da chamada WebAPI, no contexto de sua solução de gerenciamento.

Além disso, você precisa manter o token de desativação que eventualmente será necessário para cancelar o registro de uma DeviceKey novamente. 

Estabelecendo uma sessão de controle remoto

Com os dados da fase anterior, a DeviceKey e a DeviceKeyID, pode ser estabelecida uma sessão de controle remoto com o dispositivo registrado.

É importante que, durante a solicitação de controle remoto você use o mesmo tipo de controle para o qual solicitou permissões durante a fase de implementação.

Novamente, no início, uma instância de classe de dados é primeiro preenchida com as informações necessárias para a chamada da WebAPI.

Classe de dados de controle de solicitação

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

Com essa instância de dados em posição, a chamada da API da Web pode ser emitida como no código C# a seguir.

Novamente, primeiro o URL é adicionado, em seguida, o cabeçalho de autorização HTTP com o token de script e, finalmente, a instância da classe de dados desserializado como um corpo JSON.

Depois que a solicitação retornar com uma resposta, os dados podem ser desserializado em uma instância de classe de dados própria, que fornece o modelo para o link do TeamViewer.

Este link será então preenchido com uma Mensagem de Autenticação de Método com Hash (HMAC).

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

Como a resposta da API retorna apenas um modelo de link, o link deve ser preenchido com a HMAC. 

O segredo para criar a HMAC é retornado criptografado na resposta da API, portanto, a primeira etapa é descriptografar o segredo.

A chave para a des-criptografia é a DeviceKey que foi recebida com a resposta da API durante a fase de implementação.

Como a DeviceKey é armazenada como uma string formatada por PEM, a primeira parte do código converte essa string em uma estrutura adequada para o BouncyCastle (a variável do tipo "AsymmetricCipherKeyPair”). 

Descriptografar PreMasterSecret

using (var reader = new StringReader(DeviceKey)) { //Convert to right format var bytesToDecrypt = encryptedDeviceSecret.FromBase64SafeUrl(); //--------DESCRIPTOGRAFAR COM DISPOSITIVO PEM 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); }

 Com o DeviceSecret descriptografado, A TenantID, A RemotecontrolID do destino e os nonces do destino e do locatário, o HMAC pode ser criado como no exemplo a seguir, que novamente é implementado usando a biblioteca de segurança BouncyCastle. 

Gerar Mastersecret

//---------Valores HMAC a serem hash, recombinados em uma 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();

O resultado é colocado no modelo de link do TeamViewer em vez da string YOURMASTERSECRET.

Com essa string concluída, a sessão de controle remoto pode ser estabelecida abrindo o link no navegador da Internet de um sistema que tenha um cliente TeamViewer Enterprise instalado ou passando este link para a linha de comando de uma chamada para o TeamViewer.exe 

Cancelar o registro do dispositivo

A chamada de dispositivo de cancelamento de registro requer os seguintes parâmetros para executar com êxito o cancelamento de registro:

• Token de script válido com permissão correta (excluir chave do dispositivo)
• Token de desativação 
• ID da chave do dispositivo
• ID de controle remoto
• ID do locatário

Como nas fases anteriores, uma instância de classe de dados para esta chamada específica deve ser criada, preenchida com os dados concretos para a próxima chamada para a WebAPI:

Criação de estrutura de dados

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

Novamente, como já mostrado anteriormente, o mesmo padrão de implementação é seguido, adicionando a URL de chamada WebAPI, adicionando o método, o token de script do aplicativo ao cabeçalho de autorização HTTP e, eventualmente, anexando o conteúdo serializado da classe de dados criada anteriormente no formato JSON.

Cancelando o registro

HttpWebRequest webReq = (HttpWebRequest)WebRequest.Create(apiUrl + "/api/v1/oem/devices/unregister"); 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; }

Neste caso, o resultado retornado não conterá dados.

O sucesso da operação só pode ser verificado verificando o valor de retorno que deve ser 204 (consulte também valores de retorno comuns de HTTP).