SQL Server 示例仓库:基于 VBS 安全飞地的 Always Encrypted C 控制台演示应用实战解析

原创2026-09-24 20:12:151,685 阅读
文章标签:示例工程数据库教程后端

SQL Server 示例仓库:基于 VBS 安全飞地的 Always Encrypted C# 控制台演示应用实战解析

本文基于 sql-server-samples 仓库中 samples/features/security/always-encrypted-with-secure-enclaves 目录下的 C# 客户端示例应用,完整讲解如何通过一个控制台程序演示 Always Encrypted(AE)与 VBS(Virtualization Based Security)安全飞地在 Azure SQL Database 中的编码实践。读完本文,你将掌握:如何配置 ConnectContosoHR 环境变量、如何在代码中动态追加飞地相关连接串设置、如何通过三个布尔开关演示"明文数据/密文数据/启用飞地后富查询"的完整对比流程,以及 Entra ID(Azure AD)认证、Azure Key Vault 列主密钥提供程序注册等底层实现细节。

一、示例定位:用代码演示 VBS 飞地下的 Always Encrypted 编码

该示例应用位于 sample-application,是一个 C# 客户端控制台应用,用于演示 Always Encrypted with VBS enclaves 的客户端编码层面内容,其配套数据库是 ContosoHR。它属于整个 always-encrypted-with-secure-enclaves 演示家族中的"编码示范"角色,与之配套的还有四组环境级演示:

该控制台应用只关心"客户端驱动如何开启 AE、如何加密参数、如何解密结果"这一编码链路,因此它是理解 AE 客户端编程模型的最佳切入点。

二、应用结构与运行前提

2.1 目录结构

samples/features/security/always-encrypted-with-secure-enclaves/sample-application/
├── AlwaysEncryptedConsole/
│   ├── AlwaysEncryptedConsole.csproj   # 工程文件与依赖包
│   ├── AlwaysEncryptedConsole.sln      # 解决方案文件
│   ├── DumpData.cs                     # 结果集输出(密文以 Hex 形式转储)
│   ├── Program.cs                      # 主流程与四步演示逻辑
│   └── Utils.cs                        # 连接串构建、Azure 登录、AKV 提供程序注册
├── AlwaysEncryptedConsole.sln
├── LICENSE.txt
└── README.md

核心代码由三个 partial class Program 文件组成(Program.cs、DumpData.cs、Utils.cs),每个文件各司其职。

2.2 工程目标框架与依赖

查看 AlwaysEncryptedConsole.csproj,该项目:

  • 目标框架为 net8.0-windows10.0.22621.0(Windows 平台控制台应用,启用 ImplicitUsings 与 Nullable);
  • 核心依赖包:
    • Microsoft.Data.SqlClient 5.1.4:SQL Server 客户端驱动,承载 Always Encrypted 参数加密与结果解密;
    • Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider 3.0.0:让驱动能够访问 Azure Key Vault 中的列主密钥(CMK);
    • Azure.Identity 1.11.4:提供 Entra ID 令牌凭据(示例中使用 AzureCliCredential);
    • Azure.Security.KeyVault.Secrets 4.5.0:Key Vault 访问辅助。

运行该示例前,需要有一个已部署好的 ContosoHR 数据库(VBS 飞地已启用,SSN/Salary 列已加密),其完整部署方式见 azure-sql-database-vbs 演示环境(通过 setup.ps1 与 azuredeploy.bicep 一键部署逻辑服务器、ContosoHR 数据库、Key Vault 与 CMK 密钥)。

三、环境变量 ConnectContosoHR:把连接串与代码解耦

示例要求先设置一个名为 ConnectContosoHR 的环境变量,其值就是指向 Azure SQL Database 实例的连接字符串,例如:

Server=tcp:XXXXXXXserver.database.windows.net;Database=ContosoHR;

在 Windows 的 Command Prompt 中可用 setx 命令持久化设置:

setx ConnectContosoHR=`Server=tcp:XXXXXXXserver.database.windows.net;Database=ContosoHR;`

关键设计约束(README 明确强调):不要在这个环境变量里写入任何飞地专属设置(如 Column Encryption Setting、Attestation Protocol),这些设置由代码在运行时按需追加。这样做的目的是:同一份基础连接串既可用于"未启用 AE"的对比演示,也可用于"启用 AE"的演示,二者切换只靠代码内标志位,不需要改环境变量。

代码侧的读取逻辑位于 Utils.cs 的 GetSQLConnectionString(bool useAE = true):

const string _EnvVar = "ConnectContosoHR";

string? sqlConn =
    Environment.GetEnvironmentVariable(_EnvVar, EnvironmentVariableTarget.Process)
    ?? throw new ArgumentException($"Missing environment variable, {_EnvVar}");

// 仅在启用 AE 时追加飞地相关设置
if (useAE)
    sqlConn += ";Column Encryption Setting=Enabled;Attestation Protocol=None;";

