Función CryptVerifySignatureA (wincrypt.h)

Artículo
11/20/2024

importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API de 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 sesión de datos o al objeto hash.

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

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 de la pbSignature datos de firma.

[in] hPubKey

Identificador de la clave pública 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 debe usarse 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 ejecuta 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 datos en sí 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	El contexto del proveedor de servicios criptográficos (CSP) que se especificó cuando no se encontró el objeto hash.
NTE_NO_MEMORY	El CSP se quedó sin memoria durante la operación.

Observaciones

La función CryptVerifySignature completa el hash. Después de esta llamada, no se pueden agregar más datos al hash. Se producen errores en 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 va a comprobar una firma generada mediante una API de .NET Framework, debe intercambiar el orden de bytes de firma antes de llamar a la función de CryptVerifySignature para comprobar la firma.

Ejemplos

Para obtener un ejemplo que usa la función de CryptVerifySignature, vea Programa C de ejemplo: Firma de un hash y Comprobación de 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	wincrypt.h
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll