CryptSignHashA 関数 (wincrypt.h)
構文
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
次のフラグ値が定義されています。
| 値 | 意味 |
|---|---|
|
RSA プロバイダーで使用されます。 ハッシュ オブジェクト識別子 (OID) は、RSA 公開キー暗号化に配置されません。 このフラグが設定されていない場合、既定の署名のハッシュ OID は PKCS #1 の DigestInfo の定義で指定されています。 |
|
このフラグは使用されません。 |
|
ANSI X9.31 標準で指定されている RSA 署名パディング メソッドを使用します。 |
[out] pbSignature
署名データを受信するバッファーへのポインター。
メモリ割り当て目的でバッファー サイズを設定するには、このパラメーターに NULL を 指定できます。 詳細については、「不明な 長さのデータの取得」を参照してください。
[in, out] pdwSigLen
pbSignature バッファーのサイズをバイト単位で指定する DWORD 値へのポインター。 関数が戻るときに、 DWORD 値にはバッファーに格納されているバイト数が含まれます。
戻り値
関数が成功した場合、関数は TRUE を返します。
関数が失敗した場合は、 FALSE を返します。 拡張エラー情報については、 GetLastError を呼び出します。
"NTE" の前に表示されるエラー コードは、使用している特定の CSP によって生成されます。 考えられるエラー コードの一部を次に示します。
| リターン コード | 説明 |
|---|---|
|
パラメーターの 1 つは、無効なハンドルを指定します。 |
|
パラメーターの 1 つに無効な値が含まれています。 これはほとんどの場合、無効なポインターです。 |
|
pbSignature パラメーターで指定されたバッファーは、返されたデータを保持するのに十分な大きさではありません。 必要なバッファー サイズ (バイト単位) は pdwSigLenDWORD 値にあります。 |
|
hHash ハンドルは、この CSP がサポートしていないアルゴリズムを指定するか、dwKeySpec パラメーターの値が正しくありません。 |
|
dwFlags パラメーターは 0 以外です。 |
|
hHash パラメーターで指定されたハッシュ オブジェクトが無効です。 |
|
ハッシュ オブジェクトの作成時に指定された CSP コンテキストが見つかりません。 |
|
dwKeySpec で指定された秘密キーが存在しません。 |
|
操作中に 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 プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして CryptSignHash を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |