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 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 de 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 el BCryptOpenAlgorithmProvider función 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 de pbSecret de . 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 siguiente valor.

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

Observaciones

En función 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 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 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, consulte WDK y Developer Tools.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

BCryptDestroyHash