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 功能。

提供者識別項 Description pvPara 內容
CERT_STORE_PROV_MEMORY

sz_CERT_STORE_PROV_MEMORY

 在快取的記憶體中建立證書存儲。 憑證、 證書吊銷清單 (CRL) ，或 憑證信任清單 (CTL) 一開始會載入至存放區。 通常用來建立暫存存放區。

不會自動儲存記憶體存放區中憑證、CRL 或 CTL 屬性的任何新增憑證、CRL 或 CCL 或變更。 它們可以使用 CertSaveStore 儲存至檔案或記憶體 BLOB。

 未使用。
CERT_STORE_PROV_FILE 使用從指定的開啟檔案讀取的憑證、CRL 和 CTL，初始化存放區。 此提供者預期檔案只包含串行化存放區，而不是 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 和 CTL，初始化存放區。

此提供者會在 pvPara 中傳遞的機碼下開啟或建立登錄子機碼 Certificates、CRL 和 CTL。 提供者不會關閉輸入索引鍵。 在傳回之前，提供者會開啟它自己在 pvPara 中傳遞的密鑰複本。 如果CERT_STORE_READONLY_FLAG設定為 dwFlags 的低字組，則會使用具有 KEY_READ_ACCESS 的 RegOpenKey 來開啟登錄子機碼。 否則，會使用 RegCreateKey 搭配 KEY_ALL_ACCESS 來建立登錄子機碼。 開啟存放區內容的任何變更都會立即保存到登錄。 不過，如果CERT_STORE_READONLY_FLAG是在 dwFlags 的低字組中設定，則任何嘗試新增至存放區的內容或變更內容的 屬性會導致 GetLastError 傳回E_ACCESSDENIED程式代碼時發生錯誤。

 開啟登錄機碼的句柄。
CERT_STORE_PROV_SYSTEM_A 使用來自指定系統存放區的憑證、CRL 和 CTL，初始化存放區。

系統存放區是由一或多個實體存放區組成的邏輯集合存放區。 與系統存放區相關聯的實體存放區會向 CertRegisterPhysicalStore 函式註冊。 開啟系統存放區之後，所有與其相關聯的實體存放區也會透過呼叫 CertOpenStore 開啟，並使用 CertAddStoreToCollection 函式新增至系統存放區集合。 dwFlags 的高字表示系統存放區位置，通常設定為 CERT_SYSTEM_STORE_CURRENT_USER。 如需登錄位置的詳細資訊，請參閱本主題稍後的 dwFlags 和 系統存放區位置。 某些系統存放區位置可以從遠端開啟;如需詳細資訊，請參閱系統存放區位置。

 以 Null 結尾的 ANSI 字串指標，其中包含系統存放區名稱，例如 “My” 或 “Root”。
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相同。 Null 終止 Unicode 字串的指標，其中包含系統存放區名稱，例如 “My” 或 “Root”。
CERT_STORE_PROV_SYSTEM_REGISTRY_A 使用實體登錄存放區中的憑證、CRL 和 CTL 初始化存放區。 實體存放區不會開啟為集合存放區。 列舉和搜尋只會經歷該實體存放區中的憑證、CRL 和 CTL。

dwFlags 的高字表示系統存放區位置，通常設定為 CERT_SYSTEM_STORE_CURRENT_USER。 如需詳細資訊，請參閱本主題稍後 的 dwFlags 。 某些系統存放區位置可以從遠端開啟;如需詳細資訊，請參閱 系統存放區位置。

 以 Null 結尾的 ANSI 字串指標，其中包含系統存放區名稱，例如 “My” 或 “Root”。
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相同。 Null 終止 Unicode 字串的指標，其中包含系統存放區名稱，例如 “My” 或 “Root”。
CERT_STORE_PROV_PHYSICAL

CERT_STORE_PROV_PHYSICAL_W

sz_CERT_STORE_PROV_PHYSICAL

