Nebula DLL 版 SDK 接入文档（NebulaSDK_x64 / x86.dll）

📚 本文属 Nebula 文档中心，主索引见 Nebula 文档中心；相关文档：C++ SDK 接入 · SDK 加固指南 · API 接口

适用对象：NebulaSDK_x86.dll / NebulaSDK_x64.dll（纯 DLL 黑盒，C 接口）
调用约定：__stdcall · 字符串编码：UTF-8（char*）· 适用平台：Windows 7+（x86 / x64）
目标调用方：易语言、C/C++、C#、Delphi、Python 等一切能调用 Windows DLL 的语言

1. 概述与选型

DLL 版是 Nebula SDK 的二进制黑盒形态：把 Nebula 3.1 协议（ECDH P-256 握手 + AES-256-GCM 信封 + ES256 响应验签 + seq 防重放）完整封装进一个 DLL，导出 38 个 C 风格函数。调用方零密码学实现，声明即可用。

2. 交付物清单

编译环境：Visual Studio 2022（v145 工具集）、C++20、Windows SDK 10。DLL 与宿主架构必须一致，混用会导致 LoadLibrary 失败。

3. 两种集成方式

方式 A：隐式链接（.lib + .h + .dll）

适合 C/C++、易语言。VS 项目设置：链接器 → 输入 → 附加依赖项加 NebulaSDK_x86.lib（或 x64）；附加库目录指向 .lib 路径；C/C++ → 附加包含目录指向 NebulaSDK.h。

cl /EHsc main.cpp /I. /link NebulaSDK_x86.lib    rem 32 位
cl /EHsc main.cpp /I. /link NebulaSDK_x64.lib    rem 64 位

.lib 只是导入库，运行时仍需对应架构的 .dll 与 exe 同目录。

方式 B：动态加载 LoadLibrary（免 .lib）

适合 C#、Python、Delphi 或需要运行时按需加载的场景。只需 .dll 一个文件，用 LoadLibraryA + GetProcAddress 逐个取函数地址（声明原型参见 NebulaSDK.h）。

4. 调用流程

Nebula_Create                  创建实例
    |
Nebula_SetServer / SetAppKey / SetClientVersion / SetMachineId
Nebula_SetRespSignKey          (可选) 响应签名公钥
Nebula_SetDeviceInfo           (可选) 设备指纹六项
    |
Nebula_Handshake               ECDH P-256 握手，建立加密通道
    |
Nebula_Init                    初始化，拉取配置（含软件名称）
    |
Nebula_LoginPassword / LoginUsernameCode / LoginCard   三选一登录
    |
Nebula_Heartbeat / GetUserInfo / GetDevices / GetNotice / CheckVersion
Nebula_GetOnline / Activate / Unbind / DecryptFeature
Nebula_SecurityCheck           (v2.2+) 周期安全自检
    |
Nebula_Logout                  退出登录
    |
Nebula_Destroy                 销毁实例（自动清零敏感内存、停心跳线程）

机器码需调用方自行采集传入 Nebula_SetMachineId（DLL 不自动采集硬件信息，避免 WMI 权限、虚拟机兼容、易语言环境差异等问题）。常见方式：硬盘序列号 / CPU ID / 主板序列号单项、多项拼接取 SHA256，或 Windows 产品 ID。设备绑定由服务端自动处理：已绑定设备直接通过，未绑定未达上限自动绑定，达上限拒绝（4001）。

最小可运行示例（C）：

#include "NebulaSDK.h"
#include <stdio.h>

int main() {
    NEBULA_HANDLE h = Nebula_Create();
    Nebula_SetServer(h, "https://your-server.com");
    Nebula_SetAppKey(h, "YOUR_APP_KEY");
    Nebula_SetClientVersion(h, "1.0.0");
    Nebula_SetMachineId(h, "MACHINE_ID");

    if (Nebula_Handshake(h) != 0) { Nebula_ShowErrorBox(h, NULL); Nebula_Destroy(h); return 1; }
    Nebula_Init(h);

    if (Nebula_LoginPassword(h, "your_username", "your_password") == 0) {
        char result[16384];
        Nebula_GetResult(h, result, sizeof(result));
        printf("Login: %s\n", result);
        Nebula_Heartbeat(h);                /* 心跳保活，30~60 秒一次 */
        Nebula_Logout(h);
    } else {
        Nebula_ShowErrorBox(h, NULL);       /* 失败直接弹框，免拼错误信息 */
    }
    Nebula_Destroy(h);
    return 0;
}

