SQL Server 示例仓库:基于 VBS 安全飞地的 Always Encrypted C 控制台演示应用实战解析
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 演示家族中的"编码示范"角色,与之配套的还有四组环境级演示:
- Azure SQL Database 中的 Intel SGX 飞地演示
- Azure SQL Database 中的 VBS 飞地演示
- 使用 Host Guardian Service 进行证明的 SQL Server 演示
- 无证明的 SQL Server 演示
该控制台应用只关心"客户端驱动如何开启 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.SqlClient5.1.4:SQL Server 客户端驱动,承载 Always Encrypted 参数加密与结果解密;Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider3.0.0:让驱动能够访问 Azure Key Vault 中的列主密钥(CMK);Azure.Identity1.11.4:提供 Entra ID 令牌凭据(示例中使用AzureCliCredential);Azure.Security.KeyVault.Secrets4.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)的大致执行顺序:
- 打印冷启动提示,输出当前是否使用 AE;
- 调用
LoginToAure()登录 Azure 并获取 Azure SQL DB 的 OAuth2 令牌; - 通过
GetSQLConnectionString(useAlwaysEncrypted)构造连接串并打开SqlConnection(使用 Entra ID 令牌而非 SQL 账号密码); - 若
useAlwaysEncrypted && registerAkv4Ae,调用RegisterAkvForAe(credential)注册 AKV 提供程序(应用启动时只需执行一次); - 之后进入真正的数据库查询阶段。
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 飞地全套演示 中"编码侧"的补充。环境侧的关键事实有助于理解应用行为:
- 部署产物包括逻辑服务器、ContosoHR 数据库(已启用 VBS 飞地)、Key Vault 及 CMK 密钥、Contoso HR Web 应用;
- 数据库初始化 SQL 位于 PopulateDatabase.sql,扩展事件会话创建脚本为 CreateXESession.sql;
- 维护性 T-SQL 脚本位于 tsql-scripts:包括查看员工列表的 ListAllEmployees.sql、查看扩展事件的 QueryXevents.sql,以及演示原地加密/解密的 EncryptColumns.sql 与 DecryptColumns.sql。
八、关键要点总结
- 连接串分层:基础连接串放环境变量,飞地专属设置(
Column Encryption Setting=Enabled;Attestation Protocol=None)由代码动态追加,从而支持带/不带 AE 的同一数据源对比演示; - VBS 飞地无需证明:
Attestation Protocol=None是 VBS 场景的标配,这与 SGX/HGS 需要证明协议的场景不同; - 富查询的前提是参数化:加密列上的
LIKE、范围比较、ORDER BY、存储过程调用都必须走SqlParameter,客户端驱动负责透明加解密参数; - AKV 提供程序是必选项:列主密钥托管在 Azure Key Vault 时,必须在应用启动时注册
SqlColumnEncryptionAzureKeyVaultProvider,否则启用 AE 后所有查询都会失败; - 认证链路:示例使用 Azure CLI 凭据获取
https://database.windows.net/.default作用域令牌,通过SqlConnection.AccessToken完成 Entra ID 认证连接; - 对比验证手段:未启用 AE 时,SSN/Salary 以密文 Hex 形式(前 16 字节)出现在控制台;启用 AE 后同一查询返回明文,直观展示 Always Encrypted 的端到端透明解密效果。
该示例完整呈现了"客户端驱动视角下 Always Encrypted with VBS enclaves 的全部编码要素",是学习如何在自有应用中集成 AE 飞地加密的最小可运行范本。更进一步的环境部署、Web 应用富查询演示与原地加密演示,可继续研读 azure-sql-database-vbs 文档。