sp_describe_parameter_encryption (Transact-SQL)

适用于:SQL Server 2016 (13.x) 及更高版本 Azure SQL 数据库 Azure SQL 托管实例

分析指定的 Transact-SQL 语句及其参数,以确定哪些参数对应于使用 Always Encrypted 功能保护的数据库列。 返回对应于加密列的参数的加密元数据。

语法

sp_describe_parameter_encryption
    [ @tsql = ] N'tsql'
    [ , [ @params = ] N'@parameter_name data_type [ , ... n ]' ]
[ ; ]

参数

[ @tsql = ] 'tsql'

一个或多个 Transact-SQL 语句。 @tsql可能是 nvarchar(nnvarchar(max)。

[ @params = ] N'@parameter_name data_type [ ,... n ]'

@params为@tsql的参数提供声明字符串,这类似于 sp_executesql。 参数可以是 nvarchar(nnvarchar(max)。

一个字符串,其中包含 Transact-SQL_batch中嵌入的所有参数的定义。 字符串必须是 Unicode 常量或 Unicode 变量。 每个参数定义由参数名称和数据类型组成。 n 是表示附加参数定义的占位符。 n 是表示附加参数定义的占位符。 语句中指定的每个参数都必须在@params定义。 如果语句中的 Transact-SQL 语句或批处理不包含参数, 则不需要@paramsNULL 是此参数的默认值。

返回值

0 指示成功。 其他任何内容都表示失败。

结果集

sp_describe_parameter_encryption 返回两个结果集:

  • 描述为数据库列配置的加密密钥的结果集,指定的 Transact-SQL 语句的参数对应。

  • 描述应如何加密特定参数的结果集。 此结果集引用第一个结果集中所述的键。

第一个结果集的每一行描述了一对密钥:一个加密列加密密钥及其相应的列主密钥(CMK)。

列名称 数据类型 描述
column_encryption_key_ordinal int 结果集中行的 ID。
database_id int 数据库 ID。
column_encryption_key_id int 列加密密钥 ID。

注意:此 ID 表示sys.column_encryption_keys目录视图中的行。
column_encryption_key_version int 保留供将来使用。 目前,始终包含 1
column_encryption_key_metadata_version binary(8) 一个时间戳,表示列加密密钥的创建时间。
column_encryption_key_encrypted_value varbinary(4000) 列加密密钥的加密值。
column_master_key_store_provider_name sysname 包含 CMK 的密钥存储的提供程序的名称,该 CMK 用于生成列加密密钥的加密值。
column_master_key_path nvarchar(4000) CMK 的密钥路径,用于生成列加密密钥的加密值。
column_encryption_key_encryption_algorithm_name sysname 用于生成列加密密钥加密值的加密算法的名称。

第二个结果集的每一行都包含一个参数的加密元数据。

列名称 数据类型 描述
parameter_ordinal int 结果集中行的 ID。
parameter_name sysname @params参数中指定的参数之一的名称。
column_encryption_algorithm tinyint 指示为参数所对应的列配置的加密算法的代码。 当前支持的值适用于 2 AEAD_AES_256_CBC_HMAC_SHA_256
column_encryption_type tinyint 指示为列配置的加密类型的代码,参数对应于。 支持的值包括:

0 - 纯文本(列未加密)
1 - 确定性加密
2 - 随机加密。
column_encryption_key_ordinal int 第一个结果集中行的代码。 引用的行描述为列配置的列加密密钥,参数对应于。
column_encryption_normalization_rule_version tinyint 类型规范化算法的版本号。

注解

支持 Always Encrypted 的 SQL Server 客户端驱动程序会自动调用 sp_describe_parameter_encryption 以检索应用程序颁发的参数化查询的加密元数据。 然后,驱动程序使用加密元数据来加密与使用 Always Encrypted 保护的数据库列对应的参数值。 它将应用程序提交的纯文本参数值替换为加密参数值,然后再将查询发送到数据库引擎。

权限

需要数据库中的 VIEW ANY COLUMN ENCRYPTION KEY DEFINITIONVIEW ANY COLUMN MASTER KEY DEFINITION 权限。

示例

以下示例截断用于 ENCRYPTED_VALUE显示目的的值。

CREATE COLUMN MASTER KEY [CMK1]
WITH (
    KEY_STORE_PROVIDER_NAME = N'MSSQL_CERTIFICATE_STORE',
    KEY_PATH = N'CurrentUser/my/A66BB0F6DD70BDFF02B62D0F87E340288E6F9305'
);
GO

CREATE COLUMN ENCRYPTION KEY [CEK1]
WITH VALUES (
    COLUMN_MASTER_KEY = [CMK1],
    ALGORITHM = 'RSA_OAEP',
    ENCRYPTED_VALUE = 0x016E00000163007500720072<...> -- truncated in this example
);
GO

CREATE TABLE t1 (
    c1 INT ENCRYPTED WITH (
        COLUMN_ENCRYPTION_KEY = [CEK1],
        ENCRYPTION_TYPE = Randomized,
        ALGORITHM = 'AEAD_AES_256_CBC_HMAC_SHA_256'
        ) NULL,
);

EXEC sp_describe_parameter_encryption
    N'INSERT INTO t1 VALUES(@c1)',
    N'@c1 INT';

下面是第一个结果集:

column_encryption_key_ordinal 1
database_id 5
column_encryption_key_id 1
column_encryption_key_version 1
column_encryption_key_metadata_version 0x99EDA60083A50000
column_encryption_key_encrypted_value 0x016E00000163007500720072<...>
column_master_key_store_provider_name MSSQL_CERTIFICATE_STORE
column_master_key_path CurrentUser/my/A66BB0F6DD70BDFF02B62D0F87E340288E6F9305
column_encryption_key_encryption_algorithm_name RSA_OAEP

下面是第二个结果集:

parameter_ordinal 1
parameter_name @c1
column_encryption_algorithm 1
column_encryption_type 1
column_encryption_key_ordinal 1
column_encryption_normalization_rule_version 1