5. API 一览

全部 38 个导出函数均为 __stdcall，字符串参数为 UTF-8 const char*；返回 0 成功，负数为 DLL 内部错误，正数为服务端业务码。

5.1 生命周期与配置

5.2 握手 / 初始化 / 登录

v2.1 起登录请求自动携带 capabilities: {"runtime_guard": true}，服务端开启 RuntimeGuard 强制策略时可正常放行。

5.3 业务 API（登录后）

5.4 结果 / 状态 / Feature

返回 JSON 统一格式：{code, msg, success, data, need_relogin, need_update, force_offline}。登录成功 data 含 token / expire_at / feature_key；Init 响应 data 含 software.name（提示框标题）、heartbeat_interval（心跳建议间隔）、session_ttl、version（latest / need_update）、grace（离线宽限开关）。

5.5 运行时安全与自动心跳（v2.2+）

完整内存守卫 / 模块注入 / Manual Map 检测仅在 C++ 源码 SDK 提供；DLL 黑盒版内置「可靠不误报」检测集 + 策略驱动处置。

5.6 自动更新与代理（v2.3+）

5.7 内置提示与自定义 UI

提示框标题自动使用 Init 下发的软件名称——后台改软件名即生效，无需改代码重编译。

6. 错误码

DLL 内部错误（负数）

服务端业务码（正数，与 HTTP 接口一致）

7. 易语言接入示例

DLL 命令声明（32 位）：

.版本 2
.DLL命令 Nebula_Create, 整数型, "NebulaSDK_x86.dll", "Nebula_Create"
.DLL命令 Nebula_Destroy, , "NebulaSDK_x86.dll", "Nebula_Destroy"
    .参数 handle, 整数型
.DLL命令 Nebula_SetServer, 整数型, "NebulaSDK_x86.dll", "Nebula_SetServer"
    .参数 handle, 整数型
    .参数 server_url, 文本型
.DLL命令 Nebula_SetAppKey, 整数型, "NebulaSDK_x86.dll", "Nebula_SetAppKey"
    .参数 handle, 整数型
    .参数 app_key, 文本型
.DLL命令 Nebula_Handshake, 整数型, "NebulaSDK_x86.dll", "Nebula_Handshake"
    .参数 handle, 整数型
.DLL命令 Nebula_Init, 整数型, "NebulaSDK_x86.dll", "Nebula_Init"
    .参数 handle, 整数型
.DLL命令 Nebula_LoginPassword, 整数型, "NebulaSDK_x86.dll", "Nebula_LoginPassword"
    .参数 handle, 整数型
    .参数 username, 文本型
    .参数 password, 文本型
.DLL命令 Nebula_GetResult, 整数型, "NebulaSDK_x86.dll", "Nebula_GetResult"
    .参数 handle, 整数型
    .参数 buffer, 文本型
    .参数 buffer_size, 整数型
.DLL命令 Nebula_ShowErrorBox, 整数型, "NebulaSDK_x86.dll", "Nebula_ShowErrorBox"
    .参数 handle, 整数型
    .参数 hwnd, 整数型

调用：

handle ＝ Nebula_Create ()
Nebula_SetServer (handle, "https://your-server.com")
Nebula_SetAppKey (handle, "YOUR_APP_KEY")
.如果 (Nebula_Handshake (handle) ＝ 0)
    Nebula_Init (handle)
    .如果 (Nebula_LoginPassword (handle, "user", "pass") ＝ 0)
        result ＝ 取空白文本 (16384)
        Nebula_GetResult (handle, result, 16384)
        Nebula_SetAutoHeartbeat (handle, 1, 0)    ' v2.2+ 内置心跳，免时钟循环
        Nebula_Logout (handle)
    .否则
        Nebula_ShowErrorBox (handle, 0)           ' 失败直接弹框
    .如果结束
