ホーム › Security.Cryptography › CryptExportKey

CryptExportKey

関数

暗号鍵を保護されたキーBLOB形式でエクスポートする。

DLLADVAPI32.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// ADVAPI32.dll
#include <windows.h>

BOOL CryptExportKey(
    UINT_PTR hKey,
    UINT_PTR hExpKey,
    DWORD dwBlobType,
    CRYPT_KEY_FLAGS dwFlags,
    BYTE* pbData,   // optional
    DWORD* pdwDataLen
);

パラメーター

名前

型

方向

説明

hKey

UINT_PTR

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

hExpKey

UINT_PTR

宛先ユーザーの暗号鍵のハンドル。エクスポートされる key BLOB 内の鍵データは、この鍵を使用して暗号化されます。これにより、宛先ユーザーだけが key BLOB を利用できるようになります。hExpKey と hKey は、いずれも同じ CSP に由来している必要があります。

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

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

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

Microsoft の cryptographic service providers がこのパラメーターにどのように応答するかを確認するには、 Microsoft Cryptographic Service Providers の private key BLOB のセクションを参照してください。

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

dwBlobType

DWORD

pbData にエクスポートする key BLOB の種類を指定します。これは、 Cryptographic Key Storage and Exchange で説明されている次の定数のいずれかである必要があります。

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

dwFlags

CRYPT_KEY_FLAGS

関数の追加オプションを指定します。このパラメーターには、ゼロ、または次の値の 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 暗号化ブロックの padding の最初の 8 バイトを、ランダムデータではなく 0x03 に設定する必要があります。これはバージョンロールバック攻撃を防ぐもので、SSL3 仕様で説明されています。このフラグは Schannel CSP でのみ使用できます。
CRYPT_Y_ONLY 0x00000001	このフラグは使用されません。

pbData

BYTE*

outoptional

key BLOB データを受け取るバッファーへのポインター。この BLOB の形式は、dwBlobType パラメーターで要求された BLOB 型によって異なります。PRIVATEKEYBLOB、PUBLICKEYBLOB、SIMPLEBLOB の形式については、 Base Provider Key BLOBs を参照してください。

このパラメーターが NULL の場合、必要なバッファーサイズが pdwDataLen パラメーターが指す値に格納されます。詳細については、 Retrieving Data of Unknown Length を参照してください。

pdwDataLen

DWORD*

inout

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

注意バッファーで返されたデータを処理する際、アプリケーションは返されたデータの実際のサイズを使用する必要があります。実際のサイズは、入力で指定したバッファーのサイズよりわずかに小さい場合があります。入力時には、起こり得る最大の出力データが収まるように、通常はバッファーサイズを十分に大きく指定します。出力時には、このパラメーターが指す変数が、バッファーにコピーされたデータの実際のサイズを反映するように更新されます。

pbData バッファーに必要なサイズを取得するには、pbData に NULL を渡します。必要なバッファーサイズが、このパラメーターが指す値に格納されます。

戻り値の型: BOOL

公式ドキュメント

暗号化サービスプロバイダー (CSP) から暗号鍵または鍵ペアを安全な方法でエクスポートします。

戻り値

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

関数が失敗した場合、ゼロ (FALSE) を返します。拡張エラー情報を取得するには、 GetLastError を呼び出します。

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

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

解説(Remarks)

PLAINTEXTKEYBLOB を使用する DES 鍵の組み合わせのいずれについても、パリティビットを含む完全な鍵サイズのみをエクスポートできます。次の鍵サイズがサポートされています。

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

例

次の例は、暗号鍵または鍵ペアをより安全な方法でエクスポートする方法を示しています。この例では、暗号コンテキストが既に取得されており、エクスポート用の公開鍵が利用可能であることを前提としています。この関数を使用するための完全なコンテキストを含む例については、 Example C Program: Signing a Hash and Verifying the Hash Signature を参照してください。この関数を使用する別の例については、Example C Program: Exporting a Session Key を参照してください。

#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;
}

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

各言語での呼び出し定義

// ADVAPI32.dll
#include <windows.h>

