ナレッジベース

REACH API - コンセプトとセキュリティ

最終的にREACH APIの背後にある概念は、3つのユースケースに分かれます。

• REACH APIで管理されるデバイスの登録。ロールアウトフェーズとも呼ばれます。
• REACH APIへのアクセスを削除するため、REACH API管理されるデバイスの登録解除。
• REACH APIデバイスの制御フェーズ。無人登録（リモートデバイスでのユーザーの操作なしでデバイスへの接続）を開始、有人登録（リモートデバイスのユーザーが手動で接続を受け付ける）を開始することを許可します。どちらのセッションモードもフル機能のリモートコントロールセッションにすることも、純粋なビューのみの接続にすることもできます。（特定のプラットフォームでのみサポートされます）

デバイスの登録

ロールアウトは、デバイスと管理ソリューションの間で暗号化キーを交換するために使用されます。これらの暗号化キーは、制御フェーズと登録解除フェーズで使用され、デバイスとのすべての通信が安全であることを保証します。

以下の図は、登録フローを示しています。

統合の事例：VendorExampleApp

必要条件

このガイドに従って実際に統合を実行するには、統合のさまざまなフェーズにていくつかの情報が必要となります。

• ベンダーID
• テナントアカウント
• リモートコントロール権限を持つスクリプトトークン

ベンダーIDは、ISVのTeamViewer担当者によって提供されています。

テナント管理権限を持つベンダーアカウントのスクリプトトークンを使用して、テナントアカウントを作成することができます。

たとえば、Postmanのようなツールを使ってWebAPI呼び出しを発行することができます。

最後に、デバイスキーを作成し、制御を要求し、デバイスキーを削除する権限を持つテナントアカウントのスクリプトトークンが必要です。

💡ヒント: スクリプトトークンの作成方法については、こちらをご覧くださいませ。

統合の例として、提供されるコード例では次のテクノロジとライブラリを使用します。

• C＃および.NETランタイム
• BouncyCastleセキュリティライブラリ

Androidの場合、次の情報がさらに必要です。

• MSAのAPK署名値
• APK署名のID（TeamViewerのWebAPI発行）
• TeamViewerアカウントのアカウントID

AppKeyは、Androidデバイス上のMSAの署名であり、AppKeyIDは、アカウントIDとともにインデックスとして使用されます。両方の値は、WebコンソールにAppKeyを登録するためのWebAPIの応答と共に戻ってきます。 

💡ヒント: 説明の間に使用されるすべての値は、具体的な値に置き換えり必要があります。

ベンダー側の統合実装の概要

次の図は、ベンダー側の部品の概要を簡単に示しています。ここでは、統合が行われる必要があります。

REACH APIのためのデバイスの公開

API呼び出しは、任意のHTTPクライアントクラスで実行できます。

このWebAPIコールの事前条件は、TeamViewerクライアントによって書き込まれたロールアウトファイルから情報を読み取ることです。

このファイルは、Windowsおよび管理者権限を持つmacOsプラットフォームで読み取ることができます。

Android搭載端末では、公開データにアクセスする前に、MSAアプリの登録が必要です。これは、以下のAndroid統合の章で個別に説明されています。

ここの例では、VendorExampleAppで提供されているコードをソースコードで参照しています。まず、JSON本体を作成する必要があります。これは、例えば、次のようなデータクラスの作成のようなデータクラスを使用して行うことができます。

RemotecontrolIDとRequestIDの情報は、ロールアウトファイルに由来することを注意してください。

request bodyの作成

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

 

そのデータクラスを作成して情報で埋めて、URLとメソッドを指定し、HTTP要求ヘッダーに必要な認証情報を入力してから、上記の直列化データクラスを含むJSON本体を追加することで、WepAPI呼び出しを発行できます。

HTTPヘッダーに権限を追加するには、TeamViewer (Classic) Management Consoleを使用してアプリケーションスクリプトトークンを作成する必要があります。

