CryptSignHashA 函式（wincrypt.h）

發行項
11/20/2024

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

CryptSignHash 函式會簽署數據。由於所有簽章演算法都是非對稱的，因此速度很慢，CryptoAPI 不允許直接簽署數據。相反地，數據會先哈希，並使用 cryptSignHash 來簽署哈希。

語法

BOOL CryptSignHashA(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwKeySpec,
  [in]      LPCSTR     szDescription,
  [in]      DWORD      dwFlags,
  [out]     BYTE       *pbSignature,
  [in, out] DWORD      *pdwSigLen
);

參數

[in] hHash

要簽署之哈希物件的句柄。

[in] dwKeySpec

識別要從提供者容器使用的私鑰。它可以是AT_KEYEXCHANGE或AT_SIGNATURE。

最初建立金鑰組時，會指定所使用的簽章演算法。

Microsoft基底密碼編譯提供者支援的唯一簽章演算法是 RSA 公鑰演演算法。

[in] szDescription

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

[in] dwFlags

定義下列旗標值。

價值	意義
CRYPT_NOHASHOID 0x00000001	與 RSA 提供者搭配使用。哈希物件識別碼（OID）不會放在 RSA 公鑰加密中。如果未設定此旗標，默認簽章中的哈希 OID 會如同 PKCS 中 DigestInfo 的定義中所指定 #1。
CRYPT_TYPE2_FORMAT 0x00000002	未使用這個旗標。
CRYPT_X931_FORMAT 0x00000004	使用 ANSI X9.31 標準中指定的 RSA 簽章填補方法。

[out] pbSignature

接收簽章數據的緩衝區指標。

這個參數可以 NULL，以針對記憶體配置目的設定緩衝區大小。如需詳細資訊，請參閱擷取未知長度的數據。

[in, out] pdwSigLen

DWORD 值的指標，指定 pbSignature 緩衝區的大小，以位元組為單位。當函式傳回時，DWORD 值會包含儲存在緩衝區中的位元組數目。

注意處理緩衝區中傳回的數據時，應用程式必須使用傳回的數據的實際大小。實際大小可能稍微小於輸入上所指定緩衝區的大小。（在輸入時，緩衝區大小通常會指定夠大，以確保最大可能的輸出數據符合緩衝區。在輸出時，此參數所指向的變數會更新，以反映複製到緩衝區的數據實際大小。

傳回值

如果函式成功，函式會傳回 true 。

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

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

傳回碼	描述
ERROR_INVALID_HANDLE	其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER	其中一個參數包含無效的值。這通常是無效的指標。
ERROR_MORE_DATA	pbSignature 參數所指定的緩衝區不夠大，無法保存傳回的數據。所需的緩衝區大小，以位元組為單位，位於 pdwSigLenDWORD 值。
NTE_BAD_ALGID	hHash 句柄會指定此 CSP 不支援的演算法，或 dwKeySpec 參數的值不正確。
NTE_BAD_FLAGS	dwFlags 參數為非零。
NTE_BAD_HASH	hHash 參數指定的哈希對象無效。
NTE_BAD_UID	找不到建立哈希物件時指定的 CSP 內容。
NTE_NO_KEY	dwKeySpec 指定的私鑰不存在。
NTE_NO_MEMORY	CSP 在作業期間記憶體不足。

言論

呼叫此函式之前，必須呼叫 CryptCreateHash 函式，才能取得哈希物件的句柄。 CryptHashData 或 CryptHashSessionKey 函式接著會用來將數據或會話索引鍵新增至哈希物件。 CryptSignHash 函式會完成哈希。

雖然 DSS CSP 支援使用 MD5 和 SHA 哈希演算法進行哈希處理，但 DSS CSP 僅支援簽署 SHA 哈希。

呼叫此函式之後，就無法再將數據新增至哈希。 CryptHashData 或 CryptHashSessionKey 的其他呼叫失敗。

應用程式使用哈希完成之後，呼叫 CryptDestroyHash 函式來終結哈希物件。

根據預設，Microsoft RSA 提供者會針對簽章使用 PKCS #1 填補方法。簽章的 DigestInfo 元素中的哈希 OID 會自動設定為與哈希對象相關聯的演算法 OID。使用 CRYPT_NOHASHOID 旗標會導致簽章中省略此 OID。

有時候，在其他地方產生的哈希值必須經過簽署。這可以使用下列作業順序來完成：

使用 cryptCreateHash 建立哈希物件。
在 cryptSetHashParam中使用 dwParam 參數的 HP_HASHVAL 值，在哈希物件中設定哈希值。
使用 cryptSignHash 簽署哈希值， 並取得數位簽名區塊。
使用 CryptDestroyHash終結哈希物件。

例子

下列範例示範先哈希要簽署的數據，然後使用 cryptSignHash 函式簽署哈希來簽署數據。

//-------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV hProv;
BYTE *pbBuffer= (BYTE *)"Sample data that is to be signed.";
DWORD dwBufferLen = strlen((char *)pbBuffer)+1;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// This code assumes that a cryptographic context handle, hProv,
// and a hash handle, hHash, are available.
// For code needed to acquire the context, see "Example C Program: 
// Signing a Hash and Verifying the Hash Signature."

//--------------------------------------------------------------------
// Compute the cryptographic hash of the buffer.

if(CryptHashData(
   hHash, 
   pbBuffer, 
   dwBufferLen, 
   0)) 
{
     printf("The data buffer has been hashed.\n");
}
else
{
     printf("Error during CryptHashData.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Determine the size of the signature and allocate memory.

dwSigLen= 0;
if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   NULL, 
   &dwSigLen)) 
{
     printf("Signature length %d found.\n",dwSigLen);
}
else
{
     printf("Error during CryptSignHash\n");
     exit(1);
}
//--------------------------------------------------------------------
// Allocate memory for the signature buffer.

if(pbSignature = (BYTE *)malloc(dwSigLen))
{
     printf("Memory allocated for the signature.\n");
}
else
{
     printf("Out of memory\n");
     exit(1);
}
//--------------------------------------------------------------------
// Sign the hash object.

if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   pbSignature, 
   &dwSigLen)) 
{
     printf("pbSignature is the hash signature.\n");
}
else
{
     printf("Error during CryptSignHash.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Destroy the hash object.

if(hHash) 
  CryptDestroyHash(hHash);

如需包含此程式代碼內容的完整範例，請參閱範例 C 程式：簽署哈希並驗證哈希簽章。

注意

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

要求

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