PFN_CERT_DLL_OPEN_STORE_PROV_FUNC回调函数 (wincrypt.h)

  • 项目

CertDllOpenStoreProv 函数由存储提供程序实现，用于打开存储。 此函数由 CertOpenStore 函数调用。

注意 前五个参数与 CertOpenStore 中的匹配参数相同。
 

语法

PFN_CERT_DLL_OPEN_STORE_PROV_FUNC PfnCertDllOpenStoreProvFunc;

BOOL PfnCertDllOpenStoreProvFunc(
  [in]      LPCSTR lpszStoreProvider,
  [in]      DWORD dwEncodingType,
  [in]      HCRYPTPROV_LEGACY hCryptProv,
  [in]      DWORD dwFlags,
  [in]      const void *pvPara,
  [in]      HCERTSTORE hCertStore,
  [in, out] PCERT_STORE_PROV_INFO pStoreProvInfo
)
{...}

参数

[in] lpszStoreProvider

指向包含存储提供程序类型的以 null 结尾的 ANSI 字符串的指针。

以下值表示预定义的存储类型。 存储提供程序类型确定 pvPara 参数的内容以及 dwFlags 参数高字的使用和含义。 可以使用 CryptInstallOIDFunctionAddress 或 CryptRegisterOIDFunction 函数安装或注册其他存储提供程序。 有关添加存储提供程序的详细信息，请参阅 扩展 CertOpenStore 功能。

提供程序标识符 说明 pvPara 内容
CERT_STORE_PROV_MEMORY

sz_CERT_STORE_PROV_MEMORY

 在缓存的内存中创建证书存储。 最初，不会将证书、 证书吊销列表 (CRL) 或 证书信任列表 (CTL) 加载到存储中。 通常用于创建临时存储。

不会自动保存任何添加的证书、CRL 或 CCL，或者内存存储中证书、CRL 或 CTL 的属性更改。 可以使用 CertSaveStore 将其保存到文件或内存 BLOB。

 未使用。
CERT_STORE_PROV_FILE 使用从指定的打开文件读取的证书、CRL 和 CCL 初始化存储。 此提供程序要求文件仅包含序列化存储，而不包含 PKCS #7 签名消息或单个编码证书。

文件指针必须定位在序列化存储信息的开头。 将序列化存储中的数据加载到证书存储中后，文件指针将定位在文件中可以跟随序列化存储数据的任何数据的开头。 如果在 dwFlags 中设置了CERT_FILE_STORE_COMMIT_ENABLE，则文件句柄会重复，并且存储始终作为序列化存储提交。 当存储关闭时，文件不会关闭。

 指向使用 CreateFile 打开的文件句柄的指针。
CERT_STORE_PROV_FILENAME_A 使用文件中的证书、CRL 和 CTL 初始化存储。 提供程序打开该文件，并首先尝试以序列化存储的形式读取文件，然后作为 PKCS #7 签名的消息读取，最后尝试读取单个编码证书。

dwEncodingType 参数必须包含要与消息和证书一起使用的编码类型。 如果文件包含 X.509 编码的证书，则打开操作失败， GetLastError 并返回ERROR_ACCESS_DENIED。 如果在 dwFlags 中设置了CERT_FILE_STORE_COMMIT_ENABLE标志，则传递给 CreateFile 的 dwCreationDisposition 值如下所示：

  • 如果设置了CERT_STORE_CREATE_NEW_FLAG标志， CreateFile 将使用 CREATE_NEW。
  • 如果设置了CERT_STORE_OPEN_EXISTING_FLAG标志， CreateFile 将使用 OPEN_EXISTING。
  • 对于 dwFlags 的所有其他设置， CreateFile 使用 OPEN_ALWAYS。

如果 dwFlags 包含CERT_FILE_STORE_COMMIT_ENABLE，则文件将提交为 PKCS #7 或序列化存储，具体取决于打开的文件类型。 如果文件为空，或者文件名的扩展名为 .p7c 或 .spc，则文件将提交为 PKCS #7。 否则，文件将作为序列化存储提交。

 指向以 null 结尾的 ANSI 字符串的指针，该字符串包含现有未打开文件的名称。
CERT_STORE_PROV_FILENAME

CERT_STORE_PROV_FILENAME_W

sz_CERT_STORE_PROV_FILENAME

sz_CERT_STORE_PROV_FILENAME_W

 与 CERT_STORE_PROV_FILENAME_A 相同。 指向以 null 结尾的 Unicode 字符串的指针，该字符串包含现有未打开文件的名称。
