Win32 API 日本語リファレンス
ホーム › Security.Cryptography › NCryptImportKeyFn

NCryptImportKeyFn

コールバック

シグネチャ

HRESULT NCryptImportKeyFn(
    NCRYPT_PROV_HANDLE hProvider,
    NCRYPT_KEY_HANDLE hImportKey,
    LPWSTR pszBlobType,
    BCryptBufferDesc* pParameterList,
    NCRYPT_KEY_HANDLE* phKey,
    BYTE* pbData,
    DWORD cbData,
    DWORD dwFlags
);

パラメーター

フィールド型説明
hProviderNCRYPT_PROV_HANDLEキーストレージプロバイダーのハンドルです。
hImportKeyNCRYPT_KEY_HANDLEインポートされる キー BLOB 内のキーデータの暗号化に使用された 暗号化キー のハンドルです。これは、NCryptExportKey 関数の hExportKey パラメーターに渡したものと同じキーのハンドルである必要があります。このパラメーターが NULL の場合、キー BLOB は暗号化されていないものとみなされます。
pszBlobTypeLPWSTRキー BLOB の形式を指定する識別子を含む、null で終わる Unicode 文字列です。これらの形式は、個々のキーストレージプロバイダーに固有です。Microsoft 製プロバイダーがサポートする BLOB 形式については、解説 を参照してください。
pParameterListBCryptBufferDesc*キーのパラメーター情報を格納するバッファーの配列を指す NCryptBufferDesc 構造体のアドレスです。
phKeyNCRYPT_KEY_HANDLE*キーのハンドルを受け取る NCRYPT_KEY_HANDLE 変数のアドレスです。このハンドルの使用を終えたら、NCryptFreeObject 関数に渡して解放してください。
pbDataBYTE*インポートするキー BLOB を格納するバッファーのアドレスです。cbData パラメーターには、このバッファーのサイズを指定します。
cbDataDWORDpbData バッファーのサイズ (バイト単位) です。
dwFlagsDWORD

関数の動作を変更するフラグです。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) に対して、ディスクに格納されるがブートサイクルをまたいで再利用できないブート単位のキーでクライアントキーを保護するよう指示します。(*解説を参照)

公式ドキュメント

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

戻り値

関数の成功または失敗を示すステータスコードを返します。

返される可能性のあるコードには、次のものが含まれます (これらに限定されません)。

戻り値 説明
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 が復号操作に失敗しました。

解説(Remarks)

重要

VBS フラグに関する情報は、製品版として提供されるまでに大幅に変更される可能性があるプレリリース製品に関するものです。Microsoft は、ここで提供される情報について、明示または黙示を問わずいかなる保証も行いません。

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

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

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 は次のフラグをサポートします。

用語 説明
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 Smart Card Key Storage Provider は秘密キーをスマートカードにインポートできます。

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

VBS キーに関する追加のハードウェア要件

適切な OS がコンピューターにインストールされていても、VBS を使用してキーを生成および保護するには、次の追加のハードウェア要件を満たす必要があります。

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)