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

NCryptCreatePersistedKeyFn

コールバック

シグネチャ

HRESULT NCryptCreatePersistedKeyFn(
    NCRYPT_PROV_HANDLE hProvider,
    NCRYPT_KEY_HANDLE* phKey,
    LPWSTR pszAlgId,
    LPWSTR pszKeyName,
    DWORD dwLegacyKeySpec,
    DWORD dwFlags
);

パラメーター

フィールド型説明
hProviderNCRYPT_PROV_HANDLEキーを作成するキーストレージプロバイダーのハンドルです。このハンドルは NCryptOpenStorageProvider 関数を使用して取得します。
phKeyNCRYPT_KEY_HANDLE*キーのハンドルを受け取る NCRYPT_KEY_HANDLE 変数のアドレスです。このハンドルの使用を終えたら、NCryptFreeObject 関数に渡して解放してください。ディスク上のキーファイルを削除するには、ハンドルを NCryptDeleteKey 関数に渡します。この場合もハンドルは解放されます。したがってアプリケーションは、ハンドルを NCryptFreeObject または NCryptDeleteKey のいずれかに渡すことはできますが、両方に渡すことはできません。
pszAlgIdLPWSTRキーを作成する暗号アルゴリズムの識別子を格納した、NULL で終わる Unicode 文字列へのポインターです。標準の CNG Algorithm Identifiers のいずれか、または登録された他のアルゴリズムの識別子を指定できます。
pszKeyNameLPWSTRキーの名前を格納した、NULL で終わる Unicode 文字列へのポインターです。このパラメーターが NULL の場合、この関数は永続化されない一時的な (エフェメラル) キーを作成します。
dwLegacyKeySpecDWORD

キーの種類を指定するレガシーの識別子です。次のいずれかの値を指定できます。

値 意味
AT_KEYEXCHANGE キーはキー交換キーです。
AT_SIGNATURE キーは署名キーです。
0 キーは上記のいずれの種類でもありません。
dwFlagsDWORD

この関数の動作を変更するフラグのセットです。0、または次の値の 1 つ以上の組み合わせを指定できます。

値 意味
NCRYPT_MACHINE_KEY_FLAG キーはローカルコンピューターに適用されます。このフラグが指定されていない場合、キーは現在のユーザーに適用されます。
NCRYPT_OVERWRITE_KEY_FLAG 指定した名前のキーがコンテナーに既に存在する場合、既存のキーが上書きされます。このフラグが指定されておらず、指定した名前のキーが既に存在する場合、この関数は NTE_EXISTS を返します。
NCRYPT_REQUIRE_VBS_FLAG キーを仮想化ベースのセキュリティ (VBS) で保護する必要があることを示します。既定では、再起動サイクルをまたいで保持される、ディスクに格納されたクロスブート永続キーが作成されます。

VBS が利用できない場合、操作は失敗します。(*「解説」を参照)
NCRYPT_PREFER_VBS_FLAG キーを仮想化ベースのセキュリティ (VBS) で保護することが望ましいことを示します。既定では、再起動サイクルをまたいで保持される、ディスクに格納されたクロスブート永続キーが作成されます。

VBS が利用できない場合、ソフトウェアで分離されたキーが生成されます。(*「解説」を参照)
NCRYPT_USE_PER_BOOT_KEY_FLAG NCRYPT_REQUIRE_VBS_FLAG または NCRYPT_PREFER_VBS_FLAG と併用できる追加のフラグです。仮想化ベースのセキュリティ (VBS) に対して、ディスクに格納されるがブートサイクルをまたいで再利用できないブート単位のキーでクライアントキーを保護するよう指示します。(*「解説」を参照)

公式ドキュメント

NCryptCreatePersistedKey 関数は、新しいキーを作成し、指定されたキーストレージプロバイダーに格納します。この関数でキーを作成した後、NCryptSetProperty 関数でそのプロパティを設定できます。ただし、NCryptFinalizeKey 関数が呼び出されるまで、そのキーは使用できません。

戻り値

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

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

戻り値 説明
ERROR_SUCCESS 関数は成功しました。
NTE_BAD_FLAGS dwFlags パラメーターに有効でない値が含まれています。
NTE_EXISTS 指定した名前のキーが既に存在し、NCRYPT_OVERWRITE_KEY_FLAG が指定されていませんでした。
NTE_INVALID_HANDLE hProvider パラメーターが有効ではありません。
NTE_INVALID_PARAMETER 1 つ以上のパラメーターが有効ではありません。
NTE_NO_MEMORY メモリの割り当てに失敗しました。
NTE_VBS_UNAVAILABLE VBS が利用できません。

解説(Remarks)

重要

VBS フラグに関する情報は、商用リリース前に大幅に変更される可能性があるプレリリース製品に関するものです。Microsoft は、ここで提供される情報について、明示または黙示を問わず、いかなる保証も行いません。

RSA キーペアを作成する場合、キーを確定する際に NCryptFinalizeKey 関数へ NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG フラグを渡すことで、CryptoAPI から使用できるようにキーをレガシーストレージにも格納できます。

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

VBS キーに関する追加のハードウェア要件

適切な OS がコンピューターにインストールされていても、VBS を使用してキーを生成および保護するには、次の追加のハードウェア要件を満たす必要があります。

ハードウェア要件の詳細については、次を参照してください。

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