Funzione CryptVerifySignatureW (wincrypt.h)

Articolo
11/20/2024

Importante Questa API è deprecata. Il software nuovo ed esistente deve iniziare a usare API Di nuova generazione di crittografia. Microsoft potrebbe 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 dati o chiavi di sessione all'oggetto hash.

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

Sintassi

BOOL CryptVerifySignatureW(
  [in] HCRYPTHASH hHash,
  [in] const BYTE *pbSignature,
  [in] DWORD      dwSigLen,
  [in] HCRYPTKEY  hPubKey,
  [in] LPCWSTR    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

Vengono definiti i valori di flag seguenti.

Valore	Significato
CRYPT_NOHASHOID 0x00000001	Questo flag viene usato con i provider RSA. Quando si verifica la firma, l'hash identificatore di oggetto (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 utilizzato.
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 non riesce, il valore restituito viene FALSE. Per informazioni sugli errori estesi, chiamare GetLastError.

I codici di errore preceduti da "NTE" vengono generati dal CSP specifico in uso. Di seguito sono riportati alcuni possibili codici di errore.

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. Si tratta più spesso di un puntatore 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	Firma non valida. Ciò potrebbe essere dovuto al fatto che 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 hash o di firma non corrispondono a quelli usati per creare la firma.
NTE_BAD_UID	Impossibile trovare il contesto (CSP) del provider di servizi di crittografia specificato quando è stato creato l'oggetto hash.
NTE_NO_MEMORY	Il provider di servizi di configurazione ha esaurito la memoria durante l'operazione.

Osservazioni

La funzione CryptVerifySignature completa l'hash. Dopo questa chiamata, non è possibile aggiungere altri dati all'hash. Chiamate aggiuntive a CryptHashData o CryptHashSessionKey esito negativo. Al termine dell'applicazione con l'hash, è necessario chiamare CryptDestroyHash per eliminare definitivamente 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 ai diversi ordini di byte tra l'API Win32 nativa e l'API .NET Framework.

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

Esempi

Per un esempio che usa la funzione CryptVerifySignature, vedere esempio di programma C: 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	wincrypt.h
libreria	Advapi32.lib
dll	Advapi32.dll