HN 日本語サマリー

← 一覧へ戻る
プログラミング

Tapo (Rust/Pythonライブラリ) が TP-Link の TPAP プロトコルに対応

Tapo (Rust/Python library) now speaks TP-Link's TPAP protocol (mihai.dinculescu.dev)

107 pointsby faithraven47 コメント

要約

TP-LinkのTapoデバイス用非公式ライブラリ「tapo」(Rust/Python)が、最新ファームウェアで導入されたTPAPプロトコルに対応しました。これにより、Tapoアプリ内の「サードパーティ互換性」設定がオフの状態でも、デバイスと通信できるようになります。このアップデートは、過去数年間にわたるTP-Linkのプロトコル変更とセキュリティ強化の歴史の中で、ローカルコントロールを維持するための重要な一歩となります。

全文翻訳

数ヶ月にわたり、あなたのスクリプトはTapoプラグのオン/オフを切り替えていました。その後、プラグはファームウェアを静かにアップデートし、次のリクエストは403 Forbiddenで返されるようになりました。あなたのコードは何も変更されていません。

原因は、Tapoアプリの「マイ」>「サードパーティサービス」の奥深くに隠されている「サードパーティ互換性」というスイッチです。ファームウェア1.4.0以降、プラグは、このスイッチがオンの間だけ、以前のようにサードパーティクライアントと通信します。これは何度も人々を困惑させてきました。少なくとも9件のIssueが同じ話を語っており、その中には#441、#449、#473などがあります。

私の非公式なTP-Link Tapoデバイス用RustおよびPythonクライアントであるtapoのv0.11.1以降では、軽微な例外を除き、このスイッチをオフのままにすることができます。

これは4ヶ月近くにわたる作業のハイライトであり、3つのリリースでほぼ同時に行われました。9月28日にv0.10.0、10月2日にv0.11.0、そして10月4日にv0.11.1です。その過程で、ライブラリは新しいデバイスファミリーと、人々が要望していたTapoアプリの2つの機能も追加しました。Changelogにすべての詳細が記載されています。この記事では、例を交えながらハイライトをカバーします。

ここでのすべては、ライブラリのRust版とPython版の両方に適用されます。PythonパッケージはRustクレートの薄いラッパーなので、すべての変更は同じバージョン番号の下で同時に両方に適用されます。以下の例はRustで書かれており、Pythonの呼び出しもそれに倣っています。

経緯

これは3年間で3度目となる、セキュリティ変更によって静かにサードパーティクライアントがTapoデバイスから締め出されたケースです。このスイッチは、2度目の時に残されたものです。

2023年:ライトとプラグ。 2月、カターニア大学とロンドン大学ロイヤルホロウェイ校の3人の研究者が、Tapoデバイスがアプリと通信する方法に4つの脆弱性があると報告しました。これはL530E電球から始まりました。範囲内の誰でも被害者のTapoアカウントを乗っ取り、Wi-Fiパスワードを知ることができました。数ヶ月後、ファームウェアアップデートがデバイスの元のAESプロトコルを新しいKLAPに置き換え始めました。TP-Linkは両者が関連しているとは決して言わず、変更も発表しませんでした。「これはエラーですか、それとも意図的ですか?意図的なら、なぜですか?」とあるフォーラムスレッドで尋ねられましたが、TP-Linkからの回答なしにロックされました。このライブラリを含むすべてのサードパーティクライアントは、KLAPを学ぶ必要がありました。

2024年:カメラ。 2023年11月、TapoカメラのHome AssistantインテグレーションをメンテナンスしているJuraj Nyíri氏が、TP-Linkに脆弱性を報告しました。TP-Linkはそれを修正しましたが、2024年4月までに新しいファームウェアのカメラはインテグレーションのログインを受け付けなくなりました。Nyíri氏は、TP-Linkのクラウドを経由し、リリース許可を求める回避策を構築しました。TP-Linkはコードをレビューし、許可しないと述べました。代わりに、最初の報告から8ヶ月後の2024年12月にリリースされたのは、Tapoアプリ内の古いローカルログインを再度有効にするトグルスイッチ、「サードパーティ互換性」でした。インテグレーションのリリースノートはこれをローカル制御の勝利と呼びました。