return sqlConn;
  • 若环境变量缺失,程序会直接抛出 ArgumentException 并提示缺少 ConnectContosoHR;
  • 当 useAE == true 时,追加两个关键字:Column Encryption Setting=Enabled 让客户端驱动开启 Always Encrypted(透明加密查询参数、解密查询结果),Attestation Protocol=None 指定不进行飞地证明——这正是 VBS 飞地当前的特性:VBS 飞地暂不支持证明(attestation),这一点在 azure-sql-database-vbs README 的 Demo 1 中也有同样的说明。

从源码结构看,这里刻意用字符串拼接而非 SqlConnectionStringBuilder,是为了让读者一眼看清"哪些设置是 AE 引入的";代码注释也提示可以改用 SqlConnectionStringBuilder 实现同等效果。

四、核心标志位与四步演示流程

Program.cs 顶部定义了三个布尔开关,注释中给出了完整的四步演示剧本(Demo Steps):

// Demo step 2 置为 true
bool useAlwaysEncrypted = true;

// Demo step 3 置为 true
bool testWithParams = true;

// Demo step 4 置为 true
bool registerAkv4Ae = true;

四步演示的完整链路如下:

步骤 开关组合 预期行为
Step 1 全部保持 false(README 要求"all these flags should be false") 不使用 AE,查询结果中 SSN 与 Salary 显示为密文 Hex 转储
Step 2 useAlwaysEncrypted = true 启用 AE 但未注册 AKV 提供程序,运行因缺少密钥存储提供程序而失败
Step 3 testWithParams = true 使用参数化查询,但因未注册 AKV(registerAkv4Ae 仍为 false)继续失败
Step 4 registerAkv4Ae = true 注册 AKV 列加密密钥存储提供程序,全部查询成功:第一条查询较慢(涉及初始认证、授权与列元数据加载),第二条明显更快

主流程(Program.cs)的大致执行顺序:

  1. 打印冷启动提示,输出当前是否使用 AE;
  2. 调用 LoginToAure() 登录 Azure 并获取 Azure SQL DB 的 OAuth2 令牌;
  3. 通过 GetSQLConnectionString(useAlwaysEncrypted) 构造连接串并打开 SqlConnection(使用 Entra ID 令牌而非 SQL 账号密码);
  4. 若 useAlwaysEncrypted && registerAkv4Ae,调用 RegisterAkvForAe(credential) 注册 AKV 提供程序(应用启动时只需执行一次);
  5. 之后进入真正的数据库查询阶段。

4.1 未启用 AE:观察密文

当 useAlwaysEncrypted == false 时,程序执行:

SELECT Top 10 SSN, Salary, LastName, FirstName FROM Employees

由于数据列在数据库侧已加密,客户端驱动又未开启 AE,驱动不会做解密,因此返回的 SSN/Salary 是原始密文字节。

4.2 启用 AE 后的三类富查询

当 useAlwaysEncrypted == true 时,程序依次展示三类只能在飞地帮助下完成的查询(这是 VBS 飞地"富查询"能力的编码体现):

查询一:密文列上的直接比较(需配合参数开关)

SELECT count(*) FROM Employees where [Salary] > 50000

该查询由 testWithParams == false 分支触发,直接对加密列做范围比较——在无飞地的传统 Always Encrypted 下这是不允许的,飞地使密文上的比较运算成为可能。

查询二:参数化富查询(LIKE 模式匹配 + 范围比较 + 排序)

string query2 =
    "SELECT [SSN], [Salary], [LastName], [FirstName] " +
    "FROM Employees WHERE [Salary] > @MinSalary AND [SSN] LIKE @SSN " +
    "ORDER by [Salary] DESC";

sqlCommand = new(query2, conn);

// 必须使用参数(MUST use parameters)
SqlParameter minSalaryParam = new("@MinSalary", SqlDbType.Money) { Value = 50_000 };
sqlCommand.Parameters.Add(minSalaryParam);

SqlParameter ssnParam = new("@SSN", SqlDbType.Char) { Value = "6%" };
sqlCommand.Parameters.Add(ssnParam);

注意代码注释特别强调 "MUST use parameters":对加密列的任何运算都必须参数化,驱动负责把参数值在客户端透明加密后再发送给服务器,服务器在飞地内解密并执行计算,这样 DBA 即使捕获到参数也无法看到明文。

查询三:调用加密列上的存储过程

string query3 = "EXEC usp_GetSalary @MinSalary = @MinSalaryRange, @MaxSalary = @MaxSalaryRange";
// @MinSalaryRange = 40_000(SqlDbType.Money)
// @MaxSalaryRange = 42_000(SqlDbType.Money)

同样以参数形式传入存储过程入参,演示"富查询 + 存储过程"的组合场景。

4.3 查询计时与结果输出

每个查询都经由 Program.cs 的 DoQuery(SqlCommand) 执行:使用 Stopwatch 记录网络往返 + 查询的总耗时,然后调用 DumpData 输出结果。注释提醒:该耗时包含网络延迟,会高于纯查询时间;且第一条查询因组件加载、认证、授权等冷启动开销明显更慢——这正是 Step 4 中"第一条慢、第二条快"现象的来源。

