Función BCryptGenerateKeyPair (bcrypt.h)

  • Artículo

La función BCryptGenerateKeyPair crea un par de claves pública y privada vacía. Después de crear una clave mediante esta función, puede usar la función BCryptSetProperty para establecer sus propiedades; sin embargo, la clave no se puede usar hasta que se llame a la función BCryptFinalizeKeyPair .

Sintaxis

NTSTATUS BCryptGenerateKeyPair(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [out]     BCRYPT_KEY_HANDLE *phKey,
  [in]      ULONG             dwLength,
  [in]      ULONG             dwFlags
);

Parámetros

[in, out] hAlgorithm

Identificador de un proveedor de algoritmos que admite la firma, el cifrado asimétrico o el acuerdo de clave. Este identificador debe haberse creado mediante la función BCryptOpenAlgorithmProvider .

[out] phKey

Puntero a un BCRYPT_KEY_HANDLE que recibe el identificador de la clave. Este identificador se usa en funciones posteriores que requieren una clave, como BCryptEncrypt. Este identificador debe liberarse cuando ya no sea necesario pasándolo a la función BCryptDestroyKey .

[in] dwLength

Longitud, en bits, de la clave. Los proveedores de algoritmos tienen restricciones de tamaño de clave diferentes para cada algoritmo asimétrico estándar.

Identificador de algoritmo Significado
BCRYPT_DH_ALGORITHM
 El tamaño de clave debe ser mayor o igual que 512 bits, menor o igual que 4096 bits, y debe ser un múltiplo de 64.
BCRYPT_DSA_ALGORITHM
 Antes de Windows 8, el tamaño de la clave debe ser mayor o igual que 512 bits, menor o igual que 1024 bits, y debe ser un múltiplo de 64.

A partir de Windows 8, el tamaño de la clave debe ser mayor o igual que 512 bits, menor o igual que 3072 bits, y debe ser un múltiplo de 64. El procesamiento de tamaños de clave menores o iguales que 1024 bits se adhiere a FIPS 186-2. El procesamiento de tamaños de clave mayores que 1024 y menor o igual que 3072 se adhiere a FIPS 186-3.
BCRYPT_ECDH_P256_ALGORITHM
 El tamaño de la clave debe ser de 256 bits.
BCRYPT_ECDH_P384_ALGORITHM
 El tamaño de la clave debe ser de 384 bits.
BCRYPT_ECDH_P521_ALGORITHM
 El tamaño de la clave debe ser de 521 bits.
BCRYPT_ECDSA_P256_ALGORITHM
 El tamaño de la clave debe ser de 256 bits.
BCRYPT_ECDSA_P384_ALGORITHM
 El tamaño de la clave debe ser de 384 bits.
BCRYPT_ECDSA_P521_ALGORITHM
 El tamaño de la clave debe ser de 521 bits.
BCRYPT_RSA_ALGORITHM
 El tamaño de clave debe ser mayor o igual que 512 bits, menor o igual que 16384 bits, y debe ser un múltiplo de 64.

[in] dwFlags

Conjunto de marcas que modifican el comportamiento de esta función. Actualmente no hay marcas definidas, por lo que este parámetro debe ser cero.

Valor devuelto

Devuelve un código de estado que indica el éxito o error de la función.

Entre los posibles códigos de retorno se incluyen, entre otros, los siguientes.

Código devuelto Descripción
STATUS_SUCCESS
 La función se realizó correctamente.
STATUS_INVALID_HANDLE
 El identificador del algoritmo en el parámetro hAlgorithm no es válido.
STATUS_INVALID_PARAMETER
 Uno o más parámetros no son válidos.
STATUS_NOT_SUPPORTED
 El proveedor especificado no admite el cifrado de claves asimétricas.

Comentarios

En función de los modos de procesador que admita un proveedor, se puede llamar a BCryptGenerateKeyPair desde el modo de usuario o el modo kernel. Los autores de llamadas en modo kernel se pueden ejecutar en PASSIVE_LEVELIRQL o DISPATCH_LEVEL IRQL. Si el nivel irQL actual está DISPATCH_LEVEL, el identificador proporcionado en el parámetro hAlgorithm debe haberse abierto mediante la marca BCRYPT_PROV_DISPATCH y los punteros pasados a la función BCryptGenerateKeyPair deben hacer referencia a la memoria no paginada (o bloqueada).

Para llamar a esta función en modo kernel, use Cng.lib, que forma parte del Kit de desarrollo de controladores (DDK). Windows Server 2008 y Windows Vista: Para llamar a esta función en modo kernel, use Ksecdd.lib.

Requisitos

Requisito Value
Cliente mínimo compatible Windows Vista [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado bcrypt.h
Library Bcrypt.lib
Archivo DLL Bcrypt.dll

Consulte también

BCryptDestroyKey