Función CryptGenKey (wincrypt.h)

Artículo
07/16/2024

importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API de Cryptography Next Generation. Microsoft puede quitar esta API en futuras versiones.

La función de CryptGenKey genera una clave de sesión de criptográfica aleatoria o un par de claves pública y privada . Se devuelve un identificador para la clave o el par de claves en phKey. Después, este identificador se puede usar según sea necesario con cualquier función cryptoAPI que requiera un identificador de clave.

La aplicación que realiza la llamada debe especificar el algoritmo al llamar a esta función. Dado que este tipo de algoritmo se mantiene agrupado con la clave, la aplicación no necesita especificar el algoritmo más adelante cuando se realizan las operaciones criptográficas reales.

Sintaxis

BOOL CryptGenKey(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

Parámetros

[in] hProv

Identificador de un proveedor de servicios criptográficos (CSP) creado por una llamada a CryptAcquireContext.

[in] Algid

Valor ALG_ID que identifica el algoritmo para el que se va a generar la clave. Los valores de este parámetro varían en función del CSP usado.

Para obtener ALG_ID valores que se usarán con el proveedor criptográfico base de Microsoft, consulte algoritmos de proveedor base.

Para obtener ALG_ID valores para usarlos con el proveedor criptográfico seguro de Microsoft o el proveedor criptográfico mejorado de Microsoft, consulte algoritmos de proveedor mejorados.

Para un CSP de Diffie-Hellman, use uno de los valores siguientes.

Valor	Significado
CALG_DH_EPHEM	Especifica una clave de Diffie-Hellman "Efímera".
CALG_DH_SF	Especifica una clave de Diffie-Hellman "Almacenar y reenviar".

Además de generar claves de sesión para algoritmos simétricos, esta función también puede generar pares de claves públicas y privadas. Cada cliente cryptoAPI generalmente posee dos pares de claves públicas y privadas. Para generar uno de estos pares de claves, establezca el parámetro Algid en uno de los valores siguientes.

Valor	Significado
AT_KEYEXCHANGE	Intercambio de claves
AT_SIGNATURE	Firma digital

Nota Cuando se especifican especificaciones clave AT_KEYEXCHANGE y AT_SIGNATURE, los identificadores de algoritmo que se usan para generar la clave dependen del proveedor utilizado. Como resultado, para estas especificaciones clave, los valores devueltos de CryptGetKeyParam (cuando se especifica el parámetro KP_ALGID) dependen del proveedor usado. Para determinar qué identificador de algoritmo usan los distintos proveedores para las especificaciones de clave AT_KEYEXCHANGE y AT_SIGNATURE, consulte ALG_ID.

[in] dwFlags

Especifica el tipo de clave generada. Los tamaños de una clave de sesión, la clave de firma RSA y la clave RSA claves de intercambio se pueden establecer cuando se genera la clave. El tamaño de clave, que representa la longitud del módulo de clave en bits, se establece con los 16 bits superiores de este parámetro. Por lo tanto, si se va a generar una clave de firma RSA de 2048 bits, el valor 0x08000000 se combina con cualquier otro dwFlags valor predefinido con una operación or bit abit. Los 16 bits superiores de 0x08000000 son 0x0800 o decimales 2048. El valor de RSA1024BIT_KEY se puede usar para especificar una clave RSA de 1024 bits.

Debido a la modificación de las restricciones de control de exportación, el CSP predeterminado y la longitud predeterminada de la clave pueden cambiar entre las versiones del sistema operativo. Es importante que tanto el cifrado como el descifrado usen el mismo CSP y que la longitud de la clave se establezca explícitamente mediante el parámetro dwFlags para garantizar la interoperabilidad en distintas plataformas del sistema operativo.

En concreto, el proveedor de servicios criptográficos rsa completo predeterminado es el proveedor criptográfico seguro RSA de Microsoft. La firma de DSS predeterminada Diffie-Hellman proveedor de servicios criptográficos es el proveedor de servicios criptográficos de DSS mejorado de Microsoft Diffie-Hellman. Cada uno de estos CSP tiene una longitud de clave simétrica de 128 bits predeterminada para RC2 y RC4 y una longitud de clave predeterminada de 1024 bits para los algoritmos de clave pública.

Si los 16 bits superiores son cero, se genera el tamaño de clave predeterminado. Si se especifica una clave mayor o menor que la mínima, se produce un error en la llamada con el código ERROR_INVALID_PARAMETER.

En la tabla siguiente se enumeran las longitudes mínimas, predeterminadas y máximas de firma y clave de intercambio a partir de Windows XP.

Tipo de clave y proveedor	Longitud mínima	Longitud predeterminada	Longitud máxima
Proveedor base RSA Signature y ExchangeKeys	384	512	16,384
Proveedores seguros y mejorados de RSA Claves de firma y intercambio	384	1,024	16,384
Proveedores base de DSS Claves de firma	512	1,024	1,024
Proveedores base de DSS Claves de intercambio	No aplicable	No aplicable	No aplicable
Proveedores base DSS/DH Claves de firma	512	1,024	1,024
Proveedores base DSS/DH Claves de intercambio	512	512	1,024
Proveedores mejorados de DSS/DH Claves de firma	512	1,024	1,024
Proveedores mejorados de DSS/DH Claves de intercambio	512	1,024	4,096

Para obtener longitudes de clave de sesión, consulte CryptDeriveKey.

Para obtener más información sobre las claves generadas mediante proveedores de Microsoft, consulte Proveedores de servicios criptográficos de Microsoft.

Los 16 bits inferiores de este parámetro pueden ser cero o una combinación de uno o varios de los valores siguientes.

Valor	Significado
CRYPT_ARCHIVABLE	Si se establece esta marca, la clave se puede exportar hasta que se cierre su identificador mediante una llamada a CryptDestroyKey. Esto permite exportar las claves recién generadas al crearse para archivar o recuperar claves. Una vez cerrado el identificador, la clave ya no se puede exportar.
CRYPT_CREATE_IV	Esta marca no se usa.
CRYPT_CREATE_SALT	Si se establece esta marca, a la clave se le asigna un valor aleatorio sal automáticamente. Puede recuperar este valor de sal mediante la función de CryptGetKeyParam con el parámetro dwParam establecido en KP_SALT. Si no se establece esta marca, la clave recibe un valor de sal de cero. Cuando se exportan las claves con valores de sal distinto de cero (a través de CryptExportKey ), también se debe obtener y mantener con la clave BLOB de .
CRYPT_DATA_KEY	Esta marca no se usa.
CRYPT_EXPORTABLE	Si se establece esta marca, la clave se puede transferir fuera del CSP a un BLOB de clave mediante la función CryptExportKey. Dado que las claves de sesión suelen ser exportables, esta marca normalmente debe establecerse cuando se crean. Si no se establece esta marca, la clave no se puede exportar. Para una clave de sesión, esto significa que la clave solo está disponible en la sesión actual y solo la aplicación que creó podrá usarla. Para un par de claves pública o privada , esto significa que la clave privada no se puede transportar ni realizar una copia de seguridad. Esta marca solo se aplica a la clave de sesión y blobs de clave privada. No se aplica a las claves públicas, que siempre se pueden exportar.
CRYPT_FORCE_KEY_PROTECTION_HIGH	Esta marca especifica la protección de clave segura. Cuando se establece esta marca, se solicita al usuario que escriba una contraseña para la clave cuando se cree la clave. Se pedirá al usuario que escriba la contraseña cada vez que se use esta clave. Esta marca solo la usan los CSP proporcionados por Microsoft. Los CSP de terceros definirán su propio comportamiento para la protección segura de claves. Si se especifica esta marca, se produce el mismo resultado que llamar a esta función con la marca CRYPT_USER_PROTECTED cuando se especifica protección de clave segura en el registro del sistema. Si se especifica esta marca y el identificador de proveedor en el parámetro hProv se creó mediante la marca CRYPT_VERIFYCONTEXT o CRYPT_SILENT, esta función establecerá el último error en NTE_SILENT_CONTEXT y devolverá cero. Windows Server 2003 y Windows XP: Esta marca no se admite.
CRYPT_KEK	Esta marca no se usa.
CRYPT_INITIATOR	Esta marca no se usa.
CRYPT_NO_SALT	Esta marca especifica que no se asigna ningún valor de sal para un clave simétrica de cuarenta bits. Para obtener más información, consulte funcionalidad de valor de sal.
CRYPT_ONLINE	Esta marca no se usa.
CRYPT_PREGEN	Esta marca especifica una generación inicial de claves de Diffie-Hellman o DSS. Esta marca solo es útil con los CSP de Diffie-Hellman y DSS. Cuando se usa, se usará una longitud de clave predeterminada a menos que se especifique una longitud de clave en los 16 bits superiores del parámetro dwFlags . Si los parámetros que implican longitudes de clave se establecen en una clave PREGEN Diffie-Hellman o DSS mediante CryptSetKeyParam, las longitudes de clave deben ser compatibles con la longitud de clave establecida aquí.
CRYPT_RECIPIENT	Esta marca no se usa.
CRYPT_SF	Esta marca no se usa.
CRYPT_SGCKEY	Esta marca no se usa.
CRYPT_USER_PROTECTED	Si se establece esta marca, se notifica al usuario a través de un cuadro de diálogo u otro método cuando determinadas acciones intentan usar esta clave. El comportamiento preciso lo especifica el CSP que se usa. Si el contexto del proveedor se abrió con el conjunto de marcas CRYPT_SILENT, el uso de esta marca provoca un error y el último error se establece en NTE_SILENT_CONTEXT.
CRYPT_VOLATILE	Esta marca no se usa.

[out] phKey

Dirección a la que la función copia el identificador de la clave recién generada. Cuando haya terminado de usar la clave, elimine el identificador de la clave llamando a la función CryptDestroyKey.

Valor devuelto

Devuelve un valor distinto de cero si es correcto o cero de lo contrario.

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 enumeran algunos códigos de error posibles.

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.
NTE_BAD_ALGID	El parámetro Algid especifica un algoritmo que este CSP no admite.
NTE_BAD_FLAGS	El parámetro dwFlags contiene un valor que no es válido.
NTE_BAD_UID	El parámetro hProv no contiene un identificador de contexto válido.
NTE_FAIL	Error en la función de alguna manera inesperada.
NTE_SILENT_CONTEXT	El proveedor no pudo realizar la acción porque el contexto se adquirió como silencioso.

Observaciones

Si las claves se generan para cifrado de bloques simétricos , la clave, de forma predeterminada, se configura en modo de encadenamiento de bloques de cifrado (CBC) con un vector de inicialización de cero. Este modo de cifrado proporciona un buen método predeterminado para el cifrado masivo de datos. Para cambiar estos parámetros, use la función CryptSetKeyParam.

Para elegir una longitud de clave de adecuada, se recomiendan los métodos siguientes:

Enumere los algoritmos que admite el CSP y obtenga las longitudes máximas y mínimas de clave para cada algoritmo. Para ello, llame a CryptGetProvParam con PP_ENUMALGS_EX.
Use las longitudes mínimas y máximas para elegir una longitud de clave adecuada. No siempre es aconsejable elegir la longitud máxima porque esto puede provocar problemas de rendimiento.
Después de elegir la longitud de clave deseada, use los 16 bits superiores del parámetro dwFlags de para especificar la longitud de la clave.

Ejemplos

En el ejemplo siguiente se muestra la creación de una clave de sesión aleatoria. Para obtener un ejemplo que incluya el contexto completo de este ejemplo, vea Programa C de ejemplo: Cifrado de un archivo. Para obtener otro ejemplo que use esta función, vea Programa C de ejemplo: Descifrar un archivo.

//-------------------------------------------------------------------
//  Declare the handle to the key.
HCRYPTKEY hKey; 
//-------------------------------------------------------------------
//  This example assumes that a cryptographic context 
//  has been acquired, and that it is stored in hCryptProv.
//---------------------------------------------------------------
//  Create a random session key. 

 if(CryptGenKey(
          hCryptProv, 
          ENCRYPT_ALGORITHM, 
          KEYLENGTH | CRYPT_EXPORTABLE, 
          &hKey))
 {
         printf("A session key has been created.\n");
 } 
 else
 {
          printf("Error during CryptGenKey.\n"); 
          exit(1);
 }
//-------------------------------------------------------------------
//  The key created can be exported into a key BLOB that can be
//  written to a file.
//  ...
//  When you have finished using the key, free the resource.
if (!CryptDestroyKey(hKey))
{
          printf("Error during CryptDestroyKey.\n"); 
          exit(1);
}

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	wincrypt.h
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll