CryptCreateHash 関数 (wincrypt.h)

[アーティクル]
08/27/2023

大事な この API は非推奨です。新規および既存のソフトウェアでは、Cryptography Next Generation API の使用を開始する必要があります。Microsoft は、今後のリリースでこの API を削除する可能性があります。

CryptCreateHash 関数は、データストリームのハッシュを開始します。暗号化サービスプロバイダー (CSP) ハッシュオブジェクトへのハンドルを呼び出し元のアプリケーションに作成して返します。このハンドルは、セッションキーやその他のデータストリームをハッシュするために、CryptHashData と CryptHashSessionKey の後続の呼び出しで使用されます。

構文

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

パラメーター

[in] hProv

CryptAcquireContext の呼び出しによって作成された CSP へのハンドル。

[in] Algid

使用するハッシュアルゴリズムを識別する ALG_ID 値。

このパラメーターの有効な値は、使用される CSP によって異なります。既定のアルゴリズムの一覧については、「解説」を参照してください。

[in] hKey

ハッシュアルゴリズムの種類が、ハッシュベースのメッセージ認証コード (HMAC) やメッセージ認証コード (MAC) アルゴリズムなどのキー付きハッシュである場合は、このパラメーターにハッシュのキーが渡されます。キーなしのアルゴリズムの場合、このパラメーターは 0 に設定する必要があります。

キー付きアルゴリズムの場合、キーは、暗号ブロックチェーン (CBC) の暗号モードを持つブロック暗号キー (RC2 など) にする必要があります。

[in] dwFlags

次のフラグ値が定義されています。

値	意味
CRYPT_SECRETDIGEST 0x00000001	このフラグは使用されません。

[out] phHash

関数がハンドルを新しいハッシュオブジェクトにコピーするアドレス。ハッシュオブジェクトの使用が完了したら、 CryptDestroyHash 関数を呼び出してハンドルを解放します。

戻り値

関数が成功した場合、関数は TRUE を返します。

関数が失敗した場合は、 FALSE を返します。拡張エラー情報については、 GetLastError を呼び出します。

NTE の前に表示されるエラーコードは、使用している特定の CSP によって生成されます。次の表に、考えられるエラーコードの一部を示します。

リターンコード	説明
ERROR_INVALID_HANDLE	パラメーターの 1 つは、無効なハンドルを指定します。
ERROR_INVALID_PARAMETER	パラメーターの 1 つに無効な値が含まれています。これはほとんどの場合、無効なポインターです。
ERROR_NOT_ENOUGH_MEMORY	操作中にオペレーティングシステムのメモリが不足しました。
NTE_BAD_ALGID	Algid パラメーターは、この CSP がサポートしていないアルゴリズムを指定します。
NTE_BAD_FLAGS	dwFlags パラメーターは 0 以外です。
NTE_BAD_KEY	CALG_MACなどのキー付きハッシュアルゴリズムは Algid によって指定され、hKey パラメーターは 0 であるか、無効なキーハンドルを指定します。このエラーコードは、キーがストリーム暗号に対する場合、または暗号モードが CBC 以外の場合にも返されます。
NTE_NO_MEMORY	操作中に CSP のメモリが不足しました。

注釈

Microsoft サービスプロバイダーとその実装アルゴリズムの一覧については、「 Microsoft Cryptographic Service Providers」を参照してください。

実際のハッシュの計算は、 CryptHashData 関数と CryptHashSessionKey 関数を使用して行われます。これには、ハッシュオブジェクトへのハンドルが必要です。すべてのデータがハッシュオブジェクトに追加されると、次のいずれかの操作を実行できます。

ハッシュ値は、 CryptGetHashParam を使用して取得できます。
セッションキーは、 CryptDeriveKey を使用して派生できます。
ハッシュは、CryptSignHash を使用して署名できます。
署名は、CryptVerifySignature を使用して確認できます。

このリストの関数の 1 つが呼び出されると、 CryptHashData と CryptHashSessionKey を呼び出すことができません。

例

次の例は、データストリームのハッシュを開始する方法を示しています。呼び出し元のアプリケーションにハッシュオブジェクトへのハンドルを作成して返します。このハンドルは、 CryptHashData と CryptHashSessionKey の後続の呼び出しで使用され、データのストリームをハッシュします。この例の完全なコンテキストを含む例については、「 C プログラムの例: セッションキーの作成とハッシュ」を参照してください。この関数を使用する別の例については、「サンプル C プログラム: ハッシュの署名とハッシュ署名の検証」を参照してください。

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	wincrypt.h
Library	Advapi32.lib
[DLL]	Advapi32.dll