CERT_STORE_PROV_COLLECTION

sz_CERT_STORE_PROV_COLLECTION

 打开一个存储区，该存储将是其他存储的集合。 使用 CertAddStoreToCollection 和 CertRemoveStoreFromCollection 向集合添加或删除存储。 将存储添加到集合后，该存储区中的所有证书、CRL 和 CTL 都可用于搜索或枚举集合存储。

dwFlags 的高字设置为零。

 必须为 NULL。
CERT_STORE_PROV_REG 使用注册表子项中的证书、CRL 和 CCL 初始化存储。

此提供程序在 pvPara 中传递的项下打开或创建注册表子项“证书”、“CRL”和“CCL”。 提供程序未关闭输入键。 在返回之前，提供程序会打开其自己的 pvPara 中传递的密钥副本。 如果在 低字 dwFlags 中设置了CERT_STORE_READONLY_FLAG，则会使用 RegOpenKey 和 KEY_READ_ACCESS 打开注册表子项。 否则，注册表子项是使用 RegCreateKey 和 KEY_ALL_ACCESS 创建的。 对打开的存储区的内容所做的任何更改都会立即保存到注册表中。 但是，如果在 dwFlags 的低字中设置了CERT_STORE_READONLY_FLAG，则任何添加到存储内容或更改上下文属性的尝试都会导致 GetLastError 返回E_ACCESSDENIED代码的错误。

 打开的注册表项的句柄。
CERT_STORE_PROV_SYSTEM_A 使用指定系统存储中的证书、CRL 和 CTL 初始化存储。

系统存储是逻辑集合存储，由一个或多个物理存储组成。 与系统存储关联的物理存储向 CertRegisterPhysicalStore 函数注册。 打开系统存储后，所有与之关联的物理存储也会通过调用 CertOpenStore 打开，并使用 CertAddStoreToCollection 函数添加到系统存储集合。 dwFlags 的高字表示系统存储位置，通常设置为 CERT_SYSTEM_STORE_CURRENT_USER。 有关注册表位置的详细信息，请参阅本主题后面的 dwFlags 和 系统存储位置。 某些系统存储位置可以远程打开;有关详细信息，请参阅系统存储位置。

 指向包含系统存储名称（如“My”或“Root”）的以 null 结尾的 ANSI 字符串的指针。
CERT_STORE_PROV_SYSTEM

CERT_STORE_PROV_SYSTEM_W

sz_CERT_STORE_PROV_SYSTEM

sz_CERT_STORE_PROV_SYSTEM_W

 与 CERT_STORE_PROV_SYSTEM_A 相同。 指向包含系统存储名称（如“My”或“Root”）的以 null 结尾的 Unicode 字符串的指针。
CERT_STORE_PROV_SYSTEM_REGISTRY_A 使用物理注册表存储中的证书、CRL 和 CTL 初始化存储。 物理存储不是作为集合存储打开的。 枚举和搜索仅通过该物理存储中的证书、CRL 和 CTL。

dwFlags 的高字表示系统存储位置，通常设置为 CERT_SYSTEM_STORE_CURRENT_USER。 有关详细信息，请参阅本主题后面的 dwFlags 。 某些系统存储位置可以远程打开;有关详细信息，请参阅 系统存储位置。

 指向包含系统存储名称（如“My”或“Root”）的以 null 结尾的 ANSI 字符串的指针。
CERT_STORE_PROV_SYSTEM_REGISTRY

CERT_STORE_PROV_SYSTEM_REGISTRY_W

sz_CERT_STORE_PROV_SYSTEM_REGISTRY

sz_CERT_STORE_PROV_SYSTEM_REGISTRY_W

 与 CERT_STORE_PROV_SYSTEM_REGISTRY_A 相同。 指向包含系统存储名称（如“My”或“Root”）的以 null 结尾的 Unicode 字符串的指针。
CERT_STORE_PROV_PHYSICAL

CERT_STORE_PROV_PHYSICAL_W

sz_CERT_STORE_PROV_PHYSICAL

sz_CERT_STORE_PROV_PHYSICAL_W

 使用作为逻辑系统存储成员的指定物理存储区中的证书、CRL 和 CTL 初始化存储。

两个名称用干预反斜杠 (\) 分隔，例如“Root.LocalMachine”。 此处，“根”是系统存储的名称和“。LocalMachine“是物理存储的名称。 系统和物理存储名称不能包含任何反斜杠。 dwFlags 的高字表示系统存储位置，通常CERT_SYSTEM_STORE_CURRENT_USER。 有关详细信息，请参阅本主题后面的 dwFlags 。 某些物理存储位置可以远程打开。

 指向同时包含系统存储名称和物理名称的以 null 结尾的 Unicode 字符串的指针。