このスクリプトトークンがWebAPI呼び出しを実行するための正しい権限を持っていることを確認する必要があります。

これらのアクセス許可は、スクリプトトークンを所有するアカウントがテナントである場合にのみ、そのスクリプトトークンに対して許可することができます。

応答を解析し、応答値を含む非直列化データ・クラスを戻すコールを発行する次のボックスのコード例を参照してください。このサンプルコードは、ベンダーのアプリケーションから取得したものです。

 

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をライブラリとして選択しました。

Java用のBouncyCastleも利用できます。しかし、すべての言語がPEMファイルを扱うためのライブラリがあるはずです。

暗号化アルゴリズムは、APIリクエストから取得したPEMファイルに直接記述されています。

例：

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

セキュリティ上の理由により、ライブラリを使用して作業を処理することを強くお勧めします。ライブラリには正しいアルゴリズムが自動的に識別されるためです。

アルゴリズム自体にセキュリティ上の問題がある場合は、それを変更することができます。

適切なライブラリが使用されている場合は、ISV側で変更する必要はありませんが、手動による実装はそれほど柔軟性がありません。

Bouncy Castleを使用すると、PEMキーの解読は次の例のようにコード化されます。

より簡単にするため、BouncyCastleライブラリで処理をし、文字列として格納できるので、deviceKeyは解読されたPEM形式の文字列として格納します。

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;

 

この手順を実行すると、WebAPI呼び出しの応答で返されたDeviceKeyIDとRemotecontrolIDとともに、管理ソリューションのコンテキストでDeviceKeyを格納することが重要です。

さらに、最終的にDeviceKeyの登録を解除する必要があるdecommsion tokenを保持する必要もあります。

リモートコントロールセッションの確立

前のフェーズのデータ​​であるDeviceKeyとDeviceKeyIDにより、登録されたデバイスに対してリモートコントロールセッションを確立できます。

リモートコントロールの要求時に、ロールアウトフェーズで権限を要求したものと同じコントロールタイプを使用することが重要です。

この場合も、最初にデータクラスインスタンスがWebAPI呼び出しに必要な情報で埋められます。

要求制御データクラス

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リンク用のテンプレートを提供する独自のデータクラスインスタンスに逆シリアル化できます。

このリンクは、ハッシュメソッド認証メッセージ（HMAC）で完了します。

リモートコントロールの呼び出し

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を作成するsecretはAPIレスポンスで暗号化されて返されるため、最初のステップではsecretを復号化します。

解読のキーは、展開フェーズ中にAPI応答で受信されたDeviceKeyです。

DeviceKeyがPEM形式の文字列として格納されるとき、コードの最初の部分はこの文字列をBouncyCastle（ "AsymmetricCipherKeyPair"型変数）に適した構造に変換します。

 

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、ターゲットおよびテナントナンスを使用して、セキュリティライブラリBouncyCastleを使用して実装される次の例のようにHMACを作成できます。

 

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

 

結果は文字列YOURMASTERSECRETの代わりにTeamViewerリンクテンプレートに入れられます。

完了した文字列を使用すると、TeamViewer エンタープライズクライアントがインストールされているシステムのインターネットブラウザでリンクを開くか、このリンクをTeamViewer.exeの呼び出しのコマンドラインに渡すことでリモートコントロールセッションを確立できます。

デバイスの登録を解除する

登録解除デバイス呼び出しには、登録解除を正常に実行するために次のパラメータが必要です。

• 正しい権限を持つ有効なスクリプトトークン（デバイスキーの削除）
• トークンを廃棄する
• デバイスキーID
• リモコンID
• テナントID

前のフェーズと同様に、この特定の呼び出しのデータクラスインスタンスを作成し、WebAPIへの今後の呼び出しの具体的なデータで埋めなければなりません。

 

データ構造の作成

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形式で追加します。

 

登録の解除

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の共通戻り値も参照）をチェックすることによってのみ認証できます。