BOOL CryptExportKey(
    UINT_PTR hKey,
    UINT_PTR hExpKey,
    DWORD dwBlobType,
    CRYPT_KEY_FLAGS dwFlags,
    BYTE* pbData,   // optional
    DWORD* pdwDataLen
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool CryptExportKey(
    UIntPtr hKey,   // UINT_PTR
    UIntPtr hExpKey,   // UINT_PTR
    uint dwBlobType,   // DWORD
    uint dwFlags,   // CRYPT_KEY_FLAGS
    IntPtr pbData,   // BYTE* optional, out
    ref uint pdwDataLen   // DWORD* in/out
);

<DllImport("ADVAPI32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CryptExportKey(
    hKey As UIntPtr,   ' UINT_PTR
    hExpKey As UIntPtr,   ' UINT_PTR
    dwBlobType As UInteger,   ' DWORD
    dwFlags As UInteger,   ' CRYPT_KEY_FLAGS
    pbData As IntPtr,   ' BYTE* optional, out
    ByRef pdwDataLen As UInteger   ' DWORD* in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hKey : UINT_PTR
' hExpKey : UINT_PTR
' dwBlobType : DWORD
' dwFlags : CRYPT_KEY_FLAGS
' pbData : BYTE* optional, out
' pdwDataLen : DWORD* in/out
Declare PtrSafe Function CryptExportKey Lib "advapi32" ( _
    ByVal hKey As LongPtr, _
    ByVal hExpKey As LongPtr, _
    ByVal dwBlobType As Long, _
    ByVal dwFlags As Long, _
    ByVal pbData As LongPtr, _
    ByRef pdwDataLen As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CryptExportKey = ctypes.windll.advapi32.CryptExportKey
CryptExportKey.restype = wintypes.BOOL
CryptExportKey.argtypes = [
    ctypes.c_size_t,  # hKey : UINT_PTR
    ctypes.c_size_t,  # hExpKey : UINT_PTR
    wintypes.DWORD,  # dwBlobType : DWORD
    wintypes.DWORD,  # dwFlags : CRYPT_KEY_FLAGS
    ctypes.POINTER(ctypes.c_ubyte),  # pbData : BYTE* optional, out
    ctypes.POINTER(wintypes.DWORD),  # pdwDataLen : DWORD* in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
CryptExportKey = Fiddle::Function.new(
  lib['CryptExportKey'],
  [
    Fiddle::TYPE_UINTPTR_T,  # hKey : UINT_PTR
    Fiddle::TYPE_UINTPTR_T,  # hExpKey : UINT_PTR
    -Fiddle::TYPE_INT,  # dwBlobType : DWORD
    -Fiddle::TYPE_INT,  # dwFlags : CRYPT_KEY_FLAGS
    Fiddle::TYPE_VOIDP,  # pbData : BYTE* optional, out
    Fiddle::TYPE_VOIDP,  # pdwDataLen : DWORD* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn CryptExportKey(
        hKey: usize,  // UINT_PTR
        hExpKey: usize,  // UINT_PTR
        dwBlobType: u32,  // DWORD
        dwFlags: u32,  // CRYPT_KEY_FLAGS
        pbData: *mut u8,  // BYTE* optional, out
        pdwDataLen: *mut u32  // DWORD* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true)]
public static extern bool CryptExportKey(UIntPtr hKey, UIntPtr hExpKey, uint dwBlobType, uint dwFlags, IntPtr pbData, ref uint pdwDataLen);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_CryptExportKey' -Namespace Win32 -PassThru
# $api::CryptExportKey(hKey, hExpKey, dwBlobType, dwFlags, pbData, pdwDataLen)

#uselib "ADVAPI32.dll"
#func global CryptExportKey "CryptExportKey" sptr, sptr, sptr, sptr, sptr, sptr
; CryptExportKey hKey, hExpKey, dwBlobType, dwFlags, varptr(pbData), varptr(pdwDataLen)   ; 戻り値は stat
; hKey : UINT_PTR -> "sptr"
; hExpKey : UINT_PTR -> "sptr"
; dwBlobType : DWORD -> "sptr"
; dwFlags : CRYPT_KEY_FLAGS -> "sptr"
; pbData : BYTE* optional, out -> "sptr"
; pdwDataLen : DWORD* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global CryptExportKey "CryptExportKey" sptr, sptr, int, int, var, var
; res = CryptExportKey(hKey, hExpKey, dwBlobType, dwFlags, pbData, pdwDataLen)
; hKey : UINT_PTR -> "sptr"
; hExpKey : UINT_PTR -> "sptr"
; dwBlobType : DWORD -> "int"
; dwFlags : CRYPT_KEY_FLAGS -> "int"
; pbData : BYTE* optional, out -> "var"
; pdwDataLen : DWORD* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global CryptExportKey "CryptExportKey" sptr, sptr, int, int, sptr, sptr
; res = CryptExportKey(hKey, hExpKey, dwBlobType, dwFlags, varptr(pbData), varptr(pdwDataLen))
; hKey : UINT_PTR -> "sptr"
; hExpKey : UINT_PTR -> "sptr"
; dwBlobType : DWORD -> "int"
; dwFlags : CRYPT_KEY_FLAGS -> "int"
; pbData : BYTE* optional, out -> "sptr"
; pdwDataLen : DWORD* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。