CERT_STORE_PROV_MSG 使用指定加密消息中的证书、CRL 和 CTL 初始化存储。 dwEncodingType 参数必须包含用于消息和证书的编码类型。 编码消息的 HCRYPTMSG 句柄，由调用 CryptMsgOpenToDecode 返回。
CERT_STORE_PROV_PKCS7

sz_CERT_STORE_PROV_PKCS7

 使用已编码的 PKCS #7 签名消息中的证书、CRL 和 CTL 初始化存储。 dwEncodingType 参数必须指定要用于消息和证书的编码类型。 指向表示编码消息 的CRYPT_DATA_BLOB 结构的指针。
CERT_STORE_PROV_SERIALIZED

sz_CERT_STORE_PROV_SERIALIZED

 使用证书、CRL 和 CTL 从包含序列化存储的内存位置初始化存储。 指向包含序列化内存 BLOB 的CRYPT_DATA_BLOB 结构的指针。
CERT_STORE_PROV_LDAP

CERT_STORE_PROV_LDAP_W

sz_CERT_STORE_PROV_LDAP

sz_CERT_STORE_PROV_LDAP_W

 使用 LDAP 查询结果中的证书、CRL 和 CTL 初始化存储。

若要对存储区执行写入操作，查询字符串必须指定没有筛选器和单个属性的 BASE 查询。

 如果 dwFlags 参数包含 CERT_LDAP_STORE_OPENED_FLAG 标志，则这是指定要使用的已建立 LDAP 会话 的CERT_LDAP_STORE_OPENED_PARA 结构的地址。

否则，这是指向包含 LDAP 查询字符串的以 null 结尾的 Unicode 字符串的指针。 有关 LDAP 查询字符串的详细信息，请参阅 LDAP 方言。
CERT_STORE_PROV_SMART_CARD

CERT_STORE_PROV_SMART_CARD_W

sz_CERT_STORE_PROV_SMART_CARD

sz_CERT_STORE_PROV_SMART_CARD_W

 当前未使用。  

[in] dwEncodingType

指定证书编码类型和消息编码类型。 仅当 CertSaveStore 函数的 dwSaveAs 参数包含CERT_STORE_SAVE_AS_PKCS7时才使用编码。 否则，不使用 dwEncodingType 参数。

此参数仅在 lpszStoreProvider 参数中指定CERT_STORE_PROV_MSG、CERT_STORE_PROV_PKCS7或CERT_STORE_PROV_FILENAME提供程序类型时适用。 对于所有其他提供程序类型，此参数未使用，应设置为零。

此参数可以是以下一个或多个值的组合。

值 含义
PKCS_7_ASN_ENCODING
65536 (0x10000)
 指定 PKCS #7 消息编码。
X509_ASN_ENCODING
1 (0x1)
 指定 X.509 证书编码。

[in] hCryptProv

加密提供程序的句柄。 此参数可以为 NULL。

[in] dwFlags

这些值由使用按位 OR 运算组合的高字值和低字值组成。

dwFlags 的低字部分控制打开的证书存储的各种一般特征。 此部分可用于所有存储提供程序类型。 dwFlags 的低字部分可以是以下值之一。

值 含义
CERT_STORE_CREATE_NEW_FLAG
 创建新的存储（如果不存在）。 如果存储已存在，则此函数应失败。

如果 CERT_STORE_OPEN_EXISTING_FLAG 和 CERT_STORE_CREATE_NEW_FLAG 均未设置，请打开现有存储或创建并打开存储（如果尚不存在）。
CERT_STORE_DEFER_CLOSE_UNTIL_LAST_FREE_FLAG
 延迟关闭存储的提供程序，直到不再使用从存储获取的所有证书、CRL 或 CTL。 释放从存储区获取的最后一个证书、CRL 或 CTL 时，存储实际上会关闭。 对这些证书、CRL 和 CTL 的属性所做的任何更改（即使在调用此函数之后）也必须持久保存。

如果未设置此标志，并且仍在使用从存储中获取的证书、CRL 或 CTL，则不得保留对这些证书、CRL 和 CTL 的属性所做的任何更改。

如果使用 CERT_CLOSE_STORE_FORCE_FLAG 调用此函数，则必须忽略 CERT_STORE_DEFER_CLOSE_UNTIL_LAST_FREE_FLAG 。

