Función CryptExportKey (wincrypt.h)

Artículo
08/27/2023

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 CryptExportKey exporta una clave criptográfica o un par de claves de un proveedor de servicios criptográficos (CSP) de forma segura.

Se pasa un identificador a la clave que se va a exportar a la función y la función devuelve una clave BLOB. Este BLOB de clave se puede enviar a través de un transporte no seguro o almacenarse en una ubicación de almacenamiento no segura. Esta función puede exportar una clave de sesión de Schannel , una clave de sesión normal, una clave pública o un par de claves pública o privada. El blob clave que se va a exportar es inútil hasta que el destinatario deseado usa la función CryptImportKey en él para importar la clave o el par de claves en el CSP de un destinatario.

Sintaxis

BOOL CryptExportKey(
  [in]      HCRYPTKEY hKey,
  [in]      HCRYPTKEY hExpKey,
  [in]      DWORD     dwBlobType,
  [in]      DWORD     dwFlags,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen
);

Parámetros

[in] hKey

Identificador de la clave que se va a exportar.

[in] hExpKey

Identificador de una clave criptográfica del usuario de destino. Los datos de clave dentro de la clave exportada BLOB se cifran mediante esta clave. Esto garantiza que solo el usuario de destino pueda usar la clave BLOB. Tanto hExpKey como hKey deben proceder del mismo CSP.

Normalmente, esta es la clave pública de intercambio de claves del usuario de destino. Sin embargo, algunos protocolos de algunos CSP requieren que se use una clave de sesión que pertenezca al usuario de destino para este fin.

Si el tipo de BLOB de clave especificado por dwBlobType es PUBLICKEYBLOB, este parámetro no se usa y debe establecerse en cero.

Si el tipo de BLOB de clave especificado por dwBlobType es PRIVATEKEYBLOB, normalmente es un identificador de una clave de sesión que se va a usar para cifrar la clave BLOB. Algunos CSP permiten que este parámetro sea cero, en cuyo caso la aplicación debe cifrar manualmente el BLOB de clave privada para protegerlo.

Para determinar cómo responden los proveedores de servicios criptográficos de Microsoft a este parámetro, consulte las secciones BLOB de clave privada de proveedores de servicios criptográficos de Microsoft.

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] dwBlobType

Especifica el tipo de blob de clave que se va a exportar en pbData. Debe ser una de las siguientes constantes, como se describe en Almacenamiento de claves criptográficas y Exchange.

Valor	Significado
OPAQUEKEYBLOB	Se usa para almacenar claves de sesión en un CSP de Schannel o en cualquier otro formato específico del proveedor. OPAQUEKEYBLOBs no se pueden transferir y se deben usar en el CSP que generó el BLOB.
PRIVATEKEYBLOB	Se usa para transportar pares de claves públicas y privadas.
PUBLICKEYBLOB	Se usa para transportar claves públicas.
SIMPLEBLOB	Se usa para transportar claves de sesión.
PLAINTEXTKEYBLOB	UN PLAINTEXTKEYBLOB que se usa para exportar cualquier clave compatible con el CSP en uso.
SYMMETRICWRAPKEYBLOB	Se usa para exportar e importar una clave simétrica ajustada con otra clave simétrica. La clave ajustada real tiene el formato especificado en el estándar RFC 3217 de IETF.

[in] dwFlags

Especifica opciones adicionales para la función. Este parámetro puede ser cero o una combinación de uno o varios de los valores siguientes.

Valor	Significado
CRYPT_BLOB_VER3 0x00000080	Esta marca hace que esta función exporte la versión 3 de un tipo BLOB.
CRYPT_DESTROYKEY 0x00000004	Esta marca destruye la clave original en OPAQUEKEYBLOB. Esta marca solo está disponible en los CSP de Schannel.
CRYPT_OAEP 0x00000040	Esta marca hace que el formato PKCS #1 versión 2 se cree con el cifrado y el descifrado RSA al exportar SIMPLEBLOBs.
CRYPT_SSL2_FALLBACK 0x00000002	Los ocho primeros bytes del relleno del bloque de cifrado RSA deben establecerse en 0x03 en lugar de en datos aleatorios. Esto evita los ataques de reversión de versiones y se describe en la especificación SSL3. Esta marca solo está disponible para los CSP de Schannel.
CRYPT_Y_ONLY 0x00000001	Esta marca no se usa.

[out] pbData

Puntero a un búfer que recibe los datos blob clave . El formato de este BLOB varía en función del tipo BLOB solicitado en el parámetro dwBlobType . Para obtener el formato de PRIVATEKEYBLOBs, PUBLICKEYBLOBs y SIMPLEBLOBs, consulte Blobs de clave de proveedor base.

Si este parámetro es NULL, el tamaño de búfer necesario se coloca en el valor al que apunta el parámetro pdwDataLen . Para obtener más información, vea Recuperación de datos de longitud desconocida.

