Nebula C# SDK 接入文档

📚 本文属 Nebula 文档中心，相关文档：C++ SDK 接入 · API 接口 · Python SDK 接入

适用对象：C# SDK（.NET 10 / WinForms，Windows x64）
SDK 组成：NebulaClient.cs（主类）+ core/（通信/安全）+ protect/（运行时防护/混淆/壳标记）

1. 概述

Nebula C# SDK 与 C++ 版协议同规格，内置：

通信协议（Nebula 3.1）：ECDH P-256 会话握手 + AES-256-GCM 加密信封 + seq 单调防重放，客户端零静态对称机密，会话失效自动重握手
响应防伪造：响应 ES256|RS256 非对称验签——未配置公钥时 SDK 拒绝连接（防伪造服务器设计）
完整流程：init → login（password / username_code / code 三种方式按后台下发自动适配）→ heartbeat → logout
内置能力：完整性自校验、自动更新、弹窗/立即公告、离线宽限票据、功能密钥 NF1、运行时防护（反调试/反 VM·沙箱/代码补丁自检）、字符串混淆、壳标记

2. 快速开始

2.1 最简接入

using Nebula.Sdk;

// ① 用 SdkConfig 常量创建客户端
var client = NebulaFactory.CreateDefaultClient(
    machineId: "",            // 留空自动生成（建议持久化后传入）
    osInfo: "Windows",
    clientVersion: "1.0.0");

// ② 初始化
var init = client.Init();
if (!init.Ok) { /* 初始化失败处理 */ }

// ③ 登录
var login = client.Login("用户名", "密码");
if (login.Ok) {
    client.StartHeartbeat(login.Token, (code, msg, hb) => {/* 心跳回调 */});
}

2.2 前置条件

在 SdkConfig.cs 填入后台获取的 4 项配置（见 §3）
项目引用 System.Management NuGet 包（反 VM 的 WMI 查询依赖）
目标框架 net10.0-windows（WinForms + Windows 专用 API）

3. 配置（SdkConfig.cs）

SdkConfig.cs 是接入方唯一需要修改的文件，常量来自后台「软件管理」：

字段	必填	说明
`ApiUrl`	✅	API 地址，以 `/api/index.php` 结尾
`AppKey`	✅	软件标识，每个软件独立
`RespSignPubKey`	✅	响应签名公钥（PEM），验签服务端响应
`TlsCertSha256`	❌	TLS 证书指纹（64 位 hex），HTTPS 防中间人
`ProtectStrictPolicy`	❌	防护严格模式（false=宽松/默认，true=严格）
`DebugLog`	❌	调试日志（发布置 false）

⚠ RespSignPubKey 为空时所有请求返回配置错误、拒绝连接；生产务必配 TlsCertSha256；勿把含真实公钥/域名的配置提交到公开仓库。

4. 核心接口

Init：拉取配置 / 公告 / 版本；设置登录方式
Login：3600 三方式自动适配；登录成功返回 token / expire / user / VIP / 设备绑定 / 离线宽限票据 / 功能密钥 NF1
Heartbeat：实时下发剩余时长、踢下线指令；离线宽限期间本地解票据
Logout：服务端销毁会话；需携带 machine_id（2026-10 起强制设备绑定）
Devices / UnbindDevice / Userinfo：设备管理、用户信息（均携带 machine_id）
自动更新：检查 → 下载 → hash+size 强校验 → 替换 → 重启

5. 运行时安全防护

RuntimeProtection 提供反调试、反虚拟机/沙箱、代码补丁自检；Obfuscate 提供字符串混淆 / 间接调用 / 不透明谓词。三档等级（0 关闭 / 1 基础 / 2 标准 / 3 严格）：

反调试：IsDebuggerPresent / PEB.BeingDebugged / NtQueryInformationProcess / 硬件断点 Dr0-Dr7 / 调试堆标志
反 VM/沙箱：虚拟机/沙箱进程与模块特征、WMI 环境识别
代码补丁自检：GuardCode 登记关键函数，运行时比对

检测一次：var report = RuntimeProtection.Scan();；上报到服务端：client.ReportRuntimeEvent(login.Token, report);（网络失败自动入队、随心跳补发）。

服务端开启 require_runtime_guard 强制策略时，登录须带 capabilities:{"runtime_guard":true}（本 SDK 已自动上报）；客户端自报 risk_level/risk_score 仅作 telemetry，处置等级由服务端二次定级。

6. 壳保护集成（VMProtect / Themida）

NebulaShell 提供壳标记（ShellEnable 时运行时探测已装壳 SDK）；标记只是「告诉壳保护这里」，真正加壳仍需用 VMProtect / Themida 对编译产物处理。加密体系：SecureBuffer（擦除型敏感内存）+ 字符串混淆 + 已验证核心区标记。

7. 防护差异与建议

C# 经 JIT 编译，比 C++ 更易被 dnSpy/ILSpy 反编译 —— 建议：关键逻辑用 SecureString 擦除内存，核心算法走 C++/Native 扩展，或用 Nuitka 型 BeforeFieldInit/加壳器（如 .NET Reactor / ConfuserEx） 保护程序集
关键判定移至服务端，客户端只收结果不做本地判定
用足内置：完整性自校验（后台登记 self_file_hash）+ 功能密钥 NF1（核心数据封包分发）