NCryptCreatePersistedKey 関数 (ncrypt.h)

  • [アーティクル]

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

構文

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

パラメーター

[in] hProvider

キーを作成するキー ストレージ プロバイダーのハンドル。 このハンドルは、 NCryptOpenStorageProvider 関数を使用して取得されます。

[out] phKey

キーのハンドルを受け取る NCRYPT_KEY_HANDLE 変数のアドレス。 このハンドルの使用が完了したら、 それを NCryptFreeObject 関数に渡して解放します。 ディスク上のキー ファイルを削除するには、 ハンドルを NCryptDeleteKey 関数に渡します。 これにより、ハンドルも解放されます。 そのため、アプリケーションはハンドルを NCryptFreeObject または NCryptDeleteKey に渡すことができますが、両方に渡すことはできません。

[in] pszAlgId

キーを作成する暗号化アルゴリズムの識別子を含む null で終わる Unicode 文字列へのポインター。 これには、標準の CNG アルゴリズム識別子 の 1 つ、または別の登録済みアルゴリズムの識別子を指定できます。

[in, optional] pszKeyName

キーの名前を含む null で終わる Unicode 文字列へのポインター。 このパラメーターが NULL の場合、この関数は永続化されないエフェメラル キーを作成します。

[in] dwLegacyKeySpec

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

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

[in] dwFlags

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

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

VBS が使用できない場合、操作は失敗します。 (*解説を参照)
NCRYPT_PREFER_VBS_FLAG キーを仮想化ベースのセキュリティ (VBS) で保護する必要があることを示します。

VBS が使用できない場合、操作によってソフトウェア分離キーが生成されます。 (*解説を参照)

戻り値

関数の成功または失敗を示す状態コードを返します。

可能なリターン コードには、次のものが含まれますが、これらに限定されません。

リターン コード 説明
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 は使用できません。

注釈

重要

VBS フラグに関する情報は、市販される前に大幅に変更されるプレリリース製品に関連しています。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。

RSA キー ペアを作成する場合は、キーが終了したときに NCryptFinalizeKey 関数に NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG フラグを渡すことで CryptoAPI で使用できるように、キーをレガシ ストレージに格納することもできます。

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

VBS キーの追加ハードウェア要件

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

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

  • VBS には、Hyper-V (Windows ハイパーバイザー)、64 ビット アーキテクチャ、IOMMU のサポートなど、実行する必要があるハードウェア要件がいくつかあります。 VBS ハードウェア要件の完全な一覧については、 こちらを参照してください。
  • 安全性の高いデバイスの要件については、 こちらを参照してください。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー ncrypt.h
Library Ncrypt.lib
[DLL] Ncrypt.dll

こちらもご覧ください

NCryptDeleteKey

NCryptFinalizeKey