Función CryptCreateHash (wincrypt.h)

Artículo
08/27/2023

Importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API cryptography Next Generation. Microsoft puede quitar esta API en futuras versiones.

La función CryptCreateHash inicia el hash de un flujo de datos. Crea y devuelve a la aplicación que realiza la llamada un identificador a un objeto hash del proveedor de servicios criptográficos (CSP). Este identificador se usa en llamadas posteriores a CryptHashData y CryptHashSessionKey para aplicar hash a las claves de sesión hash y a otros flujos de datos.

Sintaxis

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

Parámetros

[in] hProv

Identificador de un CSP creado por una llamada a CryptAcquireContext.

[in] Algid

Valor de ALG_ID que identifica el algoritmo hash que se va a usar.

Los valores válidos para este parámetro varían, en función del CSP que se use. Para obtener una lista de algoritmos predeterminados, vea Comentarios.

[in] hKey

Si el tipo de algoritmo hash es un hash con clave, como el código de autenticación de mensajes basado en hash (HMAC) o el algoritmo de código de autenticación de mensajes (MAC), la clave del hash se pasa en este parámetro. En el caso de los algoritmos sin clave, este parámetro debe establecerse en cero.

Para los algoritmos con clave, la clave debe ser para una clave de cifrado de bloque , como RC2, que tiene un modo de cifrado de encadenamiento de bloques de cifrado (CBC).

[in] dwFlags

Se define el siguiente valor de marca.

Valor	Significado
CRYPT_SECRETDIGEST 0x00000001	Esta marca no se usa.

[out] phHash

Dirección a la que la función copia un identificador en el nuevo objeto hash. Cuando haya terminado de usar el objeto hash, libere el identificador llamando a la función CryptDestroyHash .

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve TRUE.

Si se produce un error en la función, devuelve FALSE. Para obtener información de error extendida, llame a GetLastError.

Los códigos de error precedidos por NTE se generan mediante el CSP concreto que usa. En la tabla siguiente se muestran algunos de los posibles códigos de error.

Código devuelto	Descripción
ERROR_INVALID_HANDLE	Uno de los parámetros especifica un identificador que no es válido.
ERROR_INVALID_PARAMETER	Uno de los parámetros contiene un valor que no es válido. Suele ser un puntero que no es válido.
ERROR_NOT_ENOUGH_MEMORY	El sistema operativo se quedó sin memoria durante la operación.
NTE_BAD_ALGID	El parámetro Algid especifica un algoritmo que este CSP no admite.
NTE_BAD_FLAGS	El parámetro dwFlags es distinto de cero.
NTE_BAD_KEY	Algid especifica un algoritmo hash con clave, como CALG_MAC, y el parámetro hKey es cero o especifica un identificador de clave que no es válido. Este código de error también se devuelve si la clave es para un cifrado de secuencia o si el modo de cifrado es distinto de CBC.
NTE_NO_MEMORY	El CSP se quedó sin memoria durante la operación.

Comentarios

Para obtener una lista de los proveedores de servicios de Microsoft y los algoritmos que implementan, consulte Proveedores de servicios criptográficos de Microsoft.

El cálculo del hash real se realiza con las funciones CryptHashData y CryptHashSessionKey . Estos requieren un identificador para el objeto hash. Una vez agregados todos los datos al objeto hash, se puede realizar cualquiera de las siguientes operaciones:

El valor hash se puede recuperar mediante CryptGetHashParam.
Una clave de sesión se puede derivar mediante CryptDeriveKey.
El hash se puede firmar mediante CryptSignHash.
Una firma se puede comprobar mediante CryptVerifySignature.

Después de llamar a una de las funciones de esta lista, no se puede llamar a CryptHashData y CryptHashSessionKey .

Ejemplos

En el ejemplo siguiente se muestra cómo iniciar el hash de un flujo de datos. Crea y devuelve a la aplicación que realiza la llamada un identificador a un objeto hash. Este identificador se usa en llamadas posteriores a CryptHashData y CryptHashSessionKey para aplicar un algoritmo hash a cualquier flujo de datos. Para obtener un ejemplo que incluya el contexto completo de este ejemplo, vea Ejemplo C Program: Creating and Hashing a Session Key. Para obtener otro ejemplo que usa esta función, vea Programa C de ejemplo: Firma de un hash y Comprobación de la firma hash.

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wincrypt.h
Library	Advapi32.lib
Archivo DLL	Advapi32.dll