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, no se puede usar la clave hasta que se llama 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 pasandolo 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 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 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 inferiores o iguales a 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 clave debe ser de 256 bits.
BCRYPT_ECDH_P384_ALGORITHM
 El tamaño de clave debe ser de 384 bits.
BCRYPT_ECDH_P521_ALGORITHM
 El tamaño de clave debe ser de 521 bits.
BCRYPT_ECDSA_P256_ALGORITHM
 El tamaño de clave debe ser de 256 bits.
BCRYPT_ECDSA_P384_ALGORITHM
 El tamaño de clave debe ser de 384 bits.
BCRYPT_ECDSA_P521_ALGORITHM
 El tamaño de 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 se definen marcas, 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 códigos de retorno posibles se incluyen, entre otros, los siguientes.

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

Observaciones

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 es 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 Valor
cliente mínimo admitido Windows Vista [aplicaciones de escritorio | Aplicaciones para UWP]
servidor mínimo admitido Windows Server 2008 [aplicaciones de escritorio | Aplicaciones para UWP]
de la plataforma de destino de Windows
encabezado de bcrypt.h
biblioteca de Bcrypt.lib
DLL de Bcrypt.dll

Consulte también

BCryptDestroyKey