Función CryptVerifySignatureA (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 CryptVerifySignature comprueba la firma de un objeto hash.

Antes de llamar a esta función, se debe llamar a CryptCreateHash para crear el identificador de un objeto hash. CryptHashData o CryptHashSessionKey se usa para agregar claves de datos o de sesión al objeto hash.

Una vez completado CryptVerifySignature , solo se puede llamar a CryptDestroyHash mediante el identificador hHash .

Sintaxis

BOOL CryptVerifySignatureA(
  [in] HCRYPTHASH hHash,
  [in] const BYTE *pbSignature,
  [in] DWORD      dwSigLen,
  [in] HCRYPTKEY  hPubKey,
  [in] LPCSTR     szDescription,
  [in] DWORD      dwFlags
);

Parámetros

[in] hHash

Identificador del objeto hash que se va a comprobar.

[in] pbSignature

Dirección de los datos de firma que se van a comprobar.

[in] dwSigLen

Número de bytes en los datos de firma pbSignature .

[in] hPubKey

Identificador de la clave pública que se va a usar para autenticar la firma. Esta clave pública debe pertenecer al par de claves que se usó originalmente para crear la firma digital.

[in] szDescription

Este parámetro ya no se debe usar y debe establecerse en NULL para evitar vulnerabilidades de seguridad. Sin embargo, todavía se admite para la compatibilidad con versiones anteriores en el proveedor criptográfico base de Microsoft.

[in] dwFlags

Se definen los siguientes valores de marca.

Valor	Significado
CRYPT_NOHASHOID 0x00000001	Esta marca se usa con proveedores RSA. Al comprobar la firma, no se espera que el identificador de objeto hash (OID) esté presente o comprobado. Si no se establece esta marca, el OID hash de la firma predeterminada se comprueba como se especifica en la definición de DigestInfo en PKCS #7.
CRYPT_TYPE2_FORMAT 0x00000002	Esta marca no se usa.
CRYPT_X931_FORMAT 0x00000004	Use la compatibilidad con X.931 para la versión compatible con FIPS 186-2 de RSA (rDSA).

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es TRUE.

Si se produce un error en la función, el valor devuelto es 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. A continuación se indican algunos códigos de error posibles.

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.
NTE_BAD_FLAGS	El parámetro dwFlags es distinto de cero.
NTE_BAD_HASH	El objeto hash especificado por el parámetro hHash no es válido.
NTE_BAD_KEY	El parámetro hPubKey no contiene un identificador para una clave pública válida.
NTE_BAD_SIGNATURE	La firma no era válida. Esto puede deberse a que los propios datos han cambiado, la cadena de descripción no coincide o la clave pública incorrecta se especificó mediante hPubKey. Este error también se puede devolver si los algoritmos hash o de firma no coinciden con los usados para crear la firma.
NTE_BAD_UID	No se encuentra el contexto del proveedor de servicios criptográficos (CSP) especificado cuando se creó el objeto hash.
NTE_NO_MEMORY	El CSP se quedó sin memoria durante la operación.

Comentarios

La función CryptVerifySignature completa el hash. Después de esta llamada, no se pueden agregar más datos al hash. Se produce un error en las llamadas adicionales a CryptHashData o CryptHashSessionKey . Una vez finalizada la aplicación con el hash, se debe llamar a CryptDestroyHash para destruir el objeto hash.

Si genera una firma mediante las API de .NET Framework e intenta comprobarla mediante la función CryptVerifySignature , se producirá un error en la función y GetLastError devolverá NTE_BAD_SIGNATURE. Esto se debe a los distintos pedidos de bytes entre la API nativa de Win32 y la API de .NET Framework.

La API de criptografía nativa usa el orden de bytes little-endian, mientras que la API de .NET Framework usa el orden de bytes big-endian. Si está comprobando una firma generada mediante una API de .NET Framework, debe intercambiar el orden de bytes de firma antes de llamar a la función CryptVerifySignature para comprobar la firma.

Ejemplos

Para obtener un ejemplo en el que se usa la función CryptVerifySignature , vea El programa C de ejemplo: Firmar un hash y comprobar la firma hash.

Nota

El encabezado wincrypt.h define CryptVerifySignature como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

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