五、密文结果的 Hex 转储输出

DumpData.cs 实现了结果集渲染:

  • 先输出各列名作为表头;
  • 逐行读取数据;
  • 关键逻辑:若某列的类型是 byte[](即密文),则调用 ByteArrayToHexString 把它转成十六进制字符串并截取前 16 字节显示,使密文以可读的 Hex 形态呈现在控制台;
  • 空值显示为 ?。

配套的 Utils.cs 中 ByteArrayToHexString 用 StringBuilder 将每个字节格式化为两位十六进制({0:x2}),并支持通过 maxLen 参数截断输出(默认 16)。这就是 README 所述"When useAlwaysEncrypted==false, you will see a hex dump of the ciphertext fields, SSN and Salary"的实现细节。

六、Entra ID 认证与 AKV 列主密钥提供程序注册

6.1 用 Azure CLI 凭据换取数据库令牌

Utils.cs 的 LoginToAure():

var credential = new AzureCliCredential();
var oauth2TokenSql = credential.GetToken(
        new TokenRequestContext(
            ["https://database.windows.net/.default"])).Token;
return (credential, oauth2TokenSql);
  • 使用 AzureCliCredential 从本机 Azure CLI 登录态获取凭据——因此运行前必须安装 Azure CLI 并完成 az login,否则会报错;
  • 令牌作用域为 https://database.windows.net/.default(Azure SQL Database 的默认资源范围);
  • 代码注释说明该处可替换为托管标识(Managed Identity)、服务主体等其他凭据来源;
  • 该令牌被赋给 SqlConnection.AccessToken 属性,实现 Entra ID 认证连接(代码注释明确:使用 Entra ID 而非 Windows 或 SQL 认证)。

6.2 注册 Azure Key Vault 提供程序

VBS 飞地场景下,列加密密钥(CEK)由 Key Vault 中的列主密钥(CMK)保护。客户端要解密 CEK,就必须让驱动认识 AKV 这个密钥存储。这正是 Utils.cs 的 RegisterAkvForAe 所做的:

var akvAeProvider = new SqlColumnEncryptionAzureKeyVaultProvider(cred);
SqlConnection.RegisterColumnEncryptionKeyStoreProviders(
    customProviders: new Dictionary<string, SqlColumnEncryptionKeyStoreProvider>() {
        { SqlColumnEncryptionAzureKeyVaultProvider.ProviderName, akvAeProvider }
    });
  • 先基于同一个 Entra ID 凭据构建 SqlColumnEncryptionAzureKeyVaultProvider;
  • 再通过 SqlConnection.RegisterColumnEncryptionKeyStoreProviders 全局注册该提供程序;
  • 该方法只需在应用启动时调用一次(代码注释:do these once per app on startup)。

这条调用链解释了 Step 2/3 为何失败:AE 已开启、参数已就绪,但驱动缺少可用的列加密密钥存储提供程序,无法从 Key Vault 取出 CMK 解密 CEK;Step 4 注册后整条链路才闭合。这与配套环境中的对象一致:数据库元数据中的列主密钥对象 CMK1(引用 Key Vault 中的 CMK 密钥,且 Enclave Computations = Allowed)与列加密密钥对象 CEK1,见 azure-sql-database-vbs README Demo 1。

七、与完整 VBS 演示环境的衔接

该控制台应用是对 VBS 飞地全套演示 中"编码侧"的补充。环境侧的关键事实有助于理解应用行为:

八、关键要点总结

  1. 连接串分层:基础连接串放环境变量,飞地专属设置(Column Encryption Setting=Enabled;Attestation Protocol=None)由代码动态追加,从而支持带/不带 AE 的同一数据源对比演示;
  2. VBS 飞地无需证明:Attestation Protocol=None 是 VBS 场景的标配,这与 SGX/HGS 需要证明协议的场景不同;
  3. 富查询的前提是参数化:加密列上的 LIKE、范围比较、ORDER BY、存储过程调用都必须走 SqlParameter,客户端驱动负责透明加解密参数;
  4. AKV 提供程序是必选项:列主密钥托管在 Azure Key Vault 时,必须在应用启动时注册 SqlColumnEncryptionAzureKeyVaultProvider,否则启用 AE 后所有查询都会失败;
  5. 认证链路:示例使用 Azure CLI 凭据获取 https://database.windows.net/.default 作用域令牌,通过 SqlConnection.AccessToken 完成 Entra ID 认证连接;
  6. 对比验证手段:未启用 AE 时,SSN/Salary 以密文 Hex 形式(前 16 字节)出现在控制台;启用 AE 后同一查询返回明文,直观展示 Always Encrypted 的端到端透明解密效果。

该示例完整呈现了"客户端驱动视角下 Always Encrypted with VBS enclaves 的全部编码要素",是学习如何在自有应用中集成 AE 飞地加密的最小可运行范本。更进一步的环境部署、Web 应用富查询演示与原地加密演示,可继续研读 azure-sql-database-vbs 文档。

登录后查看全文
sql-server-samples