CryptSignHashA 関数 (wincrypt.h)

  • [アーティクル]
大事な この API は非推奨です。 新規および既存のソフトウェアでは 、Cryptography Next Generation 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 Base Cryptographic Provider がサポートする唯一の署名アルゴリズムは、RSA 公開キー アルゴリズムです。

[in] szDescription

このパラメーターは使用されなくなり、セキュリティの脆弱性を防ぐために NULL に設定する必要があります。 ただし、Microsoft Base Cryptographic Provider では下位互換性のために引き続きサポートされています。

[in] dwFlags

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

値 意味
CRYPT_NOHASHOID
0x00000001
 RSA プロバイダーで使用されます。 ハッシュ オブジェクト識別子 (OID) は、RSA 公開キー暗号化に配置されません。 このフラグが設定されていない場合、既定の署名のハッシュ OID は PKCS #1 の DigestInfo の定義で指定されています。
CRYPT_TYPE2_FORMAT
0x00000002
 このフラグは使用されません。
CRYPT_X931_FORMAT
0x00000004
 ANSI X9.31 標準で指定されている RSA 署名パディング メソッドを使用します。

[out] pbSignature

署名データを受信するバッファーへのポインター。

メモリ割り当て目的でバッファー サイズを設定するには、このパラメーターに NULL を 指定できます。 詳細については、「不明な 長さのデータの取得」を参照してください。

[in, out] pdwSigLen

pbSignature バッファーのサイズをバイト単位で指定する DWORD 値へのポインター。 関数が戻るときに、 DWORD 値にはバッファーに格納されているバイト数が含まれます。

メモ バッファーで返されるデータを処理する場合、アプリケーションは返されるデータの実際のサイズを使用する必要があります。 実際のサイズは、入力時に指定されたバッファーのサイズよりも若干小さくすることができます。 (入力では、バッファー サイズは通常、可能な最大の出力データがバッファーに収まるように十分な大きさで指定されます)。出力時に、このパラメーターが指す変数は、バッファーにコピーされたデータの実際のサイズを反映するように更新されます。
 

戻り値

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

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

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

リターン コード 説明
ERROR_INVALID_HANDLE
 パラメーターの 1 つは、無効なハンドルを指定します。
ERROR_INVALID_PARAMETER
 パラメーターの 1 つに無効な値が含まれています。 これはほとんどの場合、無効なポインターです。
ERROR_MORE_DATA
 pbSignature パラメーターで指定されたバッファーは、返されたデータを保持するのに十分な大きさではありません。 必要なバッファー サイズ (バイト単位) は pdwSigLenDWORD 値にあります。
NTE_BAD_ALGID
 hHash ハンドルは、この CSP がサポートしていないアルゴリズムを指定するか、dwKeySpec パラメーターの値が正しくありません。
NTE_BAD_FLAGS
 dwFlags パラメーターは 0 以外です。
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 が署名から省略されます。

場合によっては、他の場所で生成されたハッシュ値に署名する必要があります。 これは、次の一連の操作を使用して行うことができます。

  1. CryptCreateHash を使用してハッシュ オブジェクトを作成します。
  2. CryptSetHashParam の dwParam パラメーターのHP_HASHVAL値を使用して、ハッシュ オブジェクトにハッシュ値を設定します。
  3. CryptSignHash を使用してハッシュ値に署名し、デジタル署名ブロックを取得します。
  4. 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 プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして CryptSignHash を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

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

こちらもご覧ください

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

ハッシュ関数とデジタル署名関数