设置此标志并传递非 NULLHCRYPTPROV 值时，即使在调用此函数之后，该提供程序仍将继续使用。
CERT_STORE_DELETE_FLAG
 存储被删除，而不是打开。 对于删除成功和失败，此函数返回 FALSE 。 若要指示删除成功，请使用零调用 SetLastError 。 若要指示删除失败，请使用相应的错误代码调用 SetLastError 。
CERT_STORE_ENUM_ARCHIVED_FLAG
 通常，存储中所有证书的枚举将忽略设置了 CERT_ARCHIVED_PROP_ID 属性的任何证书。 如果设置了此标志，则存储中证书的枚举将包含存储中的所有证书，包括具有 CERT_ARCHIVED_PROP_ID 属性的证书。
CERT_STORE_MAXIMUM_ALLOWED
 使用允许的最大权限集打开存储。 如果指定了此标志，则首先使用写入访问权限打开注册表存储;如果失败，则以只读访问权限重新打开注册表存储。
CERT_STORE_NO_CRYPT_RELEASE_FLAG
 当 hCryptProv 参数为 NULL 时，不使用此标志。 仅当非 NULL CSP 句柄作为 hCryptProv 参数传递时，此标志才有效。 设置此标志可防止在证书存储关闭时自动释放非默认 CSP。
CERT_STORE_OPEN_EXISTING_FLAG
 仅打开现有存储。 如果存储不存在，函数将失败。
CERT_STORE_READONLY_FLAG
 在只读模式下打开存储区。 任何更改存储内容尝试都将导致错误。 设置此标志并使用基于注册表的存储提供程序时，将使用 RegOpenKey 和 KEY_READ_ACCESS 打开注册表子项。 否则，注册表子项是使用 RegCreateKey 和 KEY_ALL_ACCESS 创建的。
CERT_STORE_SET_LOCALIZED_NAME_FLAG
 如果支持此标志，提供程序将设置存储的 CERT_STORE_LOCALIZED_NAME_PROP_ID 属性。 可以通过调用将 dwPropID 设置为 CERT_STORE_LOCALIZED_NAME_PROP_ID 的 CertGetStoreProperty 函数来检索本地化名称。 CERT_STORE_PROV_FILENAME、CERT_STORE_PROV_SYSTEM、CERT_STORE_PROV_SYSTEM_REGISTRY 和 CERT_STORE_PROV_PHYSICAL_W 类型的提供程序支持此标志。
CERT_STORE_SHARE_CONTEXT_FLAG
 多次打开存储时，可以设置此标志，以确保通过跨存储的已打开实例重用证书、CRL 或 CTL 上下文的编码部分的内存，确保有效使用内存。
CERT_STORE_UPDATE_KEYID_FLAG
 当前User 和 LocalMachine 中存在密钥标识符Lists。 这些密钥标识符的属性与证书的属性非常类似。 如果设置了 CERT_STORE_UPDATE_KEYID_FLAG ，则对于存储位置中具有 CERT_KEY_PROV_INFO_PROP_ID 属性的每个密钥标识符，该属性将从密钥标识符属性 CERT_KEY_PROV_INFO_PROP_ID 或与该密钥标识符相关的证书 CERT_KEY_IDENTIFIER_PROP_ID 自动更新。
CERT_STORE_BACKUP_RESTORE_FLAG
 使用线程的SE_BACKUP_NAME和SE_RESTORE_NAME 权限 打开注册表或基于文件的系统存储。 如果线程不具有这些权限，则此函数必须失败并出现拒绝访问错误。
 

CERT_STORE_PROV_SYSTEM、CERT_STORE_PROV_SYSTEM_REGISTRY和CERT_STORE_PROV_PHYSICAL提供程序类型使用以下高字 dwFlags 来指定系统存储注册表位置：

CERT_SYSTEM_STORE_CURRENT_SERVICE

CERT_SYSTEM_STORE_CURRENT_USER

CERT_SYSTEM_STORE_CURRENT_USER_GROUP_POLICY

CERT_SYSTEM_STORE_LOCAL_MACHINE

CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE

CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY

CERT_SYSTEM_STORE_SERVICES

CERT_SYSTEM_STORE_USERS

默认情况下，系统存储位置相对于 HKEY_CURRENT_USER、 HKEY_LOCAL_MACHINE或 HKEY_USERS 预定义注册表项打开。 有关详细信息，请参阅 系统存储位置。

以下高字标志替代此默认行为。

