Función CryptImportKey (wincrypt.h)

  • Artículo
Importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API cryptography Next Generation. Microsoft puede quitar esta API en futuras versiones.
 
La función CryptImportKey transfiere una clave criptográfica de un BLOB de clave a un proveedor de servicios criptográficos (CSP). Esta función se puede usar para importar una clave de sesiónde Schannel, una clave de sesión normal, una clave pública o un par de claves pública o privada. Para toda la clave pública, la clave o el par de claves se cifran.

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 BLOB PUBLICKEYSTRUC seguido de la clave cifrada. Esta clave BLOB se crea mediante la función CryptExportKey , ya sea en esta aplicación o en 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 según el tipo de CSP y el tipo de BLOB de clave que se va a importar:

  • Si la clave BLOB se cifra con el par de claves de intercambio de claves, por ejemplo, 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, 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 OPAQUEKEYBLOB cifrado o cualquier otro OPAQUEKEYBLOB específico del proveedor, este parámetro no se usa y debe establecerse en cero.
Nota Algunos CSP pueden modificar este parámetro como resultado de la operación. Las aplicaciones que posteriormente usan esta clave para otros fines deben llamar a la función CryptDuplicateKey para crear un identificador de clave duplicado. Cuando la aplicación haya terminado de usar el identificador, ábrala llamando a la función CryptDestroyKey .
 

[in] dwFlags

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

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

Valor Significado
CRYPT_EXPORTABLE
 La clave que se va a importar se vuelve a importar. Si no se usa esta marca, se produce un error en las llamadas a CryptExportKey con el identificador de clave.
CRYPT_OAEP
 Esta marca hace que el formato PKCS #1 versión 2 se compruebe con cifrado y descifrado RSA al importar SIMPLEBLOBs.
CRYPT_NO_SALT
 Se asigna un valor sin sal para una clave simétrica de 40 bits. Para obtener más información, consulte Funcionalidad de valor de sal.
CRYPT_USER_PROTECTED
 Si se establece esta marca, el CSP notifica al usuario a través de un cuadro de diálogo o algún otro método cuando se intentan usar esta clave determinadas acciones. El comportamiento preciso lo especifica el CSP o el tipo de CSP usado. Si el contexto del proveedor se adquirió con CRYPT_SILENT establecido, el uso de esta marca produce un error y el último error se establece en NTE_SILENT_CONTEXT.
CRYPT_IPSEC_HMAC_KEY
 Permite la importación de una clave RC2 superior a 16 bytes. Si no se establece esta marca, se producirá un error en las llamadas a la función CryptImportKey con claves RC2 mayores de 16 bytes y se devolverá una llamada a GetLastErrorNTE_BAD_DATA.

[out] phKey

Puntero a un valor 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.

Código devuelto Descripción
ERROR_BUSY
 Algunos CSP establecen este error si se importa una clave privada en un contenedor mientras otro subproceso o proceso usa esta clave.
ERROR_INVALID_HANDLE
 Uno de los parámetros especifica un identificador que no es válido.
ERROR_INVALID_PARAMETER
 Uno de los parámetros contiene un valor que no es válido. Suele ser un puntero que no es válido.
NTE_BAD_ALGID
 El BLOB de clave simple que se va a importar no se cifra con el algoritmo de intercambio de claves esperado.
NTE_BAD_DATA
 Este CSP no admite el algoritmo que funciona con la clave pública que se va a importar o se intentó importar una clave de sesión cifrada con algo distinto de una de las claves públicas.
NTE_BAD_FLAGS
 El parámetro dwFlags especificado no es válido.
NTE_BAD_TYPE
 Este CSP no admite el tipo blob de clave y, posiblemente, no es válido.
NTE_BAD_UID
 El parámetro hProv no contiene un identificador de contexto válido.
NTE_BAD_VER
 El número de versión de la clave BLOB no coincide con la versión de CSP. Normalmente, esto indica que es necesario actualizar el CSP.

Comentarios

Al importar una clave de código de autenticación de mensajes basado en hash (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 BLOB PUBLICKEYSTRUC .

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 es un PLAINTEXTKEYBLOB.

Puede usar el tipo PLAINTEXTKEYBLOB con cualquier algoritmo o tipo de combinación de teclas 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 sin formato.

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.

Nota Los algoritmos HMAC no tienen sus propios identificadores de algoritmo; use CALG_RC2 en su lugar. CRYPT_IPSEC_HMAC_KEY permite la importación de claves RC2 de más de 16 bytes.
 
Para cualquiera de las permutaciones de claves estándar de cifrado de datos (DES) que usan PLAINTEXTKEYBLOB, solo se puede importar el tamaño de clave completo, incluido el bit de paridad.

Se admiten los siguientes tamaños de clave.

Algoritmo Tamaño de clave admitido
CALG_DES 64 bits
CALG_3DES_112 128 bits
CALG_3DES 192 bits
 

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 Ejemplo de programa C: firma de un hash y comprobación de la firma hash. Para obtener código adicional que usa esta función, vea Programa C de ejemplo: Descifrado de 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

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado wincrypt.h
Library Advapi32.lib
Archivo DLL Advapi32.dll

Consulte también

CryptAcquireContext

CryptDestroyKey

CryptExportKey

Funciones de generación y intercambio de claves