2025年:再びプラグとライト。 2025年10月、ファームウェア1.4.0は別の新しいプロトコル、TPAPを導入し、プラグを同じスイッチの後ろに置きました。ライトは2026年前半に、ファームウェア1.4.1から1.4.3でこれに続きました。今回は、ドアが閉まる前に出口が存在していました。スイッチは2024年12月からTapoアプリに存在していました。しかし、デフォルトではオフでした。TP-LinkのFAQによると、この機能は「セキュリティを確保するためデフォルトで無効になっており」、オンにすると「デバイスのセキュリティが低下する可能性がある」とのことです。新しく壊れたプラグの所有者がフォーラムで尋ねたところ、Home Assistantは「Tapo製品の公式にサポートされているサードパーティプラットフォームではない」と伝えられました。TPAP自体は文書化されていませんでした。

このスイッチは、友好的な名前を持つセキュリティダウングレードです。オンにすると、新しいプロトコルに代わって古いログインが復活しますが、新しいプロトコルの方が優れています。詳細は後述します。

TPAPサポート

最近のTapoファームウェアでは、「サードパーティ互換性」スイッチがデバイスがどのプロトコルを話すかを決定します。ライト、プラグ、電源タップ、H100ハブは、スイッチがオンの場合はKLAPを、オフの場合はTPAPを話します。カメラはKLAPを話したことはありません。それらの古いプロトコルはAES SSLであり、一部のカメラはスイッチがオフの場合にそれを拒否します。ライブラリはTPAPを話さなかったので、スイッチがオンになっているデバイスにしかアクセスできませんでした。

v0.11.1はTPAPを追加しました。ライト、プラグ、電源タップ、ハブ、およびTPAPを必要とするカメラは、IPアドレスでの接続とdiscover_devicesの両方で、スイッチがオフの場合でも使用できるようになりました。コードを変更する必要はありません。クライアントはデバイスがどのプロトコルを話すかを検出し、その上でログインします。

知っておくべきことが3つあります。

  • 間違ったパスワードはデバイスをロックする可能性があります。 ログインに複数回失敗すると、TPAPデバイスはしばらくの間、すべてのログインを拒否します。ライブラリは間違ったパスワードをTPAP_CREDENTIALSとして、ロックアウトをTPAP_AUTH_ATTEMPTS_LIMITとして報告します。どちらもループで再試行しないでください。
  • カメラハブはまだTPAPを話しません。 H200(v0.10で新規、下記参照)はファームウェア1.7.5で、スイッチのオン/オフに関わらずAES SSLをアナウンスし、ライブラリはその上でログインします。
  • 一部のカメラもまだTPAPを話しません。 モデルとファームウェアによります。C220とC510Wはファームウェア1.3.4でTPAPを話すため、スイッチオフで動作します。C210はファームウェア1.5.2では話さないため、ライブラリはAES SSL経由でログインしますが、カメラはスイッチオフ時にそのログインを拒否します。現時点ではスイッチオンの場合のみ動作します。

1つのプロトコルが到着した一方で、別のプロトコルが去りました。2023年にKLAPが置き換えた元のAESプロトコルはライブラリに残っており、IPアドレスで接続するすべてのライトとプラグをプローブして、どちらを求めているか(AESかKLAPか)を特定していました。長らくAESプロトコルを搭載したファームウェアは出荷されていないため、v0.11.0で削除されました。カメラやカメラハブが話すAES SSLは、近縁です。同じ種類の暗号化された封筒ですが、HTTPS経由で、異なるログイン方法です。これは残ります。

TPAPがより安全なプロトコルである理由

スイッチを無視できるのは良いことです。より興味深いのは、TPAPのログイン方法です。

KLAPは、両者がパスワードと、クリアで送信される2つのランダム値から構築されたハッシュを交換することで、あなたの認証情報(クレデンシャル)を知っていることを証明します。これにより、パスワード自体はワイヤー上を流れませんが、ネットワーク上の単一のログインを記録した人は誰でもそれを持ち帰り、ハードウェアの許す限り速くパスワード推測を試すことができます。セッションキーも同じ材料から生成されるため、正しい推測はそれに続くすべてのものを復号化します。