值 含义
CERT_SYSTEM_STORE_RELOCATE_FLAG
 设置后， pvPara 必须包含指向 CERT_SYSTEM_STORE_RELOCATE_PARA 结构的指针，而不是字符串。 结构指示存储的名称及其在注册表中的位置。
CERT_SYSTEM_STORE_UNPROTECTED_FLAG
 默认情况下，打开 CurrentUser“根”存储时，此函数返回之前，将从缓存中删除不在受保护根列表上的任何 SystemRegistry 根。 设置此标志时，将覆盖此默认值，并返回 SystemRegistry 中的所有根，并且不会检查受保护的根列表。
 

CERT_STORE_PROV_REGISTRY提供程序使用以下高字标志。

值 含义
CERT_REGISTRY_STORE_SERIALIZED_FLAG
 CERT_STORE_PROV_REG提供程序将证书、CRL 和 CTL 保存在单个序列化存储子项中，而不是执行默认保存操作。 默认情况下，每个证书、CRL 或 CTL 都保存为相应的子项下的单独注册表子项。

此标志主要用于从组策略模板 (GPT) 下载的商店，例如 CurrentUserGroupPolicy 和 LocalMachineGroupPolicy 存储区。

设置CERT_REGISTRY_STORE_SERIALIZED_FLAG时，除非使用 CERT_STORE_CTRL_COMMIT 调用 CertCloseStore 或 CertControlStore，否则不会保留存储添加、删除或属性更改。
CERT_REGISTRY_STORE_REMOTE_FLAG
 pvPara 包含远程计算机上注册表项的句柄。 若要访问远程计算机上的注册表项，必须将远程计算机上的安全权限设置为允许访问。 有关详细信息，请参阅“备注”。
 

CERT_STORE_PROV_FILE和CERT_STORE_PROV_FILENAME提供程序类型使用以下高字标志。

值 含义
CERT_FILE_STORE_COMMIT_ENABLE
 当调用 CertCloseStore 或使用 CERT_STORE_CONTROL_COMMIT 调用 CertControlStore 时，设置此标志会将任何添加到存储区或对存储中上下文属性所做的任何更改提交到文件 存储 。

如果在 dwFlags 中同时设置了CERT_FILE_STORE_COMMIT_ENABLE和CERT_STORE_READONLY_FLAG，则 CertOpenStore 将失败并出现E_INVALIDARG。
 

CERT_STORE_PROV_LDAP提供程序类型使用以下高字标志。

值 含义
CERT_LDAP_STORE_SIGN_FLAG
 若要提供某些应用程序所需的完整性，请使用 Kerberos 身份验证协议对传入和传出 LDAP 服务器的所有 LDAP 流量进行数字签名。
CERT_LDAP_STORE_OPENED_FLAG
 使用此标志可以使用现有的 LDAP 会话。 指定此标志时， pvPara 参数是包含要使用的 LDAP 会话相关信息 的CERT_LDAP_STORE_OPENED_PARA 结构的地址。
CERT_LDAP_STORE_AREC_EXCLUSIVE_FLAG
 对 pvPara 参数中名为 的 URL 执行仅限 A 记录的 DNS 查找。 这可以防止在解析 URL 主机名时生成虚假 DNS 查询。 传递 主机名而不是 pvPara 参数的域名时使用此标志。
CERT_LDAP_STORE_UNBIND_FLAG
 将此标志与 CERT_LDAP_STORE_OPENED_FLAG 标志一起使用，使 LDAP 会话在存储关闭时取消绑定。 关闭存储时，系统将使用 ldap_unbind 函数取消绑定 LDAP 会话。

[in] pvPara

一个 32 位值，可包含此函数的其他信息。 此参数的内容取决于 lpszStoreProvider 和其他参数的值。

[in] hCertStore

内存中已打开的存储的句柄，可用于调用其他与存储相关的 API 调用，例如 CertAddSerializedElementToStore。

[in, out] pStoreProvInfo

指向要更新 的CERT_STORE_PROV_INFO 结构的指针。 数据结构已归零，并在调用之前设置 cbSize 。

CERT_STORE_PROV_INFO 结构的 cStoreProvFunc 成员是已实现且应最后设置的回调函数的计数。 设置 cStoreProvFunc 后，所有后续存储调用（如 CertAddEncodedCertificateToStore）都将调用相应的提供程序回调函数。

返回值

如果成功，则为 TRUE;否则为 FALSE。

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 wincrypt.h

另请参阅

CERT_STORE_PROV_INFO

回调函数

CertAddEncodedCertificateToStore

CertOpenStore