ホーム › Security.Cryptography › CryptImportKey

CryptImportKey

関数

キーBLOBから暗号鍵をプロバイダーへインポートする。

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

シグネチャ

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

BOOL CryptImportKey(
    UINT_PTR hProv,
    const BYTE* pbData,
    DWORD dwDataLen,
    UINT_PTR hPubKey,
    CRYPT_KEY_FLAGS dwFlags,
    UINT_PTR* phKey
);

パラメーター

名前

型

方向

説明

hProv

UINT_PTR

CryptAcquireContext 関数で取得した CSP のハンドルです。

pbData

BYTE*

PUBLICKEYSTRUC BLOB ヘッダーとそれに続く暗号化された鍵を格納する BYTE 配列です。このキー BLOB は、このアプリケーション内で、または別のコンピューター上で動作している可能性のある別のアプリケーションによって、CryptExportKey 関数で作成されます。

dwDataLen

DWORD

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

hPubKey

UINT_PTR

pbData に格納された鍵を復号する暗号鍵のハンドルです。この鍵は、hProv が参照するのと同じ CSP から取得したものでなければなりません。このパラメーターの意味は、CSP の種類とインポートするキー BLOB の種類によって異なります。

キー BLOB が exchange key pair (キー交換鍵ペア) で暗号化されている場合 (たとえば SIMPLEBLOB)、このパラメーターにはキー交換鍵のハンドルを指定できます。
キー BLOB がセッション鍵で暗号化されている場合 (たとえば暗号化された PRIVATEKEYBLOB)、このパラメーターにはそのセッション鍵のハンドルを格納します。
キー BLOB が暗号化されていない場合 (たとえば PUBLICKEYBLOB)、このパラメーターは使用されず、0 でなければなりません。
キー BLOB が Schannel CSP でセッション鍵により暗号化されている場合 (たとえば暗号化された OPAQUEKEYBLOB やその他のベンダー固有の OPAQUEKEYBLOB)、このパラメーターは使用されず、0 に設定する必要があります。

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

dwFlags

CRYPT_KEY_FLAGS

現在は、PRIVATEKEYBLOB 形式の public/private key pair (公開鍵/秘密鍵ペア) を CSP にインポートする場合にのみ使用されます。

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

値	意味
CRYPT_EXPORTABLE	インポートする鍵を、最終的に再びエクスポートできるようにします。このフラグを使用しない場合、その鍵ハンドルを指定した CryptExportKey の呼び出しは失敗します。
CRYPT_OAEP	このフラグにより、SIMPLEBLOB のインポート時に RSA の暗号化および復号で PKCS #1 バージョン 2 形式のチェックが行われます。
CRYPT_NO_SALT	40 ビットの symmetric key (対称鍵) に対して no-salt value (ソルトなしの値) が割り当てられます。詳細については、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 を返します。

phKey

UINT_PTR*

out

インポートされた鍵のハンドルを受け取る HCRYPTKEY 値へのポインターです。鍵の使用を終えたら、CryptDestroyKey 関数を呼び出してハンドルを解放してください。

戻り値の型: BOOL

公式ドキュメント

暗号鍵をキー BLOB から暗号化サービスプロバイダー (CSP) に転送します。

戻り値

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

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

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

戻り値	説明
ERROR_BUSY	別のスレッドまたは process (プロセス) がこの鍵を使用している間に秘密鍵がコンテナーにインポートされた場合、このエラーを設定する CSP があります。
ERROR_INVALID_HANDLE	いずれかのパラメーターに、有効でないハンドルが指定されています。
ERROR_INVALID_PARAMETER	いずれかのパラメーターに、有効でない値が含まれています。これは多くの場合、有効でないポインターです。
NTE_BAD_ALGID	インポートする simple key BLOB が、期待される key exchange algorithm (キー交換アルゴリズム) で暗号化されていません。
NTE_BAD_DATA	インポートする公開鍵に対応するアルゴリズムがこの CSP でサポートされていないか、自分の公開鍵以外のもので暗号化されたセッション鍵をインポートしようとしました。
NTE_BAD_FLAGS	指定された dwFlags パラメーターが有効ではありません。
NTE_BAD_TYPE	このキー BLOB の種類はこの CSP でサポートされておらず、有効でない可能性があります。
NTE_BAD_UID	hProv パラメーターに、有効なコンテキストハンドルが含まれていません。
NTE_BAD_VER	キー BLOB のバージョン番号が CSP のバージョンと一致しません。通常、これは CSP のアップグレードが必要であることを示します。

