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 スマート カード KSP

Microsoft Software KSP

Microsoft ソフトウェア KSP でサポートされているほとんどの pszBlobType パラメーターの詳細については、NCryptImportKey を参照してください。

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

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 Software KSP にインポートします。 したがって、この API を使用してキーをスマート カードに保持することはできません。また、Microsoft Software KSP 内でキーを保持しようとすると、上記のセクションのガイダンスが適用されます。

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

• カードのキー コンテナー名が有効です。
• 秘密キーのインポートは、スマート カードでサポートされています。
• 次の 2 つのレジストリ キーは、の 0x1 に設定されます。
  • 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 スマート カード 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