CryptVerifySignatureW 函式（wincrypt.h）

發行項
11/20/2024

重要此 API 已被取代。新的和現有的軟體應該開始使用密碼編譯新一代 API。 Microsoft在未來版本中可能會移除此 API。

CryptVerifySignature 函式會驗證哈希對象的簽章。

呼叫此函式之前，必須先呼叫 cryptCreateHash，才能建立哈希物件的句柄。 CryptHashData 或 CryptHashSessionKey 接著會用來將數據或會話密鑰新增至哈希物件。

CryptVerifySignature 完成之後，只能使用 hHash 句柄呼叫 cryptDestroyHash。

語法

BOOL CryptVerifySignatureW(
  [in] HCRYPTHASH hHash,
  [in] const BYTE *pbSignature,
  [in] DWORD      dwSigLen,
  [in] HCRYPTKEY  hPubKey,
  [in] LPCWSTR    szDescription,
  [in] DWORD      dwFlags
);

參數

[in] hHash

要驗證之哈希物件的句柄。

[in] pbSignature

要驗證之簽章數據的位址。

[in] dwSigLen

pbSignature 中的位元元組數目 簽章數據。

[in] hPubKey

公鑰的句柄用來驗證簽章。此公鑰必須屬於原本用來建立數位簽名金鑰組。

[in] szDescription

此參數不應再使用，而且必須設定為 NULL，以防止安全性弱點。不過，在 Microsoft 基底密碼編譯提供者中仍支援回溯相容性。

[in] dwFlags

定義下列旗標值。

價值	意義
CRYPT_NOHASHOID 0x00000001	此旗標會與 RSA 提供者搭配使用。驗證簽章時，預期不會存在或檢查哈希對象標識碼（OID）。如果未設定此旗標，則會驗證預設簽章中的哈希 OID，如 PKCS 中 DigestInfo 的定義中所指定 #7。
CRYPT_TYPE2_FORMAT 0x00000002	未使用這個旗標。
CRYPT_X931_FORMAT 0x00000004	針對符合 RSA （rDSA）的 FIPS 186-2 相容版本，請使用 X.931 支援。

傳回值

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

如果函式失敗，則傳回值 FALSE。如需擴充錯誤資訊，請呼叫 getLastError。

“NTE” 開頭的錯誤碼是由您使用的特定 CSP 所產生。以下是一些可能的錯誤碼。

傳回碼	描述
ERROR_INVALID_HANDLE	其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER	其中一個參數包含無效的值。這通常是無效的指標。
NTE_BAD_FLAGS	dwFlags 參數為非零。
NTE_BAD_HASH	hHash 參數指定的哈希對象無效。
NTE_BAD_KEY	hPubKey 參數不包含有效公鑰的句柄。
NTE_BAD_SIGNATURE	簽章無效。這可能是因為數據本身已變更、描述字串不相符，或 hPubKey指定錯誤的公鑰。如果哈希或簽章演算法不符合用來建立簽章的演算法，也可以傳回此錯誤。
NTE_BAD_UID	找不到建立哈希物件時所指定的密碼編譯服務提供者（CSP）內容。
NTE_NO_MEMORY	CSP 在作業期間記憶體不足。

言論

CryptVerifySignature 函式會完成哈希。在此呼叫之後，無法再將數據新增至哈希。 CryptHashData 或 CryptHashSessionKey 的其他呼叫失敗。使用哈希完成應用程式之後，應該呼叫 cryptDestroyHash，以終結哈希物件。

如果您使用 .NET Framework API 產生簽章，並嘗試使用 CryptVerifySignature 函式來驗證簽章，則函式將會失敗，GetLastError 會傳回 NTE_BAD_SIGNATURE。這是因為原生 Win32 API 與 .NET Framework API 之間的位元組順序不同。

原生密碼編譯 API 會使用小端位元組順序，而 .NET Framework API 則使用 big-endian 位元組順序。如果您要驗證使用 .NET Framework API 所產生的簽章，您必須先交換簽章位元組的順序，才能呼叫 CryptVerifySignature 函式來驗證簽章。

例子

如需使用 CryptVerifySignature 函式的範例，請參閱範例 C 程式：簽署哈希並驗證哈希簽章。

注意

wincrypt.h 標頭會根據 UNICODE 預處理器常數的定義，將 CryptVerifySignature 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	wincrypt.h
連結庫	Advapi32.lib
DLL	Advapi32.dll