Función BCryptGenerateSymmetricKey (bcrypt.h)

La función BCryptGenerateSymmetricKey crea un objeto de clave para su uso con un algoritmo de cifrado de clave simétrica a partir 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 pasandolo 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 destruir 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 de 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 de pbSecret de .

[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_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 de algoritmo del parámetro hAlgorithm no es válido.
STATUS_INVALID_PARAMETER	Uno o varios parámetros no son válidos.

Observaciones

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 es DISPATCH_LEVEL, el identificador proporcionado en el parámetro hAlgorithm debe haberse abierto mediante la marca de 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	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