CryptImportKey 函式 （wincrypt.h）

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，則此參數不會使用，而且必須設定為零。

[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 中指定，後面接著實際的索引鍵數據。

對於使用 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 函式