Función BCryptCreateHash (bcrypt.h)

Se llama a la función BCryptCreateHash para crear un objeto hash o código de autenticación de mensajes (MAC).

Sintaxis

NTSTATUS BCryptCreateHash(
  [in, out]      BCRYPT_ALG_HANDLE  hAlgorithm,
  [out]          BCRYPT_HASH_HANDLE *phHash,
  [out]          PUCHAR             pbHashObject,
  [in, optional] ULONG              cbHashObject,
  [in, optional] PUCHAR             pbSecret,
  [in]           ULONG              cbSecret,
  [in]           ULONG              dwFlags
);

Parámetros

[in, out] hAlgorithm

Identificador de un proveedor de algoritmos creado mediante la función BCryptOpenAlgorithmProvider . El algoritmo que se especificó cuando se creó el proveedor debe admitir la interfaz hash.

[out] phHash

Puntero a un valor de BCRYPT_HASH_HANDLE que recibe un identificador que representa el hash o el objeto MAC. Este identificador se usa en las funciones hash o MAC posteriores, como la función BCryptHashData . Cuando haya terminado de usar este identificador, suéltelo pasando a la función BCryptDestroyHash .

[out] pbHashObject

Puntero a un búfer que recibe el hash o el objeto MAC. El parámetro cbHashObject 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 hash o MAC para el algoritmo especificado.

Esta memoria solo se puede liberar después de que se destruya el identificador al que apunta el parámetro phHash .

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

[in, optional] cbHashObject

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

Si el valor de este parámetro es cero y el valor del parámetro pbHashObject 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, optional] pbSecret

Puntero a un búfer que contiene la clave que se va a usar para el hash o MAC. El parámetro cbSecret contiene el tamaño de este búfer. Esta clave solo se aplica a los algoritmos hash abiertos por la función BCryptOpenAlgorithmProvider mediante la marca BCRYPT_ALG_HANDLE_HMAC_FLAG . De lo contrario, establezca este parámetro en NULL.

[in] cbSecret

Tamaño, en bytes, del búfer pbSecret . Si no se usa ninguna clave, establezca este parámetro en cero.

[in] dwFlags

Marcas que modifican el comportamiento de la función. Puede ser cero o el valor siguiente.

Valor	Significado
BCRYPT_HASH_REUSABLE_FLAG	Crea un objeto hash reutilizable. El objeto se puede usar para una nueva operación hash inmediatamente después de llamar a BCryptFinishHash. Para obtener más información, consulte Creación de un hash con CNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 y Windows Vista: Esta marca no se admite.

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 hash especificado por el parámetro cbHashObject no es lo suficientemente grande como para contener el objeto hash.
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 de algoritmos especificado por el parámetro hAlgorithm no admite la interfaz hash.

Comentarios

Dependiendo de los modos de procesador que admita un proveedor, se puede llamar a BCryptCreateHash 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 BCryptCreateHash 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). Para obtener más información, vea WDK y Herramientas de desarrollo. 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

BCryptDestroyHash