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 アルゴリズム識別子 のいずれか、または別の登録済みアルゴリズムの識別子を指定できます。

[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 が使用できない場合、操作によってソフトウェア分離キーが生成されます。 (*「備考」を参照)
NCRYPT_USE_PER_BOOT_KEY_FLAG NCRYPT_REQUIRE_VBS_FLAGまたはNCRYPT_PREFER_VBS_FLAGと共に使用できる追加のフラグ。 仮想化ベースのセキュリティ (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 キー ペアを作成する場合は、キーをレガシ ストレージに格納して、キーの最終処理時に NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG フラグを NCryptFinalizeKey 関数に渡すことで 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

NCryptImportKey