CryptImportKey 函式（wincrypt.h）

發行項
07/16/2024

重要此 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

另請參閱

共用方式為

CryptImportKey 函式（wincrypt.h）

語法

參數

傳回值

言論

例子

要求

另請參閱

意見反應

其他資源

共用方式為

CryptImportKey 函式 （wincrypt.h）

語法

參數

傳回值

言論

例子

要求

另請參閱

意見反應

其他資源

CryptImportKey 函式（wincrypt.h）