Función BCryptGenerateSymmetricKey (bcrypt.h)

  • Artículo

La función BCryptGenerateSymmetricKey crea un objeto de clave para su uso con un algoritmo de cifrado de clave simétrica de una clave proporcionada.

Sintaxis

NTSTATUS BCryptGenerateSymmetricKey(
  [in, out]       BCRYPT_ALG_HANDLE hAlgorithm,
  [out]           BCRYPT_KEY_HANDLE *phKey,
  [out, optional] PUCHAR            pbKeyObject,
  [in]            ULONG             cbKeyObject,
  [in]            PUCHAR            pbSecret,
  [in]            ULONG             cbSecret,
  [in]            ULONG             dwFlags
);

Parámetros

[in, out] hAlgorithm

Identificador de un proveedor de algoritmos creado con la función BCryptOpenAlgorithmProvider . El algoritmo especificado cuando se creó el proveedor debe admitir el cifrado de claves simétricas.

[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 .

[out, optional] pbKeyObject

Puntero a un búfer que recibe el objeto de clave. El parámetro cbKeyObject contiene el tamaño de este búfer. El tamaño necesario de este búfer se puede obtener llamando a la función BCryptGetProperty para obtener la propiedad BCRYPT_OBJECT_LENGTH . Esto proporcionará el tamaño del objeto de clave para el algoritmo especificado.

Esta memoria solo se puede liberar después de que se destruya el identificador de clave phKey .

Si el valor de este parámetro es NULL y el valor del parámetro cbKeyObject es cero, esta función asigna y libera la memoria del objeto de clave. Windows 7: Esta funcionalidad de administración de memoria está disponible a partir de Windows 7.

[in] cbKeyObject

Tamaño, en bytes, del búfer pbKeyObject .

Si el valor de este parámetro es cero y el valor del parámetro pbKeyObject es NULL, esta función asigna y libera la memoria del objeto de clave. Windows 7: Esta funcionalidad de administración de memoria está disponible a partir de Windows 7.

[in] pbSecret

Puntero a un búfer que contiene la clave desde la que se va a crear el objeto de clave. El parámetro cbSecret contiene el tamaño de este búfer. Normalmente, se trata de un hash de una contraseña o de otros datos reproducibles. Si los datos pasados superan el tamaño de la clave de destino, los datos se truncarán y se omitirá el exceso.

Nota Se recomienda encarecidamente que las aplicaciones pasen el número exacto de bytes requeridos por la clave de destino.
 

[in] cbSecret

Tamaño, en bytes, del búfer pbSecret .

[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_BUFFER_TOO_SMALL
 El tamaño del objeto de clave especificado por el parámetro cbKeyObject no es lo suficientemente grande como para contener el objeto de clave.
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.

Comentarios

En función de los modos de procesador que admita un proveedor, se puede llamar a BCryptGenerateSymmetricKey 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 de IRQL actual está DISPATCH_LEVEL, el identificador proporcionado en el parámetro hAlgorithm debe haberse abierto con la marca BCRYPT_PROV_DISPATCH y los punteros pasados a la función BCryptGenerateSymmetricKey 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