ZSeal.Hart.Licensing 1.0.2

ZSeal Hart Licensing SDK

ZSeal.Hart.Licensing 是面向桌面端的离线授权验签 SDK，强调安全性、可审计性与 AOT 友好。当前以 Windows 为主，跨平台能力后续补齐。

许可：本包为内部许可。公开 NuGet 仅为分发便利，非授权用户不得使用与分发。

核心特性

• ECDSA P-256 签名验签：防篡改/防伪造。
• 机器绑定：
  • V1 强绑定：全因子哈希（安全优先）。
  • V2 弱绑定：多因子阈值匹配（容错更强）。
• 反回滚：检测时间回退与授权降级。
• AOT 友好：无反射依赖，支持 NativeAOT。

安装

<PackageReference Include="ZSeal.Hart.Licensing" Version="1.0.1" />

如需启用 Native 全链路验签（可选增强），请同时安装：

<PackageReference Include="ZSeal.Hart.Licensing.Native" Version="1.0.1" />

说明：Native 包可选，仅在默认组件场景生效；当前仅提供 win-x64 运行时资产，且需与主包版本一致。 NuGet 页面会直接显示本 README（由 PackageReadmeFile=README.md 提供）。

使用方法（核心用法）

1) 启动时验签（最常用）

using ZSeal.Hart.Licensing;
using ZSeal.Hart.Licensing.Crypto;

var keyRing = new StaticKeyRing(new[]
{
    new PublicKeyEntry(
        keyId: "key-2024",
        qx: Convert.FromBase64String("..."),
        qy: Convert.FromBase64String("..."),
        status: KeyStatus.Active),
});

var options = new VerifyOptions
{
    ProgramId = "com.yourcompany.app",
    CompanyName = "Hart",
    KeyRing = keyRing,
};

var result = LicenseVerifier.Verify(options);
if (!result.Ok)
{
    Console.WriteLine($"授权失败：{result.Code}");
    return;
}
Console.WriteLine("授权有效");

2) 无文件通道导入授权码（Base64）

var importResult = LicenseImporter.ImportFromCode(licenseCode, options);
if (!importResult.Ok)
{
    Console.WriteLine(importResult.Code);
    return;
}

说明：ImportFromCode 在 Strict 模式遇到首启 E_STATE_TAMPERED_OR_MISSING 时会自动执行一次自举重试。
如需显式控制流程，仍可使用 ImportFromCodeWithBootstrap。

2.1) 首启自举导入（推荐给首启场景）

var importResult = LicenseImporter.ImportFromCodeWithBootstrap(licenseCode, options);
if (!importResult.Ok)
{
    Console.WriteLine(importResult.Code);
    return;
}

3) 直接用字节流验签（不落盘）

var licenseBytes = Convert.FromBase64String(licenseCode);
var result = LicenseVerifier.VerifyFromBytes(licenseBytes, options);

3.1) 首启自举验签（避免首次缺失 state）

var licenseBytes = Convert.FromBase64String(licenseCode);
var result = LicenseVerifier.VerifyFromBytesWithBootstrap(licenseBytes, options);

3.2) 启动时自举验签（默认路径）

var result = LicenseVerifier.VerifyWithBootstrap(options);

4) ProgramId 白名单验签（升级兼容）

var result = LicenseVerifier.VerifyWithProgramIdWhitelist(
    options,
    new[] { "com.old.app", "com.new.app" });

5) 扩展方法：剩余时间 / 是否过期

var result = LicenseVerifier.Verify(options);
if (result.TimeInfo is not null)
{
    var remaining = result.GetRemaining();          // TimeSpan?
    var remainingSeconds = result.GetRemainingSeconds(); // long?
    var isExpired = result.IsExpired();
    var isPermanent = result.IsPermanent();
}

6) 管理员权限提示（一次性）

var r = ElevationHelper.EnsureRegistryAccessOnce(options);
if (r.Status == ElevationPromptStatus.Prompted && r.ShouldExit)
{
    Environment.Exit(0);
}

