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

BCryptDuplicateKeyFn

コールバック

シグネチャ

NTSTATUS BCryptDuplicateKeyFn(
    BCRYPT_KEY_HANDLE hKey,
    BCRYPT_KEY_HANDLE* phNewKey,
    BYTE* pbKeyObject,
    DWORD cbKeyObject,
    DWORD dwFlags
);

パラメーター

フィールド型説明
hKeyBCRYPT_KEY_HANDLE複製するキーのハンドルです。これは対称キーのハンドルである必要があります。
phNewKeyBCRYPT_KEY_HANDLE*複製されたキーのハンドルを受け取る BCRYPT_KEY_HANDLE 変数へのポインターです。このハンドルは、BCryptEncrypt など、キーを必要とする以降の関数で使用します。このハンドルが不要になったら、BCryptDestroyKey 関数に渡して解放する必要があります。
pbKeyObjectBYTE*

複製されたキーオブジェクトを受け取るバッファーへの 省略可能な ポインターです。cbKeyObject パラメーターには、このバッファーのサイズを指定します。必要なバッファーのサイズは、BCryptGetProperty 関数を呼び出して BCRYPT_OBJECT_LENGTH プロパティを取得することで求められます。これにより、指定したアルゴリズムにおけるキーオブジェクトのサイズが得られます。

このメモリを解放できるのは、phNewKey のキーハンドルが破棄された後だけです。

このパラメーターの値が NULL で、かつ cbKeyObject パラメーターの値が 0 の場合、複製されたキーオブジェクト用のメモリはこの関数によって割り当てられ、BCryptDestroyKey によって解放されます。Windows 7: このメモリ管理機能は Windows 7 以降で利用できます。

cbKeyObjectDWORD

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

このパラメーターの値が 0 で、かつ pbKeyObject パラメーターの値が NULL の場合、複製されたキーオブジェクト用のメモリはこの関数によって割り当てられ、BCryptDestroyKey によって解放されます。Windows 7: このメモリ管理機能は Windows 7 以降で利用できます。

dwFlagsDWORDこの関数の動作を変更するフラグのセットです。現在定義されているフラグはないため、このパラメーターには 0 を指定します。

公式ドキュメント

BCryptDuplicateKey 関数は、対称キーの複製を作成します。

戻り値

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

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

戻り値 説明
STATUS_SUCCESS
 関数は成功しました。
STATUS_BUFFER_TOO_SMALL
 cbKeyObject パラメーターで指定されたキーオブジェクトのサイズが、キーオブジェクトを格納するのに十分ではありません。
STATUS_INVALID_HANDLE
 hKey パラメーターのキーハンドルが無効です。複製するキーが対称キーでない場合にも、この値が返されます。
STATUS_INVALID_PARAMETER
 1 つ以上のパラメーターが無効です。

解説(Remarks)

サポートされているアルゴリズムプロバイダーを使用する場合、BCryptDuplicateKey はユーザーモードとカーネルモードのどちらからでも呼び出せます。カーネルモードの呼び出し元は、PASSIVE_LEVEL IRQL と DISPATCH_LEVEL IRQL のいずれでも実行できます。現在の IRQL レベルが DISPATCH_LEVEL の場合、hKey パラメーターに指定するハンドルは、BCRYPT_PROV_DISPATCH フラグを指定して開かれたプロバイダーが返したアルゴリズムハンドルから派生したものである必要があり、BCryptDuplicateKey 関数に渡すポインターはすべて、ページング不可の (またはロックされた) メモリを参照している必要があります。

この関数をカーネルモードで呼び出すには、Driver Development Kit (DDK) に含まれる Cng.lib を使用します。Windows Server 2008 および Windows Vista: この関数をカーネルモードで呼び出すには、Ksecdd.lib を使用します。

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