解説(Remarks)

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

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

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

平文鍵のインポート例については、Example C Program: Importing a Plaintext Key を参照してください。

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

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 から鍵をインポートする方法を示しています。この関数の完全な例については、Example C Program: Signing a Hash and Verifying the Hash Signature を参照してください。この関数を使用する追加のコードについては、Example C Program: Decrypting a File を参照してください。

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

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

各言語での呼び出し定義

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

BOOL CryptImportKey(
    UINT_PTR hProv,
    const BYTE* pbData,
    DWORD dwDataLen,
    UINT_PTR hPubKey,
    CRYPT_KEY_FLAGS dwFlags,
    UINT_PTR* phKey
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool CryptImportKey(
    UIntPtr hProv,   // UINT_PTR
    IntPtr pbData,   // BYTE*
    uint dwDataLen,   // DWORD
    UIntPtr hPubKey,   // UINT_PTR
    uint dwFlags,   // CRYPT_KEY_FLAGS
    out UIntPtr phKey   // UINT_PTR* out
);

<DllImport("ADVAPI32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CryptImportKey(
    hProv As UIntPtr,   ' UINT_PTR
    pbData As IntPtr,   ' BYTE*
    dwDataLen As UInteger,   ' DWORD
    hPubKey As UIntPtr,   ' UINT_PTR
    dwFlags As UInteger,   ' CRYPT_KEY_FLAGS
    <Out> ByRef phKey As UIntPtr   ' UINT_PTR* out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hProv : UINT_PTR
' pbData : BYTE*
' dwDataLen : DWORD
' hPubKey : UINT_PTR
' dwFlags : CRYPT_KEY_FLAGS
' phKey : UINT_PTR* out
Declare PtrSafe Function CryptImportKey Lib "advapi32" ( _
    ByVal hProv As LongPtr, _
    ByVal pbData As LongPtr, _
    ByVal dwDataLen As Long, _
    ByVal hPubKey As LongPtr, _
    ByVal dwFlags As Long, _
    ByRef phKey As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CryptImportKey = ctypes.windll.advapi32.CryptImportKey
CryptImportKey.restype = wintypes.BOOL
CryptImportKey.argtypes = [
    ctypes.c_size_t,  # hProv : UINT_PTR
    ctypes.POINTER(ctypes.c_ubyte),  # pbData : BYTE*
    wintypes.DWORD,  # dwDataLen : DWORD
    ctypes.c_size_t,  # hPubKey : UINT_PTR
    wintypes.DWORD,  # dwFlags : CRYPT_KEY_FLAGS
    ctypes.POINTER(ctypes.c_size_t),  # phKey : UINT_PTR* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
CryptImportKey = Fiddle::Function.new(
  lib['CryptImportKey'],
  [
    Fiddle::TYPE_UINTPTR_T,  # hProv : UINT_PTR
    Fiddle::TYPE_VOIDP,  # pbData : BYTE*
    -Fiddle::TYPE_INT,  # dwDataLen : DWORD
    Fiddle::TYPE_UINTPTR_T,  # hPubKey : UINT_PTR
    -Fiddle::TYPE_INT,  # dwFlags : CRYPT_KEY_FLAGS
    Fiddle::TYPE_VOIDP,  # phKey : UINT_PTR* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn CryptImportKey(
        hProv: usize,  // UINT_PTR
        pbData: *const u8,  // BYTE*
        dwDataLen: u32,  // DWORD
        hPubKey: usize,  // UINT_PTR
        dwFlags: u32,  // CRYPT_KEY_FLAGS
        phKey: *mut usize  // UINT_PTR* 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 CryptImportKey(UIntPtr hProv, IntPtr pbData, uint dwDataLen, UIntPtr hPubKey, uint dwFlags, out UIntPtr phKey);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_CryptImportKey' -Namespace Win32 -PassThru
# $api::CryptImportKey(hProv, pbData, dwDataLen, hPubKey, dwFlags, phKey)

#uselib "ADVAPI32.dll"
#func global CryptImportKey "CryptImportKey" sptr, sptr, sptr, sptr, sptr, sptr
; CryptImportKey hProv, varptr(pbData), dwDataLen, hPubKey, dwFlags, varptr(phKey)   ; 戻り値は stat
; hProv : UINT_PTR -> "sptr"
; pbData : BYTE* -> "sptr"
; dwDataLen : DWORD -> "sptr"
; hPubKey : UINT_PTR -> "sptr"
; dwFlags : CRYPT_KEY_FLAGS -> "sptr"
; phKey : UINT_PTR* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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