CertOpenStore 函式 (wincrypt.h)
CertOpenStore 函式會使用指定的存放區提供者類型,開啟 證書存儲。 雖然此函式可以針對大部分用途開啟證書存儲,但建議 CertOpenSystemStore 開啟最常見的證書存儲。 CertOpenStore 對於更複雜的選項和特殊案例而言是必要的。
語法
HCERTSTORE CertOpenStore(
[in] LPCSTR lpszStoreProvider,
[in] DWORD dwEncodingType,
[in] HCRYPTPROV_LEGACY hCryptProv,
[in] DWORD dwFlags,
[in] const void *pvPara
);
參數
[in] lpszStoreProvider
包含存放區提供者類型的 Null 終止 ANSI 字串指標。
下列值代表預先定義的存放區類型。 存放區提供者類型會決定 pvPara 參數的內容,以及 dwFlags 參數之高字的使用和意義。 您可以使用 CryptInstallOIDFunctionAddress 或 CryptRegisterOIDFunction 函式來安裝或註冊其他存放區提供者。 如需新增存放區提供者的詳細資訊,請參閱 擴充 CertOpenStore 功能。
價值 | 意義 |
---|---|
|
開啟將成為其他商店集合的存放區。 存放區會使用 CertAddStoreToCollection 和 CertRemoveStoreFromCollection來新增或移除集合。 將存放區新增至集合時,該存放區中的所有憑證、CRL 和 CCL 都可供搜尋或列舉集合存放區。
dwFlags 的高字設為零。 pvPara 值:pvPara 參數必須 NULL。 |
|
使用從指定的開啟檔案讀取的憑證、CRL 和 CCL,初始化存放區。 此提供者預期檔案只包含串行化存放區,而不是 PKCS #7 簽署的訊息或單一編碼憑證。
檔案指標必須位於串行化存放區資訊的開頭。 將串行化存放區中的數據載入證書存儲之後,檔案指標會放在任何可追蹤檔案中串行化存放區數據的數據開頭。 如果在 dwFlags中設定CERT_FILE_STORE_COMMIT_ENABLE,則會複製檔句柄,而且一律會將存放區認可為串行化存放區。 當存放區關閉時,檔案不會關閉。 pvPara 值:pvPara 參數必須包含 使用 createFile開啟之檔案句柄的指標。 |
|
使用檔案中的憑證、CRL 和 CCL,初始化存放區。 提供者會開啟檔案,並先嘗試將檔案讀取為串行化存放區,然後以 PKCS #7 簽署的訊息,最後以單一編碼憑證的形式讀取檔案。
dwEncodingType 參數必須包含要搭配訊息和憑證使用的編碼類型。 如果檔案包含 X.509 編碼憑證,則開啟作業會失敗,而且呼叫 getLastError 函式會傳回 ERROR_ACCESS_DENIED。
如果在
如果 dwFlags 包含 CERT_FILE_STORE_COMMIT_ENABLE,則會根據開啟的檔類型,將檔案認可為 PKCS #7 或串行化存放區。 如果檔案是空的,或檔名具有 .p7c 或 .spc 擴展名,則會將檔案認可為 PKCS #7。 否則,檔案會認可為串行化存放區。 pvPara 值:pvPara 參數必須包含 null 終止的 ANSI 字串指標,其中包含現有未開啟檔案的名稱。 |
|
與 CERT_STORE_PROV_FILENAME_A相同。
pvPara 值:pvPara 參數必須包含 null 終止 Unicode 字串的指標,其中包含現有未開啟檔案的名稱。 |
|
使用LDAP查詢結果中的憑證、CRL和 CTL,初始化存放區。
若要在存放區上執行寫入作業,查詢字串必須指定沒有篩選條件和單一屬性的BASE查詢。 pvPara 值:如果 dwFlags 參數包含 CERT_LDAP_STORE_OPENED_FLAG,請將 pvPara 設定為指定所建立 LDAP 會話使用的 CERT_LDAP_STORE_OPENED_PARA 結構位址。 否則,請將 pvPara 設定為指向包含 LDAP 查詢字串的 Null 終止 Unicode 字串。 如需 LDAP 查詢字串的詳細資訊,請參閱 LDAP 方言。 |
|
在快取的記憶體中建立證書存儲。 不會自動儲存記憶體存放區中憑證、CRL 或 CCL 的任何新增憑證、CRL 或 CCL 或屬性變更。 它們可以使用 CertSaveStore儲存至檔案或記憶體 BLOB。 pvPara 值:不使用 pvPara 參數。 |
|
使用來自指定密碼編譯訊息的憑證、CRL 和 CTL,初始化存放區。
dwEncodingType 參數必須包含訊息和憑證搭配使用的編碼類型。
pvPara 值:pvPara 參數包含編碼訊息的 HCRYPTMSG 句柄,由呼叫 cryptMsgOpenToDecode所傳回。 |
|
使用屬於邏輯系統存放區成員之指定實體存放區的憑證、CRL 和 CCL,初始化存放區。
兩個名稱會以反斜杠分隔,例如 “Root.Default”。 在這裡,“Root” 是系統存放區和 “的名稱。預設值“ 是實體存放區的名稱。 系統和實體存放區名稱不能包含任何反斜杠。 dwFlags 的高字表示系統存放區位置,通常CERT_SYSTEM_STORE_CURRENT_USER。 如需詳細資訊,請參閱本主題稍後的 dwFlags,請參閱 系統存放區位置。 某些實體存放區位置可以從遠端開啟。 pvPara 值:pvPara 參數指向包含系統存放區名稱和實體名稱的 null 終止 Unicode 字串。 |
|
使用來自編碼 PKCS #7 簽署訊息的憑證、CRL 和 CTL,初始化存放區。
dwEncodingType 參數必須指定要搭配訊息和憑證使用的編碼類型。
pvPara 值:pvPara 參數指向代表編碼訊息的 CRYPT_DATA_BLOB 結構。 |
|
使用 PKCS #12 封包的內容,初始化存放區。
如果 PKCS #12 封包受到 NULL 或空白密碼的保護,此函式將會成功開啟存放區。 從 Windows 8 和 Windows Server 2012 開始,如果內嵌在 PFX 封包中的密碼受到 Active Directory (AD) 主體的保護,而目前使用者作為該主體的成員,有權解密密碼,此函式就會成功開啟存放區。 如需詳細資訊,請參閱 pvPara 參數和 PFXExportCertStoreEx 函式的 PKCS12_PROTECT_TO_DOMAIN_SIDS 旗標。 您可以從 Windows 8 和 Windows Server 2012 開始,將 PFX 密碼保護至 AD 主體。 pvPara 值:pvPara 參數指向代表 PKCS #12 封包的 CRYPT_DATA_BLOB 結構。 |
|
使用登錄子機碼中的憑證、CRL 和 CTL,初始化存放區。
此提供者會開啟或建立登錄子機碼,憑證、CRL,以及 CTL 傳入 pvPara的密鑰底下。 提供者不會關閉輸入索引鍵。 在傳回之前,提供者會開啟傳入的金鑰複本,pvPara。 如果CERT_STORE_READONLY_FLAG是以低字 dwFlags設定,則會使用具有 KEY_READ_ACCESS 的 RegOpenKey 來開啟登錄子機碼。 否則,登錄子機碼會使用 RegCreateKey 搭配KEY_ALL_ACCESS來建立。 開啟存放區內容的任何變更都會立即保存至登錄。 不過,如果CERT_STORE_READONLY_FLAG是以低字 dwFlags設定,則任何新增至存放區內容或變更內容屬性的嘗試,都會導致傳回E_ACCESSDENIED程式代碼 GetLastError 的錯誤。 pvPara 值:pvPara 參數包含開啟登錄機碼的句柄。 |
|
從包含串行化存放區的記憶體位置,使用憑證、CRL 和 CCL 初始化存放區。
pvPara 值:pvPara pvPara 參數指向包含串行化記憶體 BLOB 的 CRYPT_DATA_BLOB 結構。 |
|
目前未使用。 |
|
使用來自指定系統存放區的憑證、CRL 和 CCL,初始化存放區。
系統存放區是邏輯集合存放區,由一或多個實體存放區組成。 與系統存放區相關聯的實體存放區會向 CertRegisterPhysicalStore 函式註冊。 開啟系統存放區之後,所有與其相關聯的實體存放區也會透過呼叫 CertOpenStore 開啟,並使用 CertAddStoreToCollection 函式新增至系統存放區集合。 pvPara 值:pvPara 參數指向包含系統存放區名稱的 null 終止 ANSI 字串,例如 “My” 或 “Root”。 |
|
與 CERT_STORE_PROV_SYSTEM_A相同。
pvPara 值:pvPara 參數指向包含系統存放區名稱的 Null 終止 Unicode 字串,例如 “My” 或 “Root”。 |
|
使用實體登錄存放區中的憑證、CRL 和 CTL,初始化存放區。 實體存放區不會以集合存放區的形式開啟。 列舉和搜尋只會經歷該實體存放區中的憑證、CRL 和 CCL。
pvPara 值:pvPara 參數指向包含系統存放區名稱的 null 終止 ANSI 字串,例如 “My” 或 “Root”。 |
|
與 CERT_STORE_PROV_SYSTEM_REGISTRY_A相同。
pvPara 值:pvPara 參數指向包含系統存放區名稱的 Null 終止 Unicode 字串,例如 “My” 或 “Root”。 |
[in] dwEncodingType
指定 憑證編碼類型, 和 訊息編碼類型。 只有當 CertSaveStore 函式的 dwSaveAs 參數包含 CERT_STORE_SAVE_AS_PKCS7時,才會使用編碼。 否則,不會使用 dwMsgAndCertEncodingType 參數。
只有在 lpszStoreProvider 參數中指定了 CERT_STORE_PROV_MSG、CERT_STORE_PROV_PKCS7或 CERT_STORE_PROV_FILENAME 提供者類型時,才適用此參數。 對於所有其他提供者類型,這個參數是未使用的,而且應該設定為零。
此參數可以是下列一或多個值的組合。
價值 | 意義 |
---|---|
|
指定 PKCS #7 訊息編碼。 |
|
指定 X.509 憑證編碼。 |
[in] hCryptProv
不使用此參數,而且應該設定為 NULL。
Windows Server 2003 和 Windows XP:密碼編譯提供者的句柄。 傳遞此參數 NULL 會導致使用適當的預設提供者。 建議使用預設提供者。 默認或指定的密碼編譯提供者會用於驗證主體憑證或CRL簽章的所有存放區函式。此參數的資料類型 HCRYPTPROV。
[in] dwFlags
這些值是由使用位OR 運算結合的高字和低字值所組成。
dwFlags 的低字部分 控制開啟 證書 存儲的各種一般特性。 此部分可與所有存放區提供者類型搭配使用。 dwFlags 的低字部分可以是下列其中一個值。
價值 | 意義 |
---|---|
|
使用線程的SE_BACKUP_NAME和SE_RESTORE_NAME 权限 來開啟登錄或檔案型系統存放區。 如果線程沒有這些許可權,此函式必須失敗,並出現拒絕存取錯誤。 |
|
如果新存放區不存在,則會建立新的存放區。 如果存放區已經存在,函式就會失敗。
如果未設定 CERT_STORE_OPEN_EXISTING_FLAG 或 CERT_STORE_CREATE_NEW_FLAG,則會在存放區存在或建立且尚未存在時開啟。 |
|
延遲關閉存放區的提供者,直到所有從存放區取得的憑證、CRL 或 CCL 都不再使用為止。 從存放區取得的最後一個憑證、CRL 或 CTL 釋出時,實際上會關閉存放區。 即使呼叫 CertCloseStore之後,對這些憑證、CRL 和 CTL 的屬性所做的任何變更,也會保存。
如果未設定此旗標,且從存放區取得的憑證、CRL 或 CCL 仍在使用中,則不會保存這些憑證、CRL 和 CTL 之屬性的任何變更。 如果使用 CERT_CLOSE_STORE_FORCE_FLAG呼叫此函式,則會忽略 CERT_STORE_DEFER_CLOSE_UNTIL_LAST_FREE_FLAG。 當設定此旗標並傳遞非NULLhCryptProv 參數值時,即使呼叫此函式之後,仍會繼續使用該提供者。 |
|
刪除存放區,而不是開啟。 此函式會針對刪除成功和失敗傳回 NULL |
|
一般而言,存放區中所有憑證的列舉都會忽略任何已設定 CERT_ARCHIVED_PROP_ID 屬性的憑證。 如果設定此旗標,存放區中的憑證列舉將會包含存放區中的所有憑證,包括具有 CERT_ARCHIVED_PROP_ID 屬性的憑證。 |
|
以允許的許可權上限集開啟存放區。 如果指定此旗標,登錄存放區會先以寫入許可權開啟,如果失敗,則會以只讀存取重新開啟。 |
|
當 hCryptProv 參數 NULL時,不會使用此旗標。 只有當非NULL CSP 句柄當做 hCryptProv 參數傳遞時,這個旗標才有效。 設定此旗標可防止關閉證書存儲時自動發行非預設 CSP。 |
|
只開啟現有的存放區。 如果存放區不存在,函式會失敗。 |
|
以唯讀模式開啟存放區。 任何變更存放區內容的嘗試都會導致錯誤。 設定此旗標並使用以登錄為基礎的存放區提供者時,會使用 RegOpenKey 搭配 KEY_READ_ACCESS來開啟登錄子機碼。 否則,登錄子機碼會使用 RegCreateKey 搭配 KEY_ALL_ACCESS來建立。 |
|
如果支援此旗標,提供者會設定存放區的 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類型提供者都支援此旗標。 |
|
多次開啟存放區時,您可以設定此旗標,藉由在已開啟的存放區實例上重複使用憑證、CRL 或 CTL 內容的編碼部分記憶體,以確保有效率的記憶體使用量。 |
|
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_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 開啟。 如需詳細資訊,請參閱 系統存放區位置。
下列高字旗標會覆寫此預設行為。
價值 | 意義 |
---|---|
|
設定時,pvPara 必須包含 CERT_SYSTEM_STORE_RELOCATE_PARA 結構的指標,而不是字串。 結構會指出存放區的名稱及其在登錄中的位置。 |
|
根據預設,當 CurrentUser “Root” 存放區開啟時,此函式傳回之前,不會在受保護根清單上的任何 SystemRegistry 根目錄從快取中刪除。 設定此旗標時,會覆寫此預設值,而且會傳回 SystemRegistry 中的所有根目錄,而且不會檢查受保護的根清單。 |
CERT_STORE_PROV_REGISTRY 提供者會使用下列高字旗標。
價值 | 意義 |
---|---|
|
pvPara 包含遠端電腦上登錄機碼的句柄。 若要存取遠端電腦上的登錄機碼,遠端電腦上的安全性許可權必須設定為允許存取。 如需詳細資訊,請參閱。 |
|
CERT_STORE_PROV_REG 提供者會將憑證、CRL 和 CTL 儲存在單一串行化存放區子機碼中,而不是執行預設儲存作業。 默認值是,每個憑證、CRL 或 CTL 都會儲存為適當子機碼下的個別登錄子機碼。
此旗標主要用於從組策略範本 (GPT) 下載的商店,例如 CurrentUserGroupPolicy 和 LocalMachineGroupPolicy 存放區。 設定 CERT_REGISTRY_STORE_SERIALIZED_FLAG 時,除非使用 CERT_STORE_CTRL_COMMIT呼叫 CertCloseStore 或 CertControlStore,否則不會保存儲存新增、刪除或屬性變更。 |
CERT_STORE_PROV_FILE 和 CERT_STORE_PROV_FILENAME 提供者類型會使用下列高字旗標。
CERT_STORE_PROV_LDAP 提供者類型會使用下列高字旗標。
價值 | 意義 |
---|---|
|
在 pvPara 參數中名為 的 URL 上執行僅限 A 記錄的 DNS 查閱。 這可防止解析 URL 主機名時產生錯誤的 DNS 查詢。 傳遞主機名而非 pvPara 參數的功能變數名稱時,請使用此旗標。 |
|
使用此旗標來使用現有的LDAP會話。 指定此旗標時,pvPara 參數是 CERT_LDAP_STORE_OPENED_PARA 結構的位址,其中包含要使用的LDAP會話相關信息。 |
|
若要提供某些應用程式所需的完整性,請使用 Kerberos 驗證通訊協定,以數位方式簽署 LDAP 伺服器的所有 LDAP 流量。 |
|
將此旗標與 CERT_LDAP_STORE_OPENED_FLAG 旗標搭配使用,會導致存放區關閉時,LDAP 會話未繫結。 當存放區關閉時,系統會使用 ldap_unbind 函式解除系結LDAP會話。 |
[in] pvPara
32 位值,可包含此函式的其他資訊。 此參數的內容取決於 lpszStoreProvider 和其他參數的值。
傳回值
如果函式成功,函式會傳回 憑證儲存的句柄,。 當您完成使用存放區時,請呼叫 CertCloseStore 函式來釋放句柄。
如果函式失敗,它會 NULL傳回 。 如需擴充錯誤資訊,請呼叫 getLastError
言論
系統存放區是由一或多個實體同層級存放區所組成的集合。 每個系統存放區都有預先定義的實體同層級存放區。 在CERT_SYSTEM_STORE_CURRENT_USER開啟系統存放區,CertOpenStore,以開啟系統存放區集合中的所有實體存放區。 每個實體存放區都會使用 CertAddStoreToCollection 函式新增至系統存放區集合。 這些實體存放區中的所有憑證、CRL 和 CCL 都可透過邏輯系統存放區集合取得。
您可以從遠端開啟下列系統存放區位置:
- CERT_SYSTEM_STORE_LOCAL_MACHINE
- CERT_SYSTEM_STORE_LOCAL_MACHINE_GROUP_POLICY
- CERT_SYSTEM_STORE_SERVICES
- CERT_SYSTEM_STORE_USERS
系統會以遠端方式開啟系統存放區位置,方法是在傳遞至 pvPara 的字串中,加上計算機名稱的存放區名稱前置詞。 遠端系統存放區名稱的範例包括:
- ComputerName\CA
- \\ComputerName\CA
- ComputerName\ServiceName\Trust
- \\ComputerName\ServiceName\信任
如需系統存放區的詳細資訊,請參閱 系統存放區位置。
如需自動移轉之存放區的詳細資訊,請參閱 證書儲存移轉。
例子
下列範例示範開啟不同存放區提供者類型的數個證書存儲。 此範例使用 CreateMyDACL 函式,建立 DACL 主題中定義,以確保使用適當的 DACL 建立開啟的檔案。 如需開啟其他存放區提供者類型的詳細資訊,請參閱 開啟證書儲存的範例 C 程式代碼。
//-------------------------------------------------------------------
// Open a system store, in this case, the My store.
HCERTSTORE hSysStore = NULL;
if(hSysStore = CertOpenStore(
CERT_STORE_PROV_SYSTEM, // The store provider type
0, // The encoding type is
// not needed
NULL, // Use the default HCRYPTPROV
CERT_SYSTEM_STORE_CURRENT_USER, // Set the store location in a
// registry location
L"MY" // The store name as a Unicode
// string
))
{
printf("The system store was created successfully.\n");
}
else
{
printf("An error occurred during creation "
"of the system store!\n");
exit(1);
}
// Other common system stores include "Root", "Trust", and "Ca".
//-------------------------------------------------------------------
// Open a memory store.
HCERTSTORE hMemStore = NULL;
if(hMemStore = CertOpenStore(
CERT_STORE_PROV_MEMORY, // The memory provider type
0, // The encoding type is not needed
NULL, // Use the default HCRYPTPROV
0, // Accept the default dwFlags
NULL // pvPara is not used
))
{
printf("The memory store was created successfully.\n");
}
else
{
printf("An error occurred during creation "
"of the memory store!\n");
exit(1);
}
//-------------------------------------------------------------------
// Open a read-only store from disk.
HANDLE hFile = NULL;
HCERTSTORE hFileStore = NULL;
LPCSTR pszFileName = "TestStor2.sto";
SECURITY_ATTRIBUTES sa; // For DACL
// Create a DACL to use when opening the file.
sa.nLength = sizeof(SECURITY_ATTRIBUTES);
sa.bInheritHandle = FALSE;
// Call function to set the DACL. The DACL is set in the
// SECURITY_ATTRIBUTES lpSecurityDescriptor member.
if (!CreateMyDACL(&sa))
{
// Error encountered; generate message and exit.
printf("Failed CreateMyDACL.\n");
exit(1);
}
// Obtain the file handle of an existing file.
if (hFile = CreateFile(
pszFileName, // The file name
GENERIC_READ|GENERIC_WRITE, // Access mode: Read from and
// write to this file
0, // Share mode
&sa, // Uses the DACL created
// previously
OPEN_ALWAYS, // How to create
FILE_ATTRIBUTE_NORMAL, // File attributes
NULL)) // Template
{
printf("The file was opened successfully.\n");
}
else
{
printf("An error occurred during opening of the file!\n");
exit(1);
}
//-------------------------------------------------------------------
// This file can contain data before the store itself.
// At this point, read and use data in the open file that precedes
// the serialized certificate store data.
// To open the certificate store, the file pointer must
// be placed at the beginning of the certificate store data.
//-------------------------------------------------------------------
// Open the store.
if(hFileStore = CertOpenStore(
CERT_STORE_PROV_FILE, // Load certificates from a file
0, // Encoding type not used
NULL, // Use the default HCRYPTPROV
CERT_STORE_READONLY_FLAG, // Read-only store
hFile // The handle for the open file
// that is the source of the
// certificates
))
{
printf("The file store was created successfully.\n");
}
else
{
printf("An error occurred during creation of the file store!\n");
exit(1);
}
//-------------------------------------------------------------------
// After processing, close the certificate stores and the file.
if(CertCloseStore(
hSysStore,
CERT_CLOSE_STORE_CHECK_FLAG))
{
printf("The system store was closed successfully.\n");
}
else
{
printf("An error occurred during closing of the "
"system store.\n");
}
if(CertCloseStore(
hMemStore,
CERT_CLOSE_STORE_CHECK_FLAG))
{
printf("The memory store was closed successfully.\n");
}
else
{
printf("An error occurred during closing of the "
"memory store.\n");
}
if(CertCloseStore(
hFileStore,
CERT_CLOSE_STORE_CHECK_FLAG))
{
printf("The file store was closed successfully.\n");
}
else
{
printf("An error occurred during closing of the file store.\n");
}
if(CloseHandle(hFile))
{
printf("The file was closed successfully.\n");
}
else
{
printf("An error occurred during closing of the file.\n");
}
要求
要求 | 價值 |
---|---|
最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
支援的最低伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
目標平臺 | 窗戶 |
標頭 | wincrypt.h |
連結庫 | Crypt32.lib |
DLL | Crypt32.dll |