Win32 API 日本語リファレンス
ホーム › Security.Cryptography › NCryptSignHashFn

NCryptSignHashFn

コールバック

シグネチャ

HRESULT NCryptSignHashFn(
    NCRYPT_PROV_HANDLE hProvider,
    NCRYPT_KEY_HANDLE hKey,
    void* pPaddingInfo,
    BYTE* pbHashValue,
    DWORD cbHashValue,
    BYTE* pbSignature,
    DWORD cbSignature,
    DWORD* pcbResult,
    DWORD dwFlags
);

パラメーター

フィールド型説明
hProviderNCRYPT_PROV_HANDLE
hKeyNCRYPT_KEY_HANDLE署名の生成に使用する秘密キーのハンドルです。
pPaddingInfovoid*パディング情報を格納した構造体へのポインターです。このパラメーターが指す構造体の実際の型は、dwFlags パラメーターの値によって異なります。dwFlags が 0 の場合、このパラメーターは NULL でなければなりません。
pbHashValueBYTE*

署名対象の入力を格納したバッファーへのポインターです。このバッファーのサイズは cbHashValue パラメーターで指定します。

注: pbHashValue というパラメーター名は、この API の経緯上の理由により実態と一致していません。

多くの署名アルゴリズム (DSA、RSA、ECDSA、HashML-DSA など) では、署名ルーチンはハッシュ関数の結果を入力として受け取るように定義されています。これらのアルゴリズムでは、署名対象の元のメッセージをまずハッシュ化し、得られたハッシュ値 (事前ハッシュ) を pbHashValue バッファーで渡します。

一方、署名アルゴリズムによっては (pure ML-DSA、pure SLH-DSA など)、任意のサイズのデータを直接署名できます。これらのアルゴリズムでは、pbHashValue バッファーに署名対象の入力を格納します。この入力の構成方法は署名者と検証者の間で合意する必要がありますが、事前ハッシュを用いる必要はありません。非常に大きなバッファーを直接署名すると、相互運用性を損なうおそれがあります。

いずれの場合も、pbHashValue バッファーは署名対象の入力を表します。

cbHashValueDWORDpbHashValue バッファーのサイズ (バイト単位) です。
pbSignatureBYTE*

この関数が生成した署名を受け取るバッファーのアドレスです。このバッファーのサイズは cbSignature パラメーターで指定します。

このパラメーターが NULL の場合、この関数は署名に必要なサイズを計算し、pcbResult パラメーターが指す場所にそのサイズを返します。

cbSignatureDWORDpbSignature バッファーのサイズ (バイト単位) です。pbSignature パラメーターが NULL の場合、このパラメーターは無視されます。
pcbResultDWORD*

pbSignature バッファーにコピーされたバイト数を受け取る DWORD 変数へのポインターです。

pbSignature が NULL の場合は、署名に必要なサイズ (バイト単位) を受け取ります。

dwFlagsDWORD

この関数の動作を変更するフラグのセットです。指定できるフラグは、hKey パラメーターで指定したキーの種類によって異なります。

0、または次の値の 1 つ以上の組み合わせを指定できます。

値 意味
NCRYPT_PAD_PKCS1_FLAG RSA PKCS1 パディング方式を使用します。pPaddingInfo パラメーターは BCRYPT_PKCS1_PADDING_INFO 構造体へのポインターです。
NCRYPT_PAD_PSS_FLAG RSA 確率的署名方式 (PSS) のパディング方式を使用します。pPaddingInfo パラメーターは BCRYPT_PSS_PADDING_INFO 構造体へのポインターです。
NCRYPT_PAD_PQDSA_FLAG ML-DSA または SLH-DSA 向けの PQ パディング方式を使用します。pPaddingInfo パラメーターは BCRYPT_PQDSA_PADDING_INFO 構造体へのポインターです。

注: 事前ハッシュを用いる ML-DSA のバリアントを使用する場合は、このフラグを設定する必要があります。
NCRYPT_SILENT_FLAG キーストレージプロバイダー (KSP) がユーザーインターフェイスを表示しないよう要求します。プロバイダーが動作するために UI の表示を必要とする場合、呼び出しは失敗し、KSP は最後のエラーとして NTE_SILENT_CONTEXT エラーコードを設定します。

公式ドキュメント

NCryptSignHash 関数は、署名対象のデータに対する署名を作成します。

戻り値

関数の成功または失敗を示すステータスコードを返します。

返される可能性のあるコードには、次のものがあります (これらに限りません)。

戻り値 説明
ERROR_SUCCESS 関数は成功しました。
NTE_BAD_ALGID hKey パラメーターが表すキーは署名をサポートしていません。
NTE_BAD_FLAGS dwFlags パラメーターに無効な値が含まれています。
NTE_INVALID_HANDLE hKey パラメーターが無効です。
NTE_INVALID_PARAMETER 1 つ以上のパラメーターが無効です。
NTE_NO_MEMORY メモリの割り当てに失敗しました。

解説(Remarks)

サービスは、この関数を StartService 関数 から呼び出してはいけません。サービスが StartService 関数からこの関数を呼び出すと、デッドロックが発生し、サービスが応答しなくなる可能性があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)