TPAPは、パスワード認証鍵交換であるSPAKE2+(RFC 9383)でログインします。2つの点が変更されます。

  • 記録されたログインは推測には無用です。 交換されるものの中に、候補パスワードに対してオフラインでチェックできるものはありません。推測をテストする唯一の方法は、デバイス自体に対して1回ずつ試すことですが、これはまさに上記のロックアウトが停止させるものです。
  • 記録されたトラフィックはプライベートなままです。 各セッションのキーは、両者がログインのために作成し、決して送信しない秘密に依存します。後でパスワードを知ったとしても、それ以前にキャプチャしたセッションを復号化することはできません。

スイッチがオンの場合、ライトやプラグはまだKLAPをアドバタイズしており、ライブラリはその上でログインするため、これら2つはスイッチがオフの場合にのみ有効です。ネットワーク上の他のものが「サードパーティ互換性」を必要としない場合、それをオフにする良い理由ができました。

その他の新機能

TPAPは大きな変更ですが、唯一の変更ではありません。

カメラハブ:H200およびH500

v0.10まで、ライブラリが通信できる唯一のハブはH100でした。H200とH500は異なる種類のデバイスです。H100と同様にセンサーやスイッチとペアリングしますが、カメラともペアリングして録画を保存します。

どちらにもハンドラーが追加され、ApiClientでh200またはh500を使用して作成できます。discover_devicesもそれらを見つけ、エラーを報告する代わりに、使用可能な状態で返します。

カメラハブにペアリングされたセンサーとスイッチは、H100の場合とまったく同じように動作します。get_child_device_listと型付けされた子ハンドラー(t100、t31xなど)を介してアクセスできます。新しい部分は録画です。ハブにペアリングされたカメラをリストし、録画がある日を見つけ、時間範囲内の録画をリストし、再生可能なMPEG-TSクリップとして1つをダウンロードできます。

use tapo::ApiClient;

let hub = ApiClient::new("<tapo-username>", "<tapo-password>")
    .h200("<hub ip address>")
    .await?;

let end_time = chrono::Utc::now();
let start_time = end_time - chrono::Duration::days(7);

for camera in hub.get_general_device_list().await? {
    if !camera.hub_storage_enabled {
        continue;
    }

    let recordings = hub
        .get_recordings(camera.device_id.clone(), start_time, end_time)
        .await?;

    if let Some(recording) = recordings.first() {
        let mut media = Vec::new();
        hub.download_recording(
            camera.device_id.clone(),
            recording.start_time,
            recording.end_time,
            &mut media,
        )
        .await?;

        std::fs::write("recording.ts", &media)?;
    }
}

download_recordingは任意のAsyncWriteに書き込むため、クリップは上記のバッファに、または直接ファイルに書き込むことができます。Pythonでは、代わりにファイルパスを取ります。すべての時間はUTCです。RustではDateTime<Utc>、Pythonではタイムゾーン対応のdatetimeです。

完全な例はリポジトリにあります。Rust用はこちら、Python用はこちらです。

私はどちらのハブも所有していないため、これらはすべて@dominiquefournier氏(H200での約30回のテストに付き合ってくれた)と、@supermimai氏(H500でテストしてくれた)なしには存在しませんでした。両氏に感謝します。

プラグのスケジュールとタイマー

Tapoアプリには、以前からプラグ用の「スケジュール」と「タイマー」がありました。v0.10以降、ライブラリにもこれらが追加され、PlugHandlerとPlugEnergyMonitoringHandlerで利用できます。どちらも@Hueburtsonly氏の貢献によるものです。

スケジュールルールは、1日の特定の時刻、または日の出や日の入りからのオフセットで、一度だけ、または特定の曜日に実行されます。ルールはプラグ上に存在し、プラグ自身の時計で実行されるため、スクリプト、サーバー、またはインターネット接続がダウンしている場合でも機能し続けます。

use tapo::ApiClient;
use tapo::requests::{DaysOfWeek, ScheduleRule};
use tapo::responses::PowerState;

let device = ApiClient::new("<tapo-username>", "<tapo-password>")
    .p110("<device ip address>")
    .await?;