[in, out] pdwDataLen

Puntero a un valor DWORD que, en la entrada, contiene el tamaño, en bytes, del búfer al que apunta el parámetro pbData . Cuando se devuelve la función, este valor contiene el número de bytes almacenados en el búfer.

Nota Al procesar los datos devueltos en el búfer, las aplicaciones deben usar el tamaño real de los datos devueltos. El tamaño real puede ser ligeramente menor que el tamaño del búfer especificado en la entrada. En la entrada, los tamaños de búfer suelen especificarse lo suficientemente grandes como para garantizar que los datos de salida más grandes posibles se ajusten al búfer. En la salida, la variable a la que apunta este parámetro se actualiza para reflejar el tamaño real de los datos copiados en el búfer.

Para recuperar el tamaño necesario del búfer pbData , pase NULL para pbData. El tamaño de búfer necesario se colocará en el valor al que apunta este parámetro.

Valor devuelto

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

Si se produce un error en la función, devuelve cero (FALSE). 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. En la tabla siguiente se muestran algunos de los posibles códigos de error.

Código devuelto	Descripción
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.
ERROR_MORE_DATA	Si el búfer especificado por el parámetro pbData no es lo suficientemente grande como para contener los datos devueltos, la función establece el código ERROR_MORE_DATA y almacena el tamaño de búfer necesario, en bytes, en la variable a la que apunta pdwDataLen.
NTE_BAD_DATA	Este CSP no admite el algoritmo que funciona con la clave pública que se va a exportar o se intentó exportar una clave de sesión cifrada con algo distinto de una de las claves públicas.
NTE_BAD_FLAGS	El parámetro dwFlags es distinto de cero.
NTE_BAD_KEY	Una o ambas claves especificadas por hKey y hExpKey no son válidas.
NTE_BAD_KEY_STATE	No tiene permiso para exportar la clave. Es decir, cuando se creó la clave hKey , no se especificó la marca CRYPT_EXPORTABLE.
NTE_BAD_PUBLIC_KEY	El tipo BLOB de clave especificado por dwBlobType es PUBLICKEYBLOB, pero hExpKey no contiene un identificador de clave pública.
NTE_BAD_TYPE	El parámetro dwBlobType especifica un tipo BLOB desconocido.
NTE_BAD_UID	No se encuentra el contexto de CSP que se especificó cuando se creó la clave hKey .
NTE_NO_KEY	Se exporta una clave de sesión y el parámetro hExpKey no especifica una clave pública.

Comentarios

Para cualquiera de las permutaciones de clave DES que usan un PLAINTEXTKEYBLOB, solo se puede exportar 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 exportar una clave criptográfica o un par de claves de forma más segura. En este ejemplo se supone que se ha adquirido un contexto criptográfico y que hay disponible una clave pública para la exportación. Para obtener un ejemplo que incluya el contexto completo para usar esta función, vea Programa C de ejemplo: Firma de un hash y Comprobación de la firma hash. Para obtener otro ejemplo que use esta función, vea Ejemplo de programa C: exportación de una clave de sesión.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>

BOOL GetExportedKey(
    HCRYPTKEY hKey, 
    DWORD dwBlobType,
    LPBYTE *ppbKeyBlob, 
    LPDWORD pdwBlobLen)
{
    DWORD dwBlobLength;
    *ppbKeyBlob = NULL;
    *pdwBlobLen = 0;

    // Export the public key. Here the public key is exported to a 
    // PUBLICKEYBLOB. This BLOB can be written to a file and
    // sent to another user.

    if(CryptExportKey(   
        hKey,    
        NULL,    
        dwBlobType,
        0,    
        NULL, 
        &dwBlobLength)) 
    {
        printf("Size of the BLOB for the public key determined. \n");
    }
    else
    {
        printf("Error computing BLOB length.\n");
        return FALSE;
    }

    // Allocate memory for the pbKeyBlob.
    if(*ppbKeyBlob = (LPBYTE)malloc(dwBlobLength)) 
    {
        printf("Memory has been allocated for the BLOB. \n");
    }
    else
    {
        printf("Out of memory. \n");
        return FALSE;
    }

    // Do the actual exporting into the key BLOB.
    if(CryptExportKey(   
        hKey, 
        NULL,    
        dwBlobType,    
        0,    
        *ppbKeyBlob,    
        &dwBlobLength))
    {
        printf("Contents have been written to the BLOB. \n");
        *pdwBlobLen = dwBlobLength;
    }
    else
    {
        printf("Error exporting key.\n");
        free(*ppbKeyBlob);
        *ppbKeyBlob = NULL;

        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

CryptImportKey

Funciones de generación y intercambio de claves

Compartir a través de

Función CryptExportKey (wincrypt.h)

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplos

Requisitos

Consulte también

Comentarios

Recursos adicionales