sz_CERT_STORE_PROV_PHYSICAL_W

 從屬於邏輯系統存放區成員的指定實體存放區，使用憑證、CRL 和 CCL 初始化存放區。

兩個名稱會以交錯反斜杠 (\) 分隔，例如 “Root.LocalMachine”。 在這裡，“Root” 是系統存放區和 “的名稱。LocalMachine 是實體存放區的名稱。 系統和實體存放區名稱不能包含任何反斜杠。 dwFlags 的高字表示系統存放區位置，通常CERT_SYSTEM_STORE_CURRENT_USER。 如需詳細資訊，請參閱本主題稍後 的 dwFlags 。 某些實體存放區位置可以從遠端開啟。

 Null 終止 Unicode 字串的指標，其中包含系統存放區名稱和實體名稱。
CERT_STORE_PROV_MSG 使用來自指定密碼編譯訊息的憑證、CRL 和 CCL，初始化存放區。 dwEncodingType 參數必須包含用於訊息和憑證的編碼類型。 編碼訊息的 HCRYPTMSG 句柄，由呼叫 CryptMsgOpenToDecode 傳回。
CERT_STORE_PROV_PKCS7

sz_CERT_STORE_PROV_PKCS7

 使用已編碼 PKCS #7 簽署訊息中的憑證、CRL 和 CCL，初始化存放區。 dwEncodingType 參數必須指定用於訊息和憑證的編碼類型。 表示編碼訊息之 CRYPT_DATA_BLOB 結構的指標。
CERT_STORE_PROV_SERIALIZED

sz_CERT_STORE_PROV_SERIALIZED

 從包含串行化存放區的記憶體位置，使用憑證、CRL 和 CCL 初始化存放區。 包含串行化記憶體 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和 CCL，初始化存放區。

若要在存放區上執行寫入作業，查詢字串必須指定沒有篩選條件和單一屬性的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 或 CCL 都不再使用為止。 當從存放區取得的最後一個憑證、CRL 或 CTL 釋放時，就會實際關閉存放區。 即使呼叫此函式之後，對這些憑證、CRL 和 CCL 的屬性所做的任何變更都必須保存。

如果未設定此旗標，且從存放區取得的憑證、CRL 或 CCL 仍在使用中，則這些憑證、CRL 和 CCL 的任何變更都不得保存。

如果使用 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
 在唯讀模式開啟存放區。 任何嘗試變更存放區的內容都會造成錯誤。 設定此旗標並使用以登錄為基礎的存放區提供者時，會使用 具有 KEY_READ_ACCESS的 RegOpenKey 來開啟 登錄子機碼。 否則，會使用 RegCreateKey 搭配 KEY_ALL_ACCESS 來建立 登錄子機碼。
CERT_STORE_SET_LOCALIZED_NAME_FLAG
 如果支援此旗標，提供者會設定存放區的 CERT_STORE_LOCALIZED_NAME_PROP_ID 屬性。 呼叫 CertGetStoreProperty 函式，並將 dwPropID 設定為 CERT_STORE_LOCALIZED_NAME_PROP_ID，即可擷取本地化的名稱。 此旗標支援類型 提供者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
 清單 的金鑰標識碼存在於 CurrentUser 和 LocalMachine 內。 這些金鑰標識碼的屬性非常類似憑證的屬性。 如果 已設定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 “Root” 存放區開啟時，此函式傳回之前，不會在受保護的根清單上的任何 SystemRegistry 根目錄都會從快取中刪除。 設定此旗標時，會覆寫此預設值，並傳回 SystemRegistry 中的所有根目錄，而且不會檢查受保護的根清單。
 

CERT_STORE_PROV_REGISTRY提供者會使用下列高字旗標。

值 意義
CERT_REGISTRY_STORE_SERIALIZED_FLAG
 CERT_STORE_PROV_REG提供者會將憑證、CRL 和 CCL 儲存在單一串行化的存放區子機碼中，而不是執行預設儲存作業。 預設值是每個憑證、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-Record 的 DNS 查閱。 這可防止解析 URL 主機名時產生 False 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