说明：默认机器指纹与反回滚使用内置实现（Windows）。如需自定义，使用 IMachineIdProvider / IAntiRollbackStore。 提示：LicenseRuntime 在 Auto 模式下会优先高安全策略，并在可恢复环境失败时自动降级兼容策略。

7) 中文错误封装（推荐）

var result = LicenseVerifier.VerifyWithBootstrap(options);
if (!result.Ok)
{
    var message = result.GetUserMessageZh();
    Console.WriteLine(message);
}

8) 运行时守护（长时间运行程序推荐）

using var guard = new LicenseGuard(options, new LicenseGuardOptions
{
    VerifyImmediately = true,
    UseBootstrap = true,
    ReverifyStrictAfterBootstrap = true,
    CallbackContext = SynchronizationContext.Current,
});

guard.VerificationUpdated += r => Console.WriteLine($"[Guard] {r.Code}");
guard.VerificationFailed += r => Console.WriteLine(r.GetUserMessageZh());

关键文档

• SDK 使用指南：docs/SDK使用指南.md
• 全场景使用指南：docs/全场景使用指南.md
• WMI 强化示例：docs/IMachineIdProvider-WMI示例.md
• 文档导航（使用说明树）：docs/文档导航.md
• NuGet 发布与 README 显示说明：docs/NuGet发布与README显示说明.md

文档树（使用说明）

docs/
├─ 文档导航.md                      # 文档入口与阅读顺序
├─ SDK使用指南.md                   # SDK 参数与行为细节
├─ 使用流程代码示例.md              # 端到端代码流程
├─ 全场景使用指南.md                # 场景化接入与排障
├─ Native与WPF使用指南.md           # Native/WPF 工具实战
├─ IMachineIdProvider-WMI示例.md    # WMI 扩展示例（可选）
└─ NuGet发布与README显示说明.md     # 打包/发布/官方规范链接

NuGet 官方参考（Microsoft）

• 创建与发布包：https://learn.microsoft.com/nuget/create-packages/creating-a-package-msbuild
• dotnet/msbuild pack 参数：https://learn.microsoft.com/nuget/reference/msbuild-targets#pack-target
• NuGet 显示包内 README：https://learn.microsoft.com/nuget/nuget-org/package-readme-on-nuget-org
• 发布到 nuget.org：https://learn.microsoft.com/nuget/nuget-org/publish-a-package

适用场景

• 桌面客户端（WPF/WinForms）离线授权
• 内部工具授权
• 高价值本地应用（需反回滚与机器绑定）

许可

见根目录 LICENSE.txt。

9) 一体化 Facade（LicenseRuntime，最少代码接入）

var securityOptions = new LicenseSecurityOptions
{
    Mode = LicenseSecurityMode.Auto, // Auto/Secure/Compat
};

using var runtime = new LicenseRuntime(options, securityOptions);

var import = runtime.ImportFromCode(licenseCode);
if (!import.Ok)
{
    var err = import.ToUserError();
    Console.WriteLine($"{err.MessageZh} {err.ActionHint}");
    return;
}

var verify = runtime.VerifyNow();
if (!verify.Ok)
{
    var err = verify.ToUserError();
    Console.WriteLine($"{err.MessageZh} {err.ActionHint}");
    return;
}

runtime.StartMonitoring(new LicenseGuardOptions
{
    VerifyImmediately = true,
    UseBootstrap = true,
    ReverifyStrictAfterBootstrap = true,
    CallbackContext = SynchronizationContext.Current,
});

runtime.VerificationFailed += result =>
{
    var err = result.ToUserError();
    var mode = result.AuditTags.TryGetValue("SecurityMode", out var modeValue) ? modeValue : "Unknown";
    Console.WriteLine($"{err.MessageZh} {err.ActionHint} (Mode={mode})");
};

10) 结构化错误对象（LicenseUserError）

var result = runtime.VerifyNow();
if (!result.Ok)
{
    var error = result.ToUserError();
    Console.WriteLine(error.Code);
    Console.WriteLine(error.Status);
    Console.WriteLine(error.MessageZh);
    Console.WriteLine(error.ActionHint);
}