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 つ以上の組み合わせにすることができます。 有効なフラグのセットは、各キー ストレージ プロバイダーに固有です。

戻り値

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

次のようなリターン コードが考えられますが、これらに限定されません。

注釈

サービスは 、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 では、次のフラグがサポートされています。

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 が有効 ( 仮想化ベースのセキュリティ (VBS) に関するページを参照)
• TPM が有効
  • ベアメタル環境では、TPM 2.0 が必要です。
  • VM 環境では、vTPM (仮想 TPM) がサポートされています。
• SECUREBoot プロファイルを使用して BIOS を UEFI にアップグレードする必要がある

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

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

要件

こちらもご覧ください

NCryptBuffer

NCryptCreatePersistedKey