TeamViewer API集成

一、概述

TeamViewer (Classic)提供了一个REACH API，用于集成到RMM或MDM解决方案中。通过这个API，客户可以方便地启动无人值守和有人值守的远程控制会话，从而提高工作效率。本教程解释了REACH API的基本概念，并说明和指导如何将API集成到管理解决方案中。

之后，我们用由TeamViewer (Classic)开发集成示例源代码（也称为VendorExampleApp）来解释如何利用API实现集成。

版权所有 (c) 2018 TeamViewer GmbH

TeamViewer特此授予任何获得本软件和相关文档文件（“软件”）副本的人免费许可，无限制地交易本软件，包括但不限于使用，复制，修改，合并的权利，出版，分发，再许可和/或出售本软件的副本，并根据以下条件允许被授权人员从事以下事项：

上述版权声明和本许可声明应包含在本软件的所有副本或实质部分。

本软件按“原样”提供，不提供任何形式的明示或暗示保证和担保，包括但不限于适销性，特定用途的适用性的保证。在任何情况下，作者或版权所有者均不对任何索赔，损害或其他债承担任何责任，无论这些责任是否由使用本软件而产生的，或者与使用本软件相关的，或者与交易本软件而产生的合同缔结，侵权或其他方面的行为。

再次使用或再次发表软件时，请尊重所包含的第三方软件的许可。

二、概念和安全性

REACH API所包含的概念分为三种类型：

• 注册REACH API管理的设备，也称为部署阶段；
• 取消注册设备，通过REACH API删除访问权限；
• 控制阶段允许启动无人职守（连接到远程设备时没有用户交互）和有人值守（连接远程设备时用户手动接受连接）连接到已注册的设备。两种连接模式都可以是全功能远程控制会话，或仅限于纯视图连接（仅支持在特定平台上）

1、设备注册

部署用于在设备和管理解决方案之间交换加密密钥。 这些加密密钥用于控制和注销阶段，并确保与设备的所有通信都是安全的。

该图解释了注册流程：

Management Solution Agent（MSA）是必须在设备上运行的组件。运行此代理必须具有设备的管理权限，并能获取完成部署而所需的数据。开始部署时，MSA会读取一个特殊文件（步骤1），该文件在TeamViewer (Classic)客户端启动时以及每次成功或不成功的部署请求发送到TeamViewer (Classic)客户端之后生成。

注意：每个平台上的步骤1可能不同。文件方法仅适用于Windows和macOS平台。但是，为所有平台提供的部署数据是相同的。

此文件包含RolloutKey（ROK仅对一个请求有效并用于解密API响应），全局唯一标识符（GUID）以及设备的RemotecontrolID（TeamViewer (Classic) ID）。

API可用RemotecontrolID、部署数据的GUID和一系列权限调用（POST / oem / devices / createdevicekey）以创建新的设备密钥（步骤3）。API调用能够启动TeamViewer (Classic)后端至目标客户端的通信。如果数据有效，TeamViewer (Classic)客户端将为以后的远程控制会话创建密钥对。

通过TeamViewer (Classic) 的后端，TeamViewer (Classic)客户端对具有RolloutKey的新创建的密钥对的私钥（= DeviceKey）进行加密。同时将与密钥对的标识符和API调用的解除授权令牌一起作为回复发送给API调用行。（步骤4）管理解决方案必须使用先前获得的RolloutKey来解密DeviceKey。为了简化解码过程，使用标准PEM格式加密DeviceKey。DeviceKey和DeviceKeyID是在控制阶段使用的，而解除授权令牌是在需要注销DeviceKey的时候使用的。

注意：解密的DeviceKey，DeviceKeyID以及解除授权令牌必须安全存储在管理解决方案端。

2、控制阶段

完成第一步后，从现在开始，可以启动到已注册设备的远程控制会话。启动远程控制会话按以下过程：

由于DeviceKey和DeviceKeyID是启动远程控制会话必须的前提，所以只有在设备成功注册以后远程连接才变为可能。

第一步是WebAPI调用（POST / oem / devices / requestcontrol），其参数包括RemotecontrolID，DeviceKeyID和控制类型。这些参数将传递给目标客户端，目标客户端验证DeviceKey是否拥有API调用请求的控制权限。

成功验证请求后，目标TeamViewer (Classic)客户端会生成一次性临时密钥（一个Hash身份验证消息，HMAC），该秘钥与会话密码同等效果。HMAC的确定是用控制请求所接收的数据和TeamViewer (Classic)客户端生成的数据（Target nonce，DeviceSecret）进行计算。在计算HMAC之后，客户端使用通过DeviceKeyID在API调用中指定的DeviceKey加密DeviceSecret。

DeviceSecret作为API的调用响应参数EncryptedDeviceSecret与目标随机数以及TeamViewer (Classic)协议URL（“teamviewerapi：//”）的URL模板一起返回，该URL模板包括占位符YOURMASTERSECRET。ISV执行必须使用DeviceKey解密EncryptedDeviceSecret，并根据解密的设备密钥，目标随机数和API调用请求中发送的其他信息计算HMAC。

计算出HMAC后，就必须用HMAC替换占位符YOURMASTERSECRET以构建有效的TeamViewer (Classic)协议URL。必须将包含HMAC的完整URL提供给源TeamViewer (Classic)客户端以启动连接。这可能会在浏览器或命令行参数中发生（当TeamViewer (Classic)安装并与TeamViewer (Classic)应用程序关联时，TeamViewer (Classic)协议已在操作系统中注册）。

TeamViewer (Classic)客户端现在使用URL中的信息（包括HMAC）建立与目标客户端的连接。

3、注销阶段

如果不再使用DeviceKey，则可以注销DeviceKey。该图显示了基本原理：

注销DeviceKey需要WebAPI调用DELETE / oem / devices / unregister。要执行注销，需要DeviceKeyID识别正确的密钥、设备的RemotecontrolID以及部署阶段在POST / oem / devices / createdevicekey API调用所发出的解除授权令牌。之后，此信息将由设备上的TeamViewer (Classic)客户端处理。

如果API中的信息与客户端上的信息匹配，则部署阶段所创建的密钥对的本地部分将会被删除，并通过WebAPI返回确认信息。从此时起，不能再使用此DeviceKey建立进一步的远程控制会话。

三、集成实例VendorExampleApp

1、要求

按照本说明实际执行集成时，需要在继承的不同阶段中提供一些信息，包括：

• 供应商ID；
• 租户帐户；
• 具有远程控制权限的脚本令牌。

供应商ID已由TeamViewer (Classic)发送给ISV。之后，可以使用具有租户管理权限的供应商帐户的脚本令牌创建租户帐户。可以使用类似Postman的工具来发布WebAPI调用。最后，需要来自租户帐户的脚本令牌，该令牌需要有创建设备密钥，请求控制和删除设备密钥的权限。

本集成实例所提供的代码使用以下技术和语言库：

• C# and .NET runtime
• BouncyCastle security library

Android系统还需要以下信息：

• APK签名值为MSA；
• APK签名的ID（由TeamViewer (Classic)的WebAPI发布；
• TeamViewer (Classic)帐户的ID。

AppKey是Android设备上MSA的签名，AppKeyID与帐户ID可一起用作索引。这两个值都与WebAPI调用一起返回，用于在Web控制台中注册AppKey。

提示：请注意，解释过程中使用的所有值都可替换具体值。

2、供应商端集成实施概述

下图简要介绍了供应商方面的组件，需要进行集成。

3、REACH API设备的部署

API调用可以使用任何HTTP客户端类完成，此WebAPI调用的前提条件是从TeamViewer (Classic)客户端编写的部署文件中读取信息。此文件在Windows和macOs平台上需要管理员权限才可读。

在Android设备上，访问部署数据需要注册MSA应用程序。这将在下面的Android集成一章中单独描述。对于我们这里的示例，我们引用的代码是VendorExampleApp中源代码的一部分。首先，必须创建JSON主体，可以选用数据类进行创建，例如下列示例中的方法创建此类数据类。

请注意，RemotecontrolID和RequestID的信息来自部署文件：

（1）创建请求的正文

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

创建数据类并用信息填写后，指定具体的url和方法，在HTTP请求标头上填写所需的身份验证就可以发出WepAPI调用，然后将包含上面的序列化数据类的JSON主体附上。将授权添加到HTTP标头必须通过TeamViewer (Classic)管理控制台创建应用程序脚本标记。

必须确保此脚本标记具有执行WebAPI调用的正确权限。如果该脚本令牌的帐户是租户，则这些权限只能授予给该脚本令牌。请参阅以下框中的示例代码，该代码发出调用用以解析响应，并返回包含响应值的反序列化数据类。此示例代码来源于供应商应用程序。

（2）请求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);
}

API响应后，您现在就拥有加密的DeviceKey。

为了解码PEM格式的加密DeviceKey，我们在这里选择了BouncyCastle作为库，这是很多操作更容易。

