DPAPI加密仅限Windows且不可跨用户或跨机器解密，绑定当前用户会话或本地机器上下文；使用ProtectedData.Protect/Unprotect时需严格匹配作用域和optionalEntropy，否则抛CryptographicException。
DPAPI 加密必须在 Windows 上运行，且不能跨用户或跨机器解密
DPAPI（Data Protection API）是 Windows 内置的加密机制，它不依赖密钥管理，而是绑定当前用户登录会话或本地机器上下文。这意味着：ProtectedData.Protect 加密的数据，只能由同一用户（或同一机器，取决于作用域）调用 ProtectedData.Unprotect 解密。一旦换用户、换机器、甚至用户重置密码后未同步凭据，数据就无法恢复——这不是 bug，是设计使然。
常见误用场景包括：把加密后的字节数组存到数据库，然后在 Web 服务（以 ApplicationPoolIdentity 运行）里尝试解密；或在 Windows 服务中用 LocalMachine 作用域加密，却期望普通用户进程能解密。这些都会抛出 CryptographicException，错误信息通常是 “The parameter is incorrect” 或 “Key not valid for use in specified state”。
实操建议：
- 确认运行环境：仅限 Windows，.NET Framework 2.0+ 或 .NET Core 3.0+（需 Windows 兼容层，如
Microsoft.AspNetCore.DataProtection不等于 DPAPI） - 选择作用域：
DataProtectionScope.CurrentUser（推荐，默认，绑定登录用户）或DataProtectionScope.LocalMachine（绑定机器，所有用户可解密，但安全性更低） - 不要试图提取或导出 DPAPI 的底层密钥——它不可见、不可导出
使用 ProtectedData.Protect 和 Unprotect 的最小可行代码
核心就是两行：加密用 ProtectedData.Protect，解密用 ProtectedData.Unprotect。注意它们只接受 byte[]，不支持直接处理字符串或对象，必须手动编码/序列化。
示例（加密一段密码字符串）：
using System;
using System.Security.Cryptography;
using System.Text;
string secret = "my-api-key-123";
byte[] secretBytes = Encoding.UTF8.GetBytes(secret);
byte[] encrypted = ProtectedData.Protect(
userData: secretBytes,
optionalEntropy: null, // 一般设为 null；若设了，解密时必须传相同值
scope: DataProtectionScope.CurrentUser
);
// 存储 encrypted（比如写入文件或注册表）
File.WriteAllBytes("secret.protected", encrypted);
// 解密时：
byte[] loaded = File.ReadAllBytes("secret.protected");
byte[] decryptedBytes = ProtectedData.Unprotect(
encryptedData: loaded,
optionalEntropy: null,
scope: DataProtectionScope.CurrentUser
);
string decrypted = Encoding.UTF8.GetString(decryptedBytes); // 得到原始字符串
关键点：
-
optionalEntropy不是密码，也不是 salt，它是可选的附加混淆参数；设了就必须严格一致，否则解密失败 - 加密/解密前后务必保持字节一致性；UTF8 编码是常见选择，但若原始数据含 BOM 或有编码歧义，需统一处理
- 不要对空数组或 null 调用
Protect，会抛ArgumentException
DPAPI 在 ASP.NET Core 中不能直接用，得换 DataProtection API
ASP.NET Core 默认不启用 Windows DPAPI，而是用 IDataProtector 抽象层。如果你在 Startup 或 Program.cs 里直接调用 ProtectedData，会发现它在 IIS Express 或 Kestrel 下可能工作，但在容器或非交互式服务中失败——因为缺少用户会话上下文。
正确做法是注册并使用框架内置的 IDataProtectionProvider：
// Program.cs（.NET 6+）
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDataProtection()
.SetApplicationName("MyApp")
.PersistKeysToFileSystem(new DirectoryInfo(@"C:\shared-keys")); // 可选：持久化密钥到文件
var app = builder.Build();
var protector = app.Services.GetService<IDataProtectionProvider>().CreateProtector("MyPurpose");
string protectedPayload = protector.Protect("sensitive-data");
string unprotected = protector.Unprotect(protectedPayload);
注意区别：
-
IDataProtectionProvider是跨平台、可配置、支持密钥轮换的抽象，底层可选 DPAPI（Windows）、证书、文件系统或 Azure Key Vault - 它不等价于
ProtectedData：默认不绑定当前 Windows 用户，而是靠应用名和目的（purpose）隔离 - 若硬要强制用 Windows DPAPI 作为底层，需显式配置：
.UseCryptographicAlgorithms(...).ProtectKeysWithDpapi()，但这仍受限于运行账户权限
加密失败时先检查三件事：权限、作用域、entropy
绝大多数 CryptographicException 都源于这三个地方，而不是算法本身出错。
排查顺序：
- 运行进程是否拥有对应作用域权限？例如，用
CurrentUser却在无桌面会话的服务中运行（如 Windows Service 登录类型为 “LocalSystem”），则无法访问用户密钥库 - 加密和解密的作用域是否完全一致？
CurrentUser和LocalMachine互不兼容 -
optionalEntropy是否为 null 或完全相同？哪怕差一个字节、null 和 new byte[0] 都不等价
调试技巧：把加密和解密逻辑放在同一个控制台程序里，用相同账户运行，禁用 entropy，确认基础流程通了再逐步加复杂度。DPAPI 本身没有日志输出，错误信息模糊，所以缩小变量范围比查文档更有效。
最常被忽略的一点：DPAPI 不是通用加密方案，它不提供完整性校验、不防重放、不解耦密钥生命周期。如果需要跨平台、可审计、可迁移的保护，应该用 AES-GCM + 密钥管理服务，而不是强行绕过 DPAPI 的限制。