// 月曜日と水曜日の23:30にオフ。
let rule = 
    ScheduleRule::clock_weekly(23, 30, DaysOfWeek::MON | DaysOfWeek::WED, PowerState::Off)?;
let late_night = device.add_schedule_rule(rule).await?;

// 毎日、日の出の1時間後にオン。
let rule = ScheduleRule::sunset_weekly(60, DaysOfWeek::EVERY_DAY, PowerState::On)?;
device.add_schedule_rule(rule).await?;

// 平日の日の出30分前にオフ。
let rule = ScheduleRule::sunrise_weekly(-30, DaysOfWeek::WEEKDAYS, PowerState::Off)?;
device.add_schedule_rule(rule).await?;

// デバイスから読み戻されたルールは読み取り専用です。`to_editable`は、それを変更して再度送信できるルールに変換します。
let edit = late_night.to_editable()?.with_enabled(false);
device.edit_schedule_rule(edit).await?;

一度だけ実行されるルール用のclock_once、sunrise_once、sunset_once、デバイス上のルール数と空き容量を確認するget_schedule_rulesとget_max_schedule_rules、そしてクリーンアップ用のremove_schedule_ruleとremove_all_schedule_rulesもあります。

タイマーはよりシンプルな兄弟です。set_timerは、プラグがオンまたはオフになるまでの1秒から24時間の単一のカウントダウンを設定します。get_timerはそれを読み取り、clear_timerはキャンセルします。プラグは一度に1つのアクティブなタイマーしか保持できないため、set_timerは以前にアクティブだったものを置き換えます。

MCPサーバー

tapo-mcp(TapoデバイスをAIエージェントに公開するMCPサーバー)は、これらの変更のうち2つを取り込みました。v0.5.3以降、H200およびH500カメラハブとそれにペアリングされたセンサーをリストし、「サードパーティ互換性」がオフになっているデバイスでも動作します。プラグのスケジュール、タイマー、録画ダウンロードは、現時点ではライブラリのみで利用可能です。

アップグレード前の注意

v0.9からアップグレードする場合、いくつかの破壊的変更が予想されます。レガシーAESプロトコルは削除され、トリガーログと温度記録のフィールド名が変更され、Pythonの列挙値は整数と等しく比較されなくなりました。Changelogにすべての変更点がリストされています。

今後の予定

いくつかの項目がリストにあります。

  • MCPサーバーでのさらなる機能拡張。 エネルギー使用量と検出結果のキャッシュが最優先で、関心があれば録画ダウンロードも続く可能性があります。
  • H110ハブ。 @skoky氏が、赤外線リモコンとしても機能するハブであるH110を追加するプルリクエスト(#607)を進行中です。
  • より多くのカメラ。 現在、ライブラリにはパン・チルト機能付きカメラのハンドラーしかありません。固定カメラ用のハンドラーを追加する計画があり、まずは一般的なC120から開始します。
  • デバイスシミュレーター。 テストをより良く行いたいと考えています。現在、ライブラリのほとんどは実際のハードウェアでしかテストできず、カメラハブのような一部のハードウェアは私が所有していません。デバイスと同様に応答するシミュレーターがあれば、テスターが手動で行う前に、ログインの失敗や応答の誤りを検出できるでしょう。
  • Node.jsラッパーの可能性。 これは長期的なものであり、約束ではありません。Pythonパッケージを生み出したのと同じアプローチで、ライブラリをNode.jsにもたらすことができます。

それまでの間、もしこのライブラリが「サードパーティ互換性」をオンにしておく唯一の理由だったのであれば、アップグレードしてオフにしてください。それでもデバイスがログインを拒否する場合、そのモデルとファームウェアを添えてIssueを開いてください。そのような報告が、C210に注意書きが追加されたり、H200がサポートされたりした方法です。

AI利用に関する免責事項

英語は私の母国語ではなく、どの言語でも才能のあるライターではありません。そのため、文章の推敲にAIを使用しています。アイデア、セットアップ、間違い、意見はすべて私自身のものです。それらはAIに、不完全な英語で書かれた詳細なメモとして渡され、AIが英語を修正します。思考を提供しているわけではありませんが、信頼できるリサーチアシスタントです。