CryptExportKey 関数 (wincrypt.h)

  • [アーティクル]
大事な この API は非推奨です。 新規および既存のソフトウェアでは 、暗号化次世代 API の 使用を開始する必要があります。Microsoft は、今後のリリースでこの API を削除する可能性があります。
 
CryptExportKey 関数は、暗号化キーまたはキー ペアを暗号化サービス プロバイダー (CSP) から安全な方法でエクスポートします。

エクスポートするキーへのハンドルが関数に渡され、関数は キー BLOB を返します。 このキー BLOB は、セキュリティで保護されていないトランスポート経由で送信することも、セキュリティで保護されていないストレージの場所に格納することもできます。 この関数は、 Schannel セッション キー、通常の セッション キー、 公開キー、または 公開/秘密キーのペアをエクスポートできます。 エクスポートするキー BLOB は、目的の受信者が CryptImportKey 関数を使用してキーまたはキー ペアを受信者の CSP にインポートするまで役に立ちません。

構文

BOOL CryptExportKey(
  [in]      HCRYPTKEY hKey,
  [in]      HCRYPTKEY hExpKey,
  [in]      DWORD     dwBlobType,
  [in]      DWORD     dwFlags,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen
);

パラメーター

[in] hKey

エクスポートするキーへのハンドル。

[in] hExpKey

宛先ユーザーの暗号化キーへのハンドル。 エクスポートされたキー BLOB 内の キー データは、このキーを使用して暗号化されます。 これにより、宛先ユーザーのみがキー BLOB を使用できるようになります。 hExpKey と hKey はどちらも同じ CSP から取得する必要があります。

ほとんどの場合、これは宛先ユーザーの キー交換公開キー です。 ただし、一部の CSP の特定のプロトコルでは、宛先ユーザーに属するセッション キーをこの目的で使用する必要があります。

dwBlobType で指定されたキー BLOB の種類が PUBLICKEYBLOB の場合、このパラメーターは使用されず、ゼロに設定する必要があります。

dwBlobType で指定されたキー BLOB の種類が PRIVATEKEYBLOB の場合、これは通常、キー BLOB の暗号化に使用されるセッション キーへのハンドルです。 一部の CSP では、このパラメーターを 0 にできます。この場合、アプリケーションは 秘密キー BLOB を 保護するために手動で暗号化する必要があります。

このパラメーターに対する Microsoft 暗号化サービス プロバイダーの応答方法を確認するには、「Microsoft Cryptographic Service Providers」の秘密キー BLOB セクションを参照してください。

メモ 一部の CSP では、操作の結果としてこのパラメーターが変更される場合があります。 その後、他の目的でこのキーを使用するアプリケーションでは、 CryptDuplicateKey 関数を呼び出して、重複するキー ハンドルを作成する必要があります。 アプリケーションで ハンドルの使用が完了したら、 CryptDestroyKey 関数を呼び出して解放します。
 

[in] dwBlobType

pbData でエクスポートするキー BLOB の種類を指定します。 これは、「 暗号化キー ストレージと Exchange」で説明されているように、次のいずれかの定数である必要があります。

値 意味
OPAQUEKEYBLOB
 セッション キーを Schannel CSP またはその他のベンダー固有の形式で格納するために使用されます。 OPAQUEKEYBLOB は転送不可であり、BLOB を生成した CSP 内で使用する必要があります。
PRIVATEKEYBLOB
 公開キーと秘密キーのペアを転送するために使用されます。
PUBLICKEYBLOB
 公開キーを転送するために使用されます。
SIMPLEBLOB
 セッション キーを転送するために使用されます。
PLAINTEXTKEYBLOB
 使用中の CSP でサポートされているキーをエクスポートするために使用される PLAINTEXTKEYBLOB 。
SYMMETRICWRAPKEYBLOB
 別の対称キーでラップされた 対称キー をエクスポートおよびインポートするために使用されます。 実際にラップされたキーは、IETF RFC 3217 標準で指定されている形式です。

[in] dwFlags

関数の追加オプションを指定します。 このパラメーターには、0 または次の値の 1 つ以上の組み合わせを指定できます。

値 意味
CRYPT_BLOB_VER3
0x00000080
 このフラグにより、この関数は BLOB 型のバージョン 3 をエクスポートします。
CRYPT_DESTROYKEY
0x00000004
 このフラグは、OPAQUEKEYBLOB の元のキーを破棄します。 このフラグは、Schannel CSP でのみ使用できます。
CRYPT_OAEP
0x00000040
 このフラグにより、SIMPLEBLOB のエクスポート時に RSA 暗号化と復号化を使用して PKCS #1 バージョン 2 の書式設定が作成されます。
CRYPT_SSL2_FALLBACK
0x00000002
 RSA 暗号化ブロック の埋め込みの 最初の 8 バイトは、ランダム データではなく0x03に設定する必要があります。 これにより、バージョンロールバック攻撃が防止され、SSL3 仕様で説明されています。 このフラグは、Schannel CSP でのみ使用できます。
CRYPT_Y_ONLY
0x00000001
 このフラグは使用されません。

[out] pbData

キー BLOB データを受け取るバッファーへのポインター。 この BLOB の形式は、 dwBlobType パラメーターで要求された BLOB の種類によって異なります。 PRIVATEKEYBLOB、PUBLICKEYBLOB、SIMPLEBLOB の形式については、「 基本プロバイダー キー BLOB」を参照してください。

