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

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

[in] dwDataLen

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

[in] hPubKey

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

  • 例如，如果金鑰 BLOB 使用金鑰交換金鑰組加密，則此參數可以是金鑰交換金鑰的句柄。
  • 例如，如果金鑰 BLOB 是以工作階段金鑰加密，例如加密 的 PRIVATEKEYBLOB，此參數會包含此工作階段金鑰的句柄。
  • 如果密鑰 BLOB 未加密，例如 PUBLICKEYBLOB，則不會使用此參數，而且必須是零。
  • 例如，如果金鑰 BLOB 是以安全通道 CSP 中的會話密鑰加密，例如加密的 OPAQUEKEYBLOB，則不會使用此參數，而且必須設定為零。
注意 某些 CSP 可能會因為作業而修改此參數。 後續將此金鑰用於其他用途的應用程式應該呼叫 CryptDuplicateKey 函式，以建立重複的密鑰句柄。 當應用程式使用完句柄時，呼叫 CryptDestroyKey 函 式來釋放它。
 

[in] dwFlags

目前只有在 PRIVATEKEYBLOB 形式的公開/私鑰組匯入 CSP 時才會使用。

此參數可以是下列其中一個值。

值 意義
CRYPT_EXPORTABLE
 匯入的金鑰最終會重新匯出。 如果未使用此旗標，則呼叫 CryptExportKey 且密鑰句柄失敗。
CRYPT_OAEP
 此旗標會在匯入 SIMPLEBLOB時，使用 RSA 加密和解密來檢查 PKCS #1 第 2 版格式。
CRYPT_NO_SALT
 無 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 所產生。 接下來有一些可能的錯誤碼。

傳回碼 Description
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。

備註

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

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 允許匯入 RC2 金鑰超過 16 個字節。
 
對於任何使用 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 [僅限傳統型應用程式]
目標平台 Windows
標頭 wincrypt.h
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

CryptAcquireContext

CryptDestroyKey

CryptExportKey

金鑰產生和 Exchange 函式