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 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.
[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 |
---|---|
|
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. |
|
Esta marca hace que el formato PKCS #1 versión 2 se compruebe con cifrado y descifrado RSA al importar SIMPLEBLOBs. |
|
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. |
|
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. |
|
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 |
---|---|
|
Algunos CSP establecen este error si se importa una clave privada en un contenedor mientras otro subproceso o proceso usa esta clave. |
|
Uno de los parámetros especifica un identificador que no es válido. |
|
Uno de los parámetros contiene un valor que no es válido. Suele ser un puntero que no es válido. |
|
El BLOB de clave simple que se va a importar no se cifra con el algoritmo de intercambio de claves esperado. |
|
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. |
|
El parámetro dwFlags especificado no es válido. |
|
Este CSP no admite el tipo blob de clave y, posiblemente, no es válido. |
|
El parámetro hProv no contiene un identificador de contexto válido. |
|
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.
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
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de