Funzione CryptVerifySignatureA (wincrypt.h)

Articolo
03/13/2024

Importante Questa API è deprecata. Il software nuovo e esistente deve iniziare a usare le API di nuova generazione di crittografia. Microsoft può rimuovere questa API nelle versioni future.

La funzione CryptVerifySignature verifica la firma di un oggetto hash.

Prima di chiamare questa funzione, è necessario chiamare CryptCreateHash per creare l'handle di un oggetto hash. CryptHashData o CryptHashSessionKey viene quindi usato per aggiungere i dati o le chiavi di sessione all'oggetto hash.

Al termine di CryptVerifySignature , è possibile chiamare solo CryptDestroyHash usando l'handle hHash .

Sintassi

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

Parametri

[in] hHash

Handle per l'oggetto hash da verificare.

[in] pbSignature

Indirizzo dei dati della firma da verificare.

[in] dwSigLen

Numero di byte nei dati della firma pbSignature .

[in] hPubKey

Handle per la chiave pubblica da usare per autenticare la firma. Questa chiave pubblica deve appartenere alla coppia di chiavi usata originariamente per creare la firma digitale.

[in] szDescription

Questo parametro non deve più essere usato e deve essere impostato su NULL per evitare vulnerabilità di sicurezza. Tuttavia, è ancora supportato per la compatibilità con le versioni precedenti nel provider di crittografia di base Microsoft.

[in] dwFlags

I valori di flag seguenti sono definiti.

Valore	Significato
CRYPT_NOHASHOID 0x00000001	Questo flag viene usato con i provider RSA. Quando si verifica la firma, l'identificatore dell'oggetto hash (OID) non deve essere presente o controllato. Se questo flag non è impostato, l'OID hash nella firma predefinita viene verificato come specificato nella definizione di DigestInfo in PKCS #7.
CRYPT_TYPE2_FORMAT 0x00000002	Questo flag non viene usato.
CRYPT_X931_FORMAT 0x00000004	Usare il supporto X.931 per la versione conforme a FIPS 186-2 di RSA (rDSA).

Valore restituito

Se la funzione ha esito positivo, il valore restituito è TRUE.

Se la funzione ha esito negativo, il valore restituito è FALSE. Per informazioni sull'errore estese, chiamare GetLastError.

I codici di errore preceduti da "NTE" vengono generati dal particolare CSP usato. Alcuni codici di errore possibili seguono.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Uno dei parametri specifica un handle non valido.
ERROR_INVALID_PARAMETER	Uno dei parametri contiene un valore non valido. Questo è più spesso un puntatore che non è valido.
NTE_BAD_FLAGS	Il parametro dwFlags è diverso da zero.
NTE_BAD_HASH	L'oggetto hash specificato dal parametro hHash non è valido.
NTE_BAD_KEY	Il parametro hPubKey non contiene un handle per una chiave pubblica valida.
NTE_BAD_SIGNATURE	La firma non è valida. Ciò potrebbe verificarsi perché i dati stessi sono stati modificati, la stringa di descrizione non corrisponde o la chiave pubblica errata è stata specificata da hPubKey. Questo errore può essere restituito anche se gli algoritmi di hashing o firma non corrispondono a quelli usati per creare la firma.
NTE_BAD_UID	Impossibile trovare il contesto del provider di servizi di crittografia specificato quando non è stato creato l'oggetto hash.
NTE_NO_MEMORY	Il provider di servizi di rete ha esaurito la memoria durante l'operazione.

Commenti

La funzione CryptVerifySignature completa l'hash. Dopo questa chiamata, non è possibile aggiungere altri dati all'hash. Le chiamate aggiuntive a CryptHashData o CryptHashSessionKey hanno esito negativo. Dopo aver eseguito l'applicazione con l'hash, è necessario chiamare CryptDestroyHash per eliminare l'oggetto hash.

Se si genera una firma usando le API .NET Framework e si tenta di verificarla usando la funzione CryptVerifySignature , la funzione avrà esito negativo e GetLastError restituirà NTE_BAD_SIGNATURE. Ciò è dovuto agli ordini di byte diversi tra l'API Win32 nativa e l'API .NET Framework.

L'API di crittografia nativa usa un ordine di byte little-endian mentre l'API .NET Framework usa un ordine di byte big-end. Se si verifica una firma generata tramite un'API .NET Framework, è necessario scambiare l'ordine di byte di firma prima di chiamare la funzione CryptVerifySignature per verificare la firma.

Esempio

Per un esempio che usa la funzione CryptVerifySignature , vedere Programma C di esempio: firma di un hash e verifica della firma hash.

Nota

L'intestazione wincrypt.h definisce CryptVerifySignature come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h
Libreria	Advapi32.lib
DLL	Advapi32.dll