CertSetCTLContextProperty 函式 (wincrypt.h)

  • 發行項

CertSetCTLContextProperty 函式會為指定的憑證信任清單設定擴充屬性， (CTL) 內容。

語法

BOOL CertSetCTLContextProperty(
  [in] PCCTL_CONTEXT pCtlContext,
  [in] DWORD         dwPropId,
  [in] DWORD         dwFlags,
  [in] const void    *pvData
);

參數

[in] pCtlContext

CTL_CONTEXT 結構的指標。

[in] dwPropId

識別要設定的屬性。 dwPropId 的值會決定 pvData 參數的類型和內容。 目前定義的標識碼及其相關的 pvData 類型如下所示。

值 意義
CERT_ARCHIVED_PROP_ID
 pvData 的數據類型：NULL

表示在列舉期間略過憑證。 使用明確搜尋作業仍可找到具有此屬性集的憑證，例如尋找具有特定 哈希 或特定序號的憑證。
CERT_AUTO_ENROLL_PROP_ID
 pvData 的數據類型：CRYPT_DATA_BLOB的指標

使用自動註冊註冊憑證之後設定的屬性。 pvData 所指向的CRYPT_DATA_BLOB結構包含已自動註冊憑證之憑證類型的 Null 終止 Unicode 名稱。 任何後續對自動註冊的憑證呼叫都會檢查此屬性，以判斷是否已註冊憑證。
CERT_CTL_USAGE_PROP_ID
 pvData 的數據類型：CRYPT_DATA_BLOB的指標

pvData 指向包含抽象語法表示法一 (ASN.1) 編碼CTL_USAGE結構的CRYPT_DATA_BLOB結構。 此結構使用 CryptEncodeObject 編碼，並已設定X509_ENHANCED_KEY_USAGE值。
CERT_DESCRIPTION_PROP_ID
 pvData 的數據類型：CRYPT_DATA_BLOB的指標

憑證 UI 所設定並顯示的屬性。 此屬性可讓使用者描述憑證的使用。
CERT_ENHKEY_USAGE_PROP_ID
 pvData 的數據類型：CRYPT_DATA_BLOB的指標

包含 ASN.1 編碼CERT_ENHKEY_USAGE結構的CRYPT_DATA_BLOB結構。 此結構使用 CryptEncodeObject 編碼，並已設定X509_ENHANCED_KEY_USAGE值。
CERT_FRIENDLY_NAME_PROP_ID
 pvData 的數據類型：CRYPT_DATA_BLOB的指標

CRYPT_DATA_BLOB 結構會指定憑證的顯示名稱。
CERT_HASH_PROP_ID
 pvData 的數據類型：CRYPT_HASH_BLOB的指標

這個屬性是透過呼叫 CertGetCertificateContextProperty 隱含設定的。
CERT_KEY_CONTEXT_PROP_ID
 pvData 的數據類型：CERT_KEY_CONTEXT的指標

CERT_KEY_CONTEXT 結構同時包含私鑰的 HCRYPTPROV 值和密鑰規格。 如需 hCryptProv 成員和 dwFlags 設定的詳細資訊，請參閱下列CERT_KEY_PROV_HANDLE_PROP_ID。 請注意，您可以為此屬性新增更多 CERT_KEY_CONTEXT 結構成員。 如果是，則會據以調整 cbSize 成員值。 cbSize 成員必須設定為CERT_KEY_CONTEXT結構的大小
CERT_KEY_IDENTIFIER_PROP_ID
 pvData 的數據類型：CRYPT_DATA_BLOB的指標

此屬性通常是由呼叫 CertGetCertificateContextProperty 隱含設定。
CERT_KEY_PROV_HANDLE_PROP_ID
 pvData 的數據類型：HCRYPTPROV 的指標

傳遞憑證私鑰的 HCRYPTPROV 句柄。 如果CERT_KEY_CONTEXT結構存在，則會更新CERT_KEY_CONTEXT成員的 hCryptProv 成員。 如果不存在，則會使用由 CERT_KEY_PROV_INFO_PROP_ID 初始化 的 dwKeySpec 來建立它。 如果未設定CERT_STORE_NO_CRYPT_RELEASE_FLAG，則當 屬性設定為 NULL 或最終釋放CERT_CONTEXT結構時，hCryptProv 值會隱含釋放。
CERT_KEY_PROV_INFO_PROP_ID
 pvData 的數據類型：CRYPT_KEY_PROV_INFO的指標

CRYPT_KEY_PROV_INFO 結構會指定憑證的私鑰。
CERT_KEY_SPEC_PROP_ID
 pvData 的數據類型：DWORD 的指標

DWORD 值會指定私鑰。 如果結構存在，就會更新CERT_KEY_CONTEXT結構的 dwKeySpec 成員。 如果沒有，則會使用 hCryptProv 設定為零來建立它。
CERT_MD5_HASH_PROP_ID
 pvData 的數據類型：CRYPT_HASH_BLOB的指標

這個屬性是透過呼叫 CertGetCertificateContextProperty 隱含設定的。
CERT_NEXT_UPDATE_LOCATION_PROP_ID
 pvData 的數據類型：CRYPT_DATA_BLOB的指標

CRYPT_DATA_BLOB 結構包含使用 CryptEncodeObject 搭配設定X509_ALTERNATE_NAME值所編碼的 ASN.1 編碼CERT_ALT_NAME_INFO結構。 CERT_NEXT_UPDATE_LOCATION_PROP_ID目前只搭配 CCL 使用。
CERT_PVK_FILE_PROP_ID
 pvData 的數據類型：CRYPT_DATA_BLOB的指標

CRYPT_DATA_BLOB 結構會指定包含與憑證公鑰相關聯之私鑰的檔名。 在 CRYPT_DATA_BLOB 結構內， pbData 成員是 Null 終止 Unicode、寬字元字串和 cbData 成員的指標，表示字串串的長度。
CERT_SHA1_HASH_PROP_ID
 pvData 的數據類型：CRYPT_HASH_BLOB的指標

這個屬性是透過呼叫 CertGetCertificateContextProperty 隱含設定的。
CERT_SIGNATURE_HASH_PROP_ID
CRYPT_HASH_BLOB
pvData 的數據類型：CRYPT_HASH_BLOB的指標

如果簽章哈希不存在，則會使用 CryptHashToBeSigned 進行計算。 pvData 指向現有或計算的哈希。 通常，SHA 的哈希長度為 20 個字節，MD5 則為 16 個字節。
 

一般而言，只會設定CERT_NEXT_UPDATE_LOCATION_PROP_ID屬性。

用戶可以使用從 CERT_FIRST_USER_PROP_ID 到CERT_LAST_USER_PROP_ID的 DWORD 值來定義其他 dwPropId 類型。 針對所有使用者定義 dwPropId 類型， pvData 會指向編碼 CRYPT_DATA_BLOB 結構。

[in] dwFlags

CERT_STORE_NO_CRYPT_RELEASE_FLAG可以針對 CERT_KEY_PROV_HANDLE_PROP_ID 或 CERT_KEY_CONTEXT_PROP_ID dwPropId 屬性進行設定。

如果已設定CERT_SET_PROPERTY_IGNORE_PERSIST_ERROR_FLAG值，則會忽略任何提供者寫入錯誤，而且一律會設定快取內容的屬性。

如果已設定CERT_SET_PROPERTY_INHIBIT_PERSIST_FLAG，則不會保存任何屬性集。

[in] pvData

由 dwPropId 中傳遞之值所決定之數據類型的指標。

注意 針對任何 dwPropId，將 pvData 設定為 NULL 會刪除 屬性。
 

傳回值

如果函式成功，則傳回值為 TRUE。

如果函式失敗，則傳回值為 FALSE。 如需擴充錯誤資訊，請呼叫 GetLastError。 其中一個可能的錯誤碼如下。

傳回碼 Description
E_INVALIDARG
 無效的屬性識別碼。 如需詳細資訊，請參閱 CertSetCertificateContextProperty。

備註

如果屬性已經存在，則會取代其舊值。

範例

請參閱 範例 C 程式：取得和設定憑證屬性。

規格需求

需求 值
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 wincrypt.h
程式庫 Crypt32.lib
Dll Crypt32.dll

另請參閱

CertGetCTLContextProperty

CertSetCertificateContextProperty

CryptEncodeObject

擴充屬性函式