BouncyCastle也可用于Java。但是每种语言都有很多库可以使用PEM文件。

加密算法会在您从API请求获得的PEM文件中直接声明。

示例：

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

出于安全考虑，我们强烈建议您使用库来处理工作，因为库通常能够自动识别正确的算法

如果算法本身存在安全问题，我们将会更改它。

如果使用适当的库，则ISV端不需要进行任何更改，而手动实现则不会那么灵活。

PEM密钥使用Bouncy Castle解密需要以下代码，如下例所示。

为简单起见，我们将deviceKey存储为已解密的PEM格式字符串，因为这可以很好地由BouncyCastle库处理并且可以作为字符串存储。

解密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;

3、发起远程控制会话

用上一阶段得到DeviceKey和DeviceKeyID的数据，可以向注册的设备发起远程控制会话。在请求远程控制期间，需要使用与部署阶段期间请求权限相同控件类型。同样需要首先将WebAPI调用所需的信息填充到数据类实例中。

（1）请求控制数据类

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

有了这个数据实例，就可以下面的C＃代码方式发出WebAPI调用。首先添加URL，然后添加带有脚本令牌的HTTP authorization-header，最后添加序列化数据类实例作为JSON主体。一旦请求返回并带有响应，就可以将数据反序列化为自己的数据类实例，该实例为TeamViewer (Classic)链接提供模板。之后，将使用Hash验证消息（HMAC）完成此链接。

（2）远程控制呼叫

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

}

• 由于API响应仅返回链接模板，因此必须使用HMAC完成链接；
• 创建HMAC的方法在API响应中以加密方式返回，因此第一步是解密；
• 用于解密的密钥是DeviceKey，这在部署阶段通过API响应接收；
• 由于DeviceKey存储为PEM格式的字符串，代码的第一部分将此字符串转换为适合BouncyCastle的结构（“AsymmetricCipherKeyPair”类型变量）。

（3）解密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);
}

使用已解密的DeviceSecret，TenantID，目标的RemotecontrolID以及目标和租户nonce，可以按下面示例的方法创建HMAC，这也可以使用安全库BouncyCastle实现的。

（4）生成YOURMASTERSECRET

//---------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();

结果将放入TeamViewer (Classic)链接模板而不是字符串YOURMASTERSECRET。字符串完成后，打开有TeamViewer (Classic)企业客户端的系统的Internet浏览器链接，或者通将此链接传递给TeamViewer (Classic).exe调用的命令行来建立远程控制会话。

4、取消注册设备

取消注册设备调用需要以下参数才能成功执行：

• 具有正确权限的有效脚本令牌（删除设备密钥）
• 解除授权令牌
• 设备密钥ID
• 遥控器ID
• 租户ID

与前一的阶段一样，创建此特定调用的数据类实例，并填充用于调用WebAPI的具体数据：

（1）数据结构创建

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

如前所示用相同的实现模式，将WebAPI调用URL，方式，应用程序脚本标记添加至HTTP授权标头，最后以JSON格式附加先前创建的数据类的序列化内容。

（2）注销

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

在这种情况下，返回的结果将不包含任何数据。操作是否成功只能通过检查返回值是否为204来验证（也可以参见HTTP公共返回值）。

四、Android集成的细节

由于Android平台限制（没有适当的管理权限分离），部署阶段与其他平台不同。需要先验证MSA才能与TeamViewer (Classic) Android应用程序通信，并以不同的方式获取RolloutKey。

MSA签名密钥的SHA-256 Hash值（此处称为AppKey）必须在TeamViewer (Classic)中注册为十六进制字符串，并使用WebAPI调用POST“/ oem / appregistrations”。此注册步骤对于每个AppKey仅需要一次，并且可以使用任何REST客户端（如Postman）完成。

TeamViewer (Classic)应用程序和MSA之间的通信使用本地Android Binder界面，在注册REACH API时得到的AIDL文件中有描述。

在进行任何其他调用之前，验证方法需要首先被验证。验证方法需要用到注册MSA AppKey帐户时的AccountID和注册时返回的KeyID。如果验证成功，则可以任意调用Binder服务的方法，否则会出现SecurityException。

除了应用程序注册以外，Android上的主要区别还在于如何获取RolloutKey。含有转出数据的文件将写入TeamViewer (Classic)软件中的私有应用程序中存储，且只能用于读取TeamViewer (Classic)应用程序的信息。因此，MSA应用程序必须通过Binder界面请求部署数据。成功获取部署数据后，使用Binder接口上的requestPreKeyData，可以按照《REACH API设备的部署》中所述的方式继续操作。