次の方法で共有


CryptImportKey 関数 (wincrypt.h)

重要 この API は非推奨です。 新規および既存のソフトウェアでは、Cryptography Next Generation API の使用を開始する必要があります。 Microsoft は、今後のリリースでこの API を削除する可能性があります。
 
CryptImportKey 関数は、キー BLOB から 暗号化サービス プロバイダー (CSP) に 暗号化キーを転送します。 この関数を使用して、Schannelセッション キー、通常のセッション キー、公開キー、または 公開キーと秘密キーのペアをインポートできます。 公開キー以外のすべてに対して、キーまたはキーのペアが暗号化されます。

構文

BOOL CryptImportKey(
  [in]  HCRYPTPROV hProv,
  [in]  const BYTE *pbData,
  [in]  DWORD      dwDataLen,
  [in]  HCRYPTKEY  hPubKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

パラメーター

[in] hProv

CryptAcquireContext 関数で取得された CSP のハンドル。

[in] pbData

PUBLICKEYSTRUC BLOB ヘッダーの後に暗号化されたキーが続く、BYTE 配列。 このキー BLOB は、CryptExportKey 関数によって、このアプリケーションまたは別のコンピューターで実行されている可能性のある別のアプリケーションによって作成されます。

[in] dwDataLen

キー BLOB の長さをバイト単位で格納します。

[in] hPubKey

pbDataに格納されているキーを復号化する暗号化キーのハンドル。 このキーは、hProv 参照するのと同じ CSP から取得する必要があります。 このパラメーターの意味は、CSP の種類とインポートするキー BLOB の種類によって異なります。

  • キー BLOB がキー 交換キー ペア(たとえば、SIMPLEBLOB) で暗号化されている場合、このパラメーターをキー交換キーのハンドルにすることができます。
  • 暗号化された PRIVATEKEYBLOBなど、キー BLOB がセッション キーで暗号化されている場合、このパラメーターにはこのセッション キーのハンドルが含まれます。
  • PUBLICKEYBLOBなど、キー BLOB が暗号化されていない場合、このパラメーターは使用されず、ゼロである必要があります。
  • キー BLOB が Schannel CSP のセッション キーで暗号化されている場合 (たとえば、暗号化された OPAQUEKEYBLOB や他のベンダー固有の OPAQUEKEYBLOBなど)、このパラメーターは使用されず、ゼロに設定する必要があります。
一部の CSP は、操作の結果としてこのパラメーターを変更する可能性があります。 その後、他の目的でこのキーを使用するアプリケーションでは、CryptDuplicateKey 関数を呼び出して、重複するキー ハンドルを作成する必要があります。 アプリケーションでハンドルの使用が完了したら、CryptDestroyKey 関数を呼び出して解放します。
 

[in] dwFlags

現在、PRIVATEKEYBLOB の形式で 公開キーと秘密キーのペアが CSP にインポートされている場合にのみ使用されます。

このパラメーターには、次のいずれかの値を指定できます。

価値 意味
CRYPT_EXPORTABLE
インポートされるキーは最終的に再エクスポートされます。 このフラグを使用しない場合、キー ハンドルを使用して CryptExportKey を する呼び出しは失敗します。
CRYPT_OAEP
このフラグにより、SIMPLEBLOBをインポートするときに、RSA 暗号化と復号化で PKCS #1 バージョン 2 の書式設定 確認されます。
CRYPT_NO_SALT
40 ビットの 対称キーに割り当てられる なし値。 詳細については、「Salt Value Functionality」を参照してください。
CRYPT_USER_PROTECTED
このフラグが設定されている場合、CSP は、このキーを使用して特定のアクションが試行されたときに、ダイアログ ボックスまたはその他の方法を使用してユーザーに通知します。 正確な動作は、使用される CSP または CSP の種類によって指定されます。 プロバイダー コンテキストが CRYPT_SILENT セットで取得された場合、このフラグを使用するとエラーが発生し、最後のエラーがNTE_SILENT_CONTEXTに設定されます。
CRYPT_IPSEC_HMAC_KEY
16 バイトを超える RC2 キーのインポートを許可します。 このフラグが設定されていない場合、16 バイトを超える RC2 キーを持つ CryptImportKey 関数の呼び出しは失敗し、GetLastError の呼び出しは NTE_BAD_DATAを返します。

[out] phKey

インポートされたキーのハンドルを受け取る HCRYPTKEY 値へのポインター。 キーの使用が完了したら、CryptDestroyKey 関数を呼び出してハンドルを解放します。

戻り値

関数が成功した場合、関数は 0 以外の値を返します。

関数が失敗すると、0 が返されます。 拡張エラー情報については、GetLastError呼び出します。

"NTE" で開始されるエラー コードは、使用されている特定の CSP によって生成されます。 考えられるエラー コードの一部を次に示します。

リターン コード 形容
ERROR_BUSY
一部の CSP は、別のスレッドまたは プロセスでこのキーを使用している間に秘密キーがコンテナーにインポート 場合に、このエラーを設定します。
ERROR_INVALID_HANDLE
パラメーターの 1 つは無効なハンドルを指定します。
ERROR_INVALID_PARAMETER
パラメーターの 1 つに無効な値が含まれています。 これは、多くの場合、無効なポインターです。
NTE_BAD_ALGID
インポートする 単純なキー BLOB は、予想される キー交換アルゴリズムで暗号化されません。
NTE_BAD_DATA
インポートする公開キーで動作するアルゴリズムがこの CSP でサポートされていないか、公開キー以外の何かで暗号化されたセッション キーをインポートしようとしました。
NTE_BAD_FLAGS
指定された dwFlags パラメーターが無効です。
NTE_BAD_TYPE
キー BLOB の種類は、この CSP でサポートされていないため、有効でない可能性があります。
NTE_BAD_UID
hProv パラメーターに有効なコンテキスト ハンドルが含まれていません。
NTE_BAD_VER
キー BLOB のバージョン番号が CSP のバージョンと一致しません。 これは通常、CSP をアップグレードする必要があることを示します。

備考

Hash-Based メッセージ認証コード (HMAC) キーをインポートする場合、呼び出し元はインポートされたキーを PLAINTEXTKEYBLOB 型として識別し、PUBLICKEYSTRUC BLOB ヘッダーの aiKeyAlg フィールドに適切なアルゴリズム識別子を設定する必要があります。

CryptImportKey 関数を使用して、対称アルゴリズムのプレーンテキスト キーをインポートできます。ただし、使いやすくするために、代わりに CryptGenKey 関数を使用することをお勧めします。 プレーンテキスト キーをインポートする場合、pbData パラメーターで渡されるキー BLOB の構造は、PLAINTEXTKEYBLOBです。

PLAINTEXTKEYBLOB 型は、使用中の CSP でサポートされている任意のアルゴリズムまたは種類のキーの組み合わせで使用できます。

プレーンテキスト キーのインポートの例については、「サンプル C プログラム: プレーンテキスト キーのインポート」を参照してください。

次の例は、ヘッダー フィールドを設定する方法を示しています。

keyBlob.header.bType = PLAINTEXTKEYBLOB;
keyBlob.header.bVersion = CUR_BLOB_VERSION;
keyBlob.header.reserved = 0;
// CALG_AES_128 is used as an example. You would set this to the 
// algorithm id that corresponds to the one used by the key.
keyBlob.header.aiKeyAlg = CALG_AES_128;

キーの長さは keyBlob.keyLength で指定され、その後に実際のキー データが続きます。

HMAC アルゴリズムには独自のアルゴリズム識別子がありません。代わりにCALG_RC2を使用してください。 CRYPT_IPSEC_HMAC_KEY では、16 バイトを超える RC2 キーをインポートできます。
 
PLAINTEXTKEYBLOB
使用する Data Encryption Standard (DES) キーの順列の場合は、パリティ ビットを含むフル キー サイズのみをインポートできます。

次のキー サイズがサポートされています。

アルゴリズム サポートされているキー サイズ
CALG_DES 64 ビット
CALG_3DES_112 128 ビット
CALG_3DES 192 ビット
 

次の例は、キー BLOB からキーをインポートする方法を示しています。 この関数の完全な例については、「例 C プログラム: ハッシュの署名とハッシュ署名の検証」を参照してください。 この関数を使用するその他のコードについては、「サンプル C プログラム: ファイルの復号化」を参照してください。

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>

BOOL ImportKey(HCRYPTPROV hProv, LPBYTE pbKeyBlob, DWORD dwBlobLen)
{
    HCRYPTKEY hPubKey;

    //---------------------------------------------------------------
    // This code assumes that a cryptographic provider (hProv) 
    // has been acquired and that a key BLOB (pbKeyBlob) that is 
    // dwBlobLen bytes long has been acquired. 

    //---------------------------------------------------------------
    // Get the public key of the user who created the digital 
    // signature and import it into the CSP by using CryptImportKey. 
    // The key to be imported is in the buffer pbKeyBlob that is  
    // dwBlobLen bytes long. This function returns a handle to the 
    // public key in hPubKey.

    if(CryptImportKey(
        hProv,
        pbKeyBlob,
        dwBlobLen,
        0,
        0,
        &hPubKey))
    {
        printf("The key has been imported.\n");
    }
    else
    {
        printf("Public key import failed.\n");
        return FALSE;
    }

    //---------------------------------------------------------------
    // Insert code that uses the imported public key here.
    //---------------------------------------------------------------

    //---------------------------------------------------------------
    // When you have finished using the key, you must release it.
    if(CryptDestroyKey(hPubKey))
    {
        printf("The public key has been released.");
    }
    else
    {
        printf("The public key has not been released.");
        return FALSE;
    }

    return TRUE;
}

必要条件

要件 価値
サポートされる最小クライアント Windows XP [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2003 [デスクトップ アプリのみ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー wincrypt.h
ライブラリ Advapi32.lib
DLL Advapi32.dll

関連項目

CryptAcquireContext

CryptDestroyKey

CryptExportKey

キー生成と Exchange 関数の