.否则
    Nebula_ShowErrorBox (handle, 0)
.如果结束
Nebula_Destroy (handle)

8. C# / Python 调用提示

C#（P/Invoke）：[DllImport("NebulaSDK_x86.dll", CallingConvention = CallingConvention.StdCall)]；字符串参数用 string（CharSet.Ansi），输出缓冲用 StringBuilder；句柄用 IntPtr。注意 AnyCPU 目标需在项目属性里固定「首选 32 位」或分别编译 x86/x64 两版，保证与 DLL 架构一致。

Python（ctypes）：ctypes.WinDLL("NebulaSDK_x86.dll")（__stdcall 对应 WinDLL）；句柄 c_void_p；字符串入参传 bytes（UTF-8），出参用 ctypes.create_string_buffer(16384) 后 .value.decode("utf-8")。

全部参数均为 UTF-8：C# 非 ASCII 内容需先转 UTF-8；Python 传 "中文".encode("utf-8")。

9. 加固与加壳

• Release 构建已内置：符号隐藏、字符串合并、COMDAT 折叠、全程序优化、无 PDB（PostBuild 删除 .exp/.pdb）、PE 校验和
• 加载时反调试（仅 Release）：IsDebuggerPresent / CheckRemoteDebuggerPresent / PEB NtGlobalFlag 三层，命中即加载失败（不用 TerminateProcess，更难定位）
• 敏感内存清零：握手后清 ECDH 私钥与共享密钥、Feature 解密后清密钥副本、Logout 清 feature_key、Destroy 清全部会话密钥
• 外层加壳：可对宿主 exe 使用 VMProtect / Themida 正常加壳；对 NebulaSDK_*.dll 本体建议保持原样（内部已加固，且壳可能破坏 DLL 的 TLS / 导入表导致加载失败；如必须加壳，请先用 Nebula_SelfIntegrityCheck 场景回归测试）
• DLL 自校验默认不启用：版本管理登记的哈希即客户端 exe 的哈希（一份登记两用：更新下载校验 + 宿主自校验），不登记 DLL 哈希；Nebula_SelfIntegrityCheck 未登记时返回 0 自动跳过，调用方无需处理
• 安全设计原则：DLL 不持有任何长期秘密（签名私钥只在服务端）；不做本地授权判断（授权全部由服务端决定）；即使 DLL 被完全逆向也无法伪造服务器响应（ES256 签名）；即使 DLL 被 patch 也无法获得服务器权限（服务端最终判定）；AppKey 是软件标识而非秘密凭证，泄露无碍协议安全

10. 常见问题

• 线程安全：内部互斥锁保护，所有 API 可跨线程调用同一 handle；高并发场景会被锁串行化，避免大量并发调用
• 缓冲区：GetResult ≥16KB、GetLastErrorMessage ≥1KB、DecryptFeature ≥8KB；不足会被截断（返回实际写入字节数）
• 内存管理：SDK 与调用方之间不传递动态分配指针，输出全部走调用方缓冲区，无需也不应释放 SDK 返回的数据
• 超时：连接 / 发送 10 秒，接收 30 秒
• HTTPS 证书：DLL 默认不校验 SSL 证书（兼容自签 / 调试）；但只要调用了 Nebula_SetRespSignKey，ES256 签名验证即保证响应真实性——SSL 校验可忽略，签名验证不可忽略
• 密钥安全：DLL 不提供任何读取内部密钥的接口；会话密钥 / ECDH 私钥 / feature_key 仅内部使用
• 架构不匹配：LoadLibrary 失败最常见原因——32 位程序配 x86 DLL，64 位配 x64
• 提示框标题：未 Init 或 Init 失败时用默认「Nebula SDK」；正常流程下自动用服务端软件名