このパラメーターが NULL の場合、必要なバッファー サイズは pdwDataLen パラメーターが指す値に配置されます。 詳細については、「 不明な長さのデータの取得」を参照してください。

[in, out] pdwDataLen

入力時に pbData パラメーターが指すバッファーのサイズ (バイト単位) を含む DWORD 値へのポインター。 関数が戻るとき、この値にはバッファーに格納されているバイト数が含まれます。

メモ バッファーで返されるデータを処理する場合、アプリケーションは返されるデータの実際のサイズを使用する必要があります。 実際のサイズは、入力時に指定されたバッファーのサイズよりも少し小さくすることができます。 入力では、バッファー サイズは通常、可能な最大の出力データがバッファーに収まるように十分な大きさで指定されます。 出力時に、このパラメーターが指す変数が更新され、バッファーにコピーされたデータの実際のサイズが反映されます。
 
pbData バッファーの必要なサイズを取得するには、pbData に NULL を渡します。 必要なバッファー サイズは、このパラメーターが指す値に配置されます。

戻り値

関数が成功した場合、関数は 0 以外 (TRUE) を返します。

関数が失敗した場合は、0 (FALSE) を返します。 拡張エラー情報については、 GetLastError を呼び出します。

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

リターン コード 説明
ERROR_INVALID_HANDLE
 パラメーターの 1 つは、無効なハンドルを指定します。
ERROR_INVALID_PARAMETER
 パラメーターの 1 つに無効な値が含まれています。 これは、ほとんどの場合、無効なポインターです。
ERROR_MORE_DATA
 pbData パラメーターで指定されたバッファーが、返されるデータを保持するのに十分な大きさでない場合、関数はERROR_MORE_DATA コードを設定し、pdwDataLen が指す変数に必要なバッファー サイズをバイト単位で格納します。
NTE_BAD_DATA
 エクスポートする公開キーで動作するアルゴリズムがこの CSP でサポートされていないか、公開キーの 1 つ以外で暗号化されたセッション キーをエクスポートしようとしました。
NTE_BAD_FLAGS
 dwFlags パラメーターは 0 以外です。
NTE_BAD_KEY
 hKey と hExpKey で指定されたキーの一方または両方が無効です。
NTE_BAD_KEY_STATE
 キーをエクスポートするアクセス許可がありません。 つまり、 hKey キーが作成されたときに、CRYPT_EXPORTABLE フラグが指定されませんでした。
NTE_BAD_PUBLIC_KEY
 dwBlobType で指定されたキー BLOB の種類は PUBLICKEYBLOB ですが、hExpKey には公開キー ハンドルが含まれていません。
NTE_BAD_TYPE
 dwBlobType パラメーターは、不明な BLOB 型を指定します。
NTE_BAD_UID
 hKey キーの作成時に指定された CSP コンテキストが見つかりません。
NTE_NO_KEY
 セッション キーがエクスポートされており、 hExpKey パラメーターで公開キーが指定されていません。

注釈

PLAINTEXTKEYBLOB を使用する DES キー順列の場合、パリティ ビットを含む完全なキー サイズのみをエクスポートできます。 次のキー サイズがサポートされています。

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

例

次の例は、暗号化キーまたはキー ペアをより安全な方法でエクスポートする方法を示しています。 この例では、暗号化コンテキストが取得され、公開キーがエクスポート可能であることを前提としています。 この関数を使用するための完全なコンテキストを含む例については、「 サンプル C プログラム: ハッシュの署名とハッシュ署名の検証」を参照してください。 この関数を使用する別の例については、「 サンプル C プログラム: セッション キーのエクスポート」を参照してください。

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

BOOL GetExportedKey(
    HCRYPTKEY hKey, 
    DWORD dwBlobType,
    LPBYTE *ppbKeyBlob, 
    LPDWORD pdwBlobLen)
{
    DWORD dwBlobLength;
    *ppbKeyBlob = NULL;
    *pdwBlobLen = 0;

    // Export the public key. Here the public key is exported to a 
    // PUBLICKEYBLOB. This BLOB can be written to a file and
    // sent to another user.

    if(CryptExportKey(   
        hKey,    
        NULL,    
        dwBlobType,
        0,    
        NULL, 
        &dwBlobLength)) 
    {
        printf("Size of the BLOB for the public key determined. \n");
    }
    else
    {
        printf("Error computing BLOB length.\n");
        return FALSE;
    }

    // Allocate memory for the pbKeyBlob.
    if(*ppbKeyBlob = (LPBYTE)malloc(dwBlobLength)) 
    {
        printf("Memory has been allocated for the BLOB. \n");
    }
    else
    {
        printf("Out of memory. \n");
        return FALSE;
    }

    // Do the actual exporting into the key BLOB.
    if(CryptExportKey(   
        hKey, 
        NULL,    
        dwBlobType,    
        0,    
        *ppbKeyBlob,    
        &dwBlobLength))
    {
        printf("Contents have been written to the BLOB. \n");
        *pdwBlobLen = dwBlobLength;
    }
    else
    {
        printf("Error exporting key.\n");
        free(*ppbKeyBlob);
        *ppbKeyBlob = NULL;

        return FALSE;
    }

    return TRUE;
}

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー wincrypt.h
Library Advapi32.lib
[DLL] Advapi32.dll

こちらもご覧ください

CryptImportKey

キー生成と Exchange 関数