次の方法で共有

NCryptImportKey 関数 (ncrypt.h)

  • [アーティクル]

NCryptImportKey 関数は、Cryptography API: Next Generation (CNG) キーをメモリ BLOB からインポートします。

構文

SECURITY_STATUS NCryptImportKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] NCRYPT_KEY_HANDLE  hImportKey,
  [in]           LPCWSTR            pszBlobType,
  [in, optional] NCryptBufferDesc   *pParameterList,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           PBYTE              pbData,
  [in]           DWORD              cbData,
  [in]           DWORD              dwFlags
);

パラメーター

[in] hProvider

キー ストレージ プロバイダーのハンドル。

[in, optional] hImportKey

インポートされたキー BLOB 内のキー データが暗号化された暗号化キーのハンドル。 これは、NCryptExportKey 関数の hExportKey パラメーターで渡されたのと同じキーへのハンドルである必要があります。 このパラメーターが NULL の場合、キー BLOB は暗号化されていないと見なされます。

[in] pszBlobType

キー BLOB の形式を指定する識別子を含む null で終わる Unicode 文字列。 これらの形式は、特定のキー ストレージ プロバイダーに固有です。 Microsoft プロバイダーでサポートされている BLOB 形式については、「解説」を参照してください。

[in, optional] pParameterList

キーのパラメーター情報を含むバッファーの配列を指す NCryptBufferDesc 構造体のアドレス。

[out] phKey

キーのハンドルを受け取る NCRYPT_KEY_HANDLE 変数のアドレス。 このハンドルの使用が完了したら、 NCryptFreeObject 関数に渡して解放します。

[in] pbData

インポートするキー BLOB を含むバッファーのアドレス。 cbData パラメーターには、このバッファーのサイズが含まれています。

[in] cbData

pbData バッファーのサイズ (バイト単位)。

[in] dwFlags

関数の動作を変更するフラグ。 これは、0 または次の値の 1 つ以上の組み合わせにすることができます。 有効なフラグのセットは、各キー ストレージ プロバイダーに固有です。

値 意味
NCRYPT_SILENT_FLAG キー サービス プロバイダー (KSP) にユーザー インターフェイスが表示されないことを要求します。 プロバイダーが操作する UI を表示する必要がある場合、呼び出しは失敗し、KSP は NTE_SILENT_CONTEXT エラー コードを最後のエラーとして設定する必要があります。
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 は使用できません。
NTE_VBS_CANNOT_DECRYPT_KEY VBS の暗号化解除操作に失敗しました。

注釈

重要

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

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

次のセクションでは、Microsoft キー ストレージ プロバイダーに固有の動作について説明します。

  • Microsoft Software KSP
  • Microsoft Smart Card KSP

Microsoft Software KSP

pszBlobType パラメーターの Microsoft ソフトウェア KSP では、次の定数がサポートされています。

キー名が指定されていない場合、Microsoft Software KSP はキーをエフェメラルとして扱い、永続的に保存しません。 NCRYPT_OPAQUETRANSPORT_BLOB型の場合、キー名はエクスポート時に BLOB 内に格納されます。 他の BLOB 形式の場合は、pParameterList パラメーター内の NCRYPTBUFFER_PKCS_KEY_NAME buffer パラメーターに名前を指定できます。

Windows Server 2008 および Windows Vista では、上記の方法を使用して、PKCS #7 エンベロープ BLOB (NCRYPT_PKCS7_ENVELOPE_BLOB) または PKCS #8 秘密キー BLOB (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) としてインポートされたキーのみを保持できます。 これらのプラットフォームで他の BLOB の種類を介してインポートされたキーを保持するには、「 キーのインポートとエクスポート」に記載されているメソッドを使用します。

この KSP では、次のフラグがサポートされています。

期間 説明
NCRYPT_NO_KEY_VALIDATION キー ペアの公開部分を検証しないでください。 このフラグは、公開キーと秘密キーのペアにのみ適用されます。
NCRYPT_DO_NOT_FINALIZE_FLAG キーを最終処理しないでください。 このオプションは、インポート後にキーのプロパティを追加または変更する必要がある場合に便利です。 キー ハンドルを NCryptFinalizeKey 関数に渡して使用するには、キーを最終処理する必要があります。 このフラグは、秘密キー PKCS #7 と PKCS #8 ではサポートされていますが、公開キーではサポートされていません。
NCRYPT_MACHINE_KEY_FLAG キーはローカル コンピューターに適用されます。 このフラグが存在しない場合、キーは現在のユーザーに適用されます。
NCRYPT_OVERWRITE_KEY_FLAG 指定した名前のキーがコンテナーに既に存在する場合は、既存のキーが上書きされます。 このフラグが指定されておらず、指定した名前のキーが既に存在する場合、この関数は NTE_EXISTSを返します。
NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG また、キーをレガシ ストレージに保存します。 これにより、キーを CryptoAPI と共に使用できます。 このフラグは RSA キーにのみ適用されます。

Microsoft スマート カード KSP

この KSP でサポートされる主要な BLOB 形式とフラグのセットは、Microsoft Software KSP でサポートされているセットと同じです。

Windows Server 2008 および Windows Vista では、Microsoft スマート カード KSP はすべてのキーを Microsoft ソフトウェア KSP にインポートします。 そのため、この API を使用してスマート カードにキーを保持することはできません。Microsoft Software KSP 内でキーを永続化しようとすると、上記のセクションのガイダンスが適用されます。

Windows Server 2008 R2 および Windows 7 では、Microsoft スマート カード キー ストレージ プロバイダーは、次の条件が満たされていれば、秘密キーをスマート カードにインポートできます。

  • カードのキー コンテナー名が有効です。
  • 秘密キーのインポートは、スマート カードでサポートされています。
  • 次の 2 つのレジストリ キーは、 の 0x1DWORD に設定されます。
    • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
    • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport

キー コンテナー名が NULL の場合、Microsoft Smart Card KSP はキーをエフェメラルとして扱い、Microsoft Software KSP にインポートします。

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

こちらもご覧ください

NCryptBuffer

NCryptCreatePersistedKey