Función CryptImportKey (wincrypt.h)

Sintaxis

BOOL CryptImportKey(
  [in]  HCRYPTPROV hProv,
  [in]  const BYTE *pbData,
  [in]  DWORD      dwDataLen,
  [in]  HCRYPTKEY  hPubKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

Parámetros

[in] hProv

Identificador de un CSP obtenido con la función CryptAcquireContext.

[in] pbData

Matriz BYTE que contiene un encabezado PUBLICKEYSTRUC de BLOB seguido de la clave cifrada. Esta clave BLOB se crea mediante la función CryptExportKey, ya sea en esta aplicación o mediante otra aplicación que posiblemente se ejecute en otro equipo.

[in] dwDataLen

Contiene la longitud, en bytes, del BLOB de clave.

[in] hPubKey

Identificador de la clave criptográfica que descifra la clave almacenada en pbData. Esta clave debe proceder del mismo CSP al que hace referencia hProv. El significado de este parámetro difiere en función del tipo csp y del tipo de BLOB de clave que se importa:

• Si la clave BLOB se cifra con la clave par de claves de intercambio, por ejemplo, un SIMPLEBLOB, este parámetro puede ser el identificador de la clave de intercambio de claves.
• Si la clave BLOB se cifra con una clave de sesión, por ejemplo, un PRIVATEKEYBLOB cifrado, este parámetro contiene el identificador de esta clave de sesión.
• Si la clave BLOB no está cifrada, por ejemplo, una PUBLICKEYBLOB, este parámetro no se usa y debe ser cero.
• Si la clave BLOB se cifra con una clave de sesión en un CSP de Schannel, por ejemplo, un OPAQUEKEYBLO B cifrado o cualquier otro OPAQUEKEYBLOB específico del proveedor, este parámetro no se usa y debe establecerse en cero.

[in] dwFlags

Actualmente solo se usa cuando un par de claves pública y privada en forma de PRIVATEKEYBLOB se importa en el CSP.

Este parámetro puede ser uno de los siguientes valores.

[out] phKey

Puntero a un valor de HCRYPTKEY que recibe el identificador de la clave importada. Cuando haya terminado de usar la clave, libere el identificador llamando a la función CryptDestroyKey.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.

Si se produce un error en la función, devuelve cero. Para obtener información de error extendida, llame a GetLastError.

Los códigos de error precedidos por "NTE" se generan mediante el CSP en particular que se usa. A continuación se indican algunos códigos de error posibles.

Observaciones

Al importar una clave de Hash-Based código de autenticación de mensajes (HMAC), el autor de la llamada debe identificar la clave importada como un tipo PLAINTEXTKEYBLOB y establecer el identificador de algoritmo adecuado en el campo aiKeyAlg del encabezado PUBLICKEYSTRUC BLOB.

La función CryptImportKey se puede usar para importar una clave de texto no cifrado para algoritmos simétricos; sin embargo, se recomienda que, para facilitar el uso, use la función CryptGenKey en su lugar. Al importar una clave de texto no cifrado, la estructura del BLOB de clave que se pasa en el parámetro pbData de es un PLAINTEXTKEYBLOB.

Puede usar el tipo PLAINTEXTKEYBLOB con cualquier algoritmo o tipo de combinación de claves compatible con el CSP en uso.

Para obtener un ejemplo de importación de una clave de texto no cifrado, vea Programa C de ejemplo: Importación de una clave de texto no cifrado.

En el ejemplo siguiente se muestra cómo puede establecer los campos de encabezado.

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;

La longitud de la clave se especifica en keyBlob.keyLength, seguido de los datos de clave reales.

Se admiten los siguientes tamaños de clave.

Ejemplos

En el ejemplo siguiente se muestra cómo importar una clave de un BLOB de clave. Para obtener un ejemplo completo de esta función, vea Programa C de ejemplo: Firma de un hash y Comprobación de la firma hash. Para obtener código adicional que use esta función, vea Programa C de ejemplo: Descifrar un archivo.

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

Requisitos

Consulte también

CryptAcquireContext

CryptDestroyKey

CryptExportKey

de generación de claves y funciones de Exchange de