共用方式為


CryptImportKey 函式 (wincrypt.h)

重要 此 API 已被取代。 新的和現有的軟體應該開始使用 密碼編譯新一代 API。 Microsoft 在未來版本中可能會移除此 API。
 
CryptImportKey 函式會將 密碼編譯金鑰金鑰 BLOB 傳輸至 密碼編譯服務提供者 (CSP)。 此函式可用來匯入 信道會話密鑰、一般會話密鑰、公鑰,或 公開/私鑰組。 除了公鑰,金鑰或金鑰組也會加密。

語法

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

BYTE 數位列,其中包含 PUBLICKEYSTRUC BLOB 標頭,後面接著加密密鑰。 此密鑰 BLOB 是由 CryptExportKey 函式所建立,不論是在此應用程式中,還是由另一個可能在不同的電腦上執行的應用程式所建立。

[in] dwDataLen

包含金鑰 BLOB 的長度,以位元組為單位。

[in] hPubKey

密碼編譯密鑰的句柄,會將儲存在 pbData 中的密鑰解密。 此金鑰必須來自 hProv 參考的相同 CSP。 此參數的意義會根據 CSP 類型和要匯入的金鑰 BLOB 類型而有所不同:

  • 如果密鑰 BLOB 是以金鑰 交換金鑰組加密,例如,SIMPLEBLOB,這個參數可以是金鑰交換金鑰的句柄。
  • 例如,如果金鑰 BLOB 是以工作階段金鑰加密,例如,加密 PRIVATEKEYBLOB,此參數會包含此工作階段密鑰的句柄。
  • 例如,如果未加密密鑰 BLOB,PUBLICKEYBLOB,則不會使用此參數,而且必須是零。
  • 例如,如果金鑰 BLOB 是以 通道 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 值功能
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 函式來釋放句柄。

傳回值

如果函式成功,函式會傳回非零。

如果函式失敗,則會傳回零。 如需擴充錯誤資訊,請呼叫 getLastError

「NTE」前面加上的錯誤碼是由所使用的特定 CSP 所產生。 以下是一些可能的錯誤碼。

傳回碼 描述
ERROR_BUSY
如果私鑰匯入容器,而其他線程或 進程 使用此金鑰,某些 CSP 會設定此錯誤。
ERROR_INVALID_HANDLE
其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER
其中一個參數包含無效的值。 這通常是無效的指標。
NTE_BAD_ALGID
要匯入的 簡單金鑰 BLOB 不會使用預期的 金鑰交換演算法加密
NTE_BAD_DATA
此 CSP 不支援與要匯入的公鑰搭配運作的演算法,或嘗試匯入使用您其中一個公鑰以外的專案加密的會話金鑰。
NTE_BAD_FLAGS
指定的 dwFlags 參數無效。
NTE_BAD_TYPE
此 CSP 不支援金鑰 BLOB 類型,而且可能無效。
NTE_BAD_UID
hProv 參數不包含有效的內容句柄。
NTE_BAD_VER
金鑰 BLOB 版本號碼不符合 CSP 版本。 這通常表示必須升級 CSP。

言論

匯入 Hash-Based 訊息驗證碼 (HMAC) 金鑰時,呼叫端必須將匯入的密鑰識別為 PLAINTEXTKEYBLOB 類型,並在 aiKeyAlg 字段中設定適當的演演算法識別符,PUBLICKEYSTRUC BLOB 標頭。

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的任何 數據加密標準 (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 函式