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 が使用できない場合、操作によってソフトウェア分離キーが生成されます。 (*「備考」を参照) |
戻り値
関数の成功または失敗を示す状態コードを返します。
次のようなリターン コードが考えられますが、これらに限定されません。
| リターン コード | 説明 |
|---|---|
| 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 Smart Card KSP
この KSP でサポートされるキー BLOB 形式とフラグのセットは、Microsoft Software KSP でサポートされているセットと同じです。
Windows Server 2008 および Windows Vista では、Microsoft Smart Card KSP によってすべてのキーが Microsoft Software 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 ハードウェア要件の完全な一覧については、 こちらを参照してください。
- 安全性の高いデバイスの要件については、 こちらを参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | ncrypt.h |
| Library | Ncrypt.lib |
| [DLL] | Ncrypt.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示