NCryptCreateProtectionDescriptor 函数 (ncryptprotect.h)

NCryptCreateProtectionDescriptor 函数检索保护描述符对象的句柄。

语法

SECURITY_STATUS NCryptCreateProtectionDescriptor(
  [in]  LPCWSTR                  pwszDescriptorString,
  [in]  DWORD                    dwFlags,
  [out] NCRYPT_DESCRIPTOR_HANDLE *phDescriptor
);

参数

[in] pwszDescriptorString

以 Null 结尾的 Unicode 字符串，其中包含保护描述符规则字符串或规则的已注册显示名称。

如果指定显示名称，并且希望此函数在注册表中查找关联的保护描述符规则字符串，则必须将 dwFlags 参数设置为 NCRYPT_NAMED_DESCRIPTOR_FLAG。

[in] dwFlags

指定 pwszDescriptorString 中的字符串是否表示保护描述符的显示名称的标志，如果是，则指定函数应在注册表中搜索关联的保护规则字符串的位置。 可以设置以下值组合：

• 若要指示 在 pwszDescriptorString 参数中设置的值是完整的保护描述符规则字符串而不是显示名称，请将 dwFlags 参数设置为零 (0) 。
• 若要指示字符串是显示名称，并且它连同其关联的描述符规则字符串一起保存在 HKEY_LOCAL_MACHINE 注册表配置单元中，则按位或 NCRYPT_NAMED_DESCRIPTOR_FLAG 值和 NCRYPT_MACHINE_KEY_FLAG 值。
• 若要指示字符串是显示名称并保存该字符串及其关联的描述符字符串规则，请在 HKEY_CURRENT_USER 注册表配置单元中仅设置 NCRYPT_NAMED_DESCRIPTOR_FLAG 值。 也就是说，没有用于指定当前用户注册表配置单元的唯一标志。

注意 若要将描述符规则与显示名称相关联并同时保存在注册表中，请调用 NCryptRegisterProtectionDescriptorName 函数。

 

[out] phDescriptor

指向保护描述符对象句柄的指针。

返回值

返回指示函数成功或失败的状态代码。 可能的返回代码包括但不限于以下内容。

返回代码	说明
ERROR_SUCCESS	函数成功。
NTE_INVALID_PARAMETER	phDescriptor 参数不能为 NULL。 pwszDescriptorString 参数不能为 NULL，也不能是空的刺。
NTE_BAD_FLAGS	dwFlags 参数必须 NCRYPT_MACHINE_KEY_FLAG 或 NCRYPT_NAMED_DESCRIPTOR_FLAG。
NTE_NO_MEMORY	无法分配内存来检索已注册的保护描述符字符串。
NTE_NOT_FOUND	找不到 pwszDescriptorString 参数中指定的保护描述符名称。

注解

此函数创建的保护描述符对象是一个内部数据结构，其中包含有关描述符的信息。 不能直接使用它。 但是，应用程序可以在以下函数中使用返回的句柄：

• NCryptCloseProtectionDescriptor
• NCryptGetProtectionDescriptorInfo
• NCryptProtectSecret
• NCryptProtectSecret
• NCryptUnprotectSecret
• NCryptStreamOpenToProtect

以下示例显示了保护描述符规则字符串：

• “SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812”
• “SDDL=O：S-1-5-5-0-290724G：SYD： (A;;CCDC;;;S-1-5-5-0-290724) (A;;直流;;;WD) ”
• “LOCAL=user”
• “LOCAL=machine”
• “WEBCREDENTIALS=MyPasswordName”
• “WEBCREDENTIALS=MyPasswordName，myweb.com”

可以使用 NCryptRegisterProtectionDescriptorName 函数将显示名称与规则字符串相关联，并将这两者都保存在注册表中。

要求

要求	值
最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
目标平台	Windows
标头	ncryptprotect.h
Library	NCrypt.lib
DLL	NCrypt.dll

另请参阅

CNG DPAPI 函数