TPM Quickstart

完成第一次裝置註冊，並驗證日常啟動只使用 Device ID、一次性 Challenge 與 TPM Signature。

下載安全範例返回範例庫

這個範例解決什麼問題

當你第一次把 SDK 接進產品時，先用這個範例建立最小可驗證路徑。它同時確認 SDK 安裝、公開 Gateway URL、Product 設定、TPM Key Provider 與 Gateway 回應簽章是否都能正常工作。

適合使用的場景

剛收到 SDK Wheel 與部署參數，需要確認整合環境是否完整。
要建立自動化測試的最小基準，區分 Client、網路與授權設定問題。
準備把驗證流程整合進 GUI 或 CLI 前，先確認純 Python 流程可通過。

為什麼採用這種設計

License Key 只在第一次註冊時輸入，避免長期保存在程式、設定檔或 Log。
本機 TPM 私鑰不可匯出，之後由 TPM 對一次性 Challenge 簽章，降低複製 registration.json 冒充裝置的風險。
Client 固定 Gateway 公鑰並驗證回應簽章，避免把未經信任的網路回應當成有效授權結果。

程式實際怎麼執行

同步執行。第一次需要 License Key；之後由同一呼叫完成 Challenge、TPM 簽章與線上驗證。沒有背景執行緒。

SDK 自動完成

依 requires_license_key 選擇首次註冊或後續驗證。
驗證 Gateway 回應簽章並保存非秘密 registration。

你的程式必須負責

安全詢問第一次 License Key。
處理所有 SDK 例外並阻擋功能。
長時間程式另外安排後續驗證。

呼叫時機／頻率

每次程式啟動一次。
第一次成功後關閉重跑，確認不再要求 Key。

成功時應看到

首次建立 Device/Machine；後續使用 TPM proof。
registration 與 Log 不含 License Key。

失敗處理

簽章、TPM、License 或網路不確定時全部 fail closed。
本機身分不一致時不要自動刪 TPM Key。

建議整合步驟

步驟 1
向管理員取得 SDK Wheel、Gateway URL、Product UUID、Product Namespace、Gateway Public Key 與 Key ID。
步驟 2
在乾淨的虛擬環境安裝 SDK，填入正式部署參數。
步驟 3
第一次執行時安全輸入 License Key；成功後重新啟動並確認日常驗證流程不保存 License Key。
步驟 4
檢查 connection.log，確認 registration 與 validation 都回傳成功。

完整程式碼

公開範例使用 Placeholder，重點是理解資料流與 API 行為。正式 Gateway URL、Product UUID、Namespace 與 Public Key 請向授權管理員取得；可直接運行的完整範例由管理員在 Admin SDK 整合中心下載。

"""Safe public Quickstart.

Replace every placeholder with deployment values supplied by your
administrator before running this file. The public Web does not publish SDK
wheels, Product IDs, public keys, or License Keys.
"""

from __future__ import annotations



import getpass



from keygen_device_sdk import ClientConfig, DeviceLicenseClient, LicenseSDKError





PLACEHOLDER_VALUES = {

    "https://license.example.com",

    "YOUR-PRODUCT-UUID",

    "com.example.your-product",

    "YOUR-GATEWAY-PUBLIC-KEY",

}





def build_client() -> DeviceLicenseClient:

    config = ClientConfig(

        gateway_base_url="https://license.example.com",

        product_id="YOUR-PRODUCT-UUID",

        product_namespace="com.example.your-product",

        gateway_signing_public_key_b64="YOUR-GATEWAY-PUBLIC-KEY",

        gateway_signing_key_id="gateway-v1",

        connection_log_enabled=True,

    )

    configured_values = {

        config.gateway_base_url,

        config.product_id,

        config.product_namespace,

        config.gateway_signing_public_key_b64,

    }

    if configured_values & PLACEHOLDER_VALUES:

        raise SystemExit(

            "Replace the public placeholders with values supplied by your administrator before running this example."

        )

    return DeviceLicenseClient(config)





def main() -> int:

    client = build_client()

    try:

        key = (

            getpass.getpass("License key (first activation only): ").strip()

            if client.requires_license_key

            else None

        )

        state = client.ensure_registered(key).require_valid()

        print("License valid:", state.valid)

        print("Device ID:", state.device_id)

    except LicenseSDKError as exc:

        raise SystemExit(f"License startup failed: {exc}") from exc

    return 0





if __name__ == "__main__":

    raise SystemExit(main())

上線前至少測試

首次與第二次啟動。
撤銷、過期、斷網、錯誤 Public Key。
秘密掃描。

常見錯誤

不要把 License Key 寫死在原始碼、環境變數範例或安裝包中。
不要把 Platform 版本填入 ValidationScope.version；該欄位只代表實際建立的軟體 Release。
不要在多個不同產品共用同一個 product_namespace。