Funzione CryptVerifyMessageSignature (wincrypt.h)

Articolo
08/27/2023

La funzione CryptVerifyMessageSignature verifica la firma di un messaggio firmato.

Questa funzione non deve essere utilizzata per verificare la firma di un messaggio scollegato. È consigliabile usare la funzione CryptVerifyDetachedMessageSignature per verificare la firma di un messaggio scollegato.

Sintassi

BOOL CryptVerifyMessageSignature(
  [in]            PCRYPT_VERIFY_MESSAGE_PARA pVerifyPara,
  [in]            DWORD                      dwSignerIndex,
  [in]            const BYTE                 *pbSignedBlob,
  [in]            DWORD                      cbSignedBlob,
  [out]           BYTE                       *pbDecoded,
  [in, out]       DWORD                      *pcbDecoded,
  [out, optional] PCCERT_CONTEXT             *ppSignerCert
);

Parametri

[in] pVerifyPara

Puntatore a una struttura CRYPT_VERIFY_MESSAGE_PARA che contiene parametri di verifica.

[in] dwSignerIndex

Indice della firma desiderata. Possono essere presenti più firme. CryptVerifyMessageSignature può essere chiamato ripetutamente, incrementando dwSignerIndex ogni volta. Impostare questo parametro su zero per il primo firmatario oppure se è presente un solo firmatario. Se la funzione restituisce FALSE e GetLastError restituisce CRYPT_E_NO_SIGNER, la chiamata precedente ha elaborato l'ultimo firmatario del messaggio.

[in] pbSignedBlob

Puntatore a un buffer contenente il messaggio firmato.

[in] cbSignedBlob

Dimensione, in byte, del buffer dei messaggi firmati.

[out] pbDecoded

Puntatore a un buffer per ricevere il messaggio decodificato.

Questo parametro può essere NULL se il messaggio decodificato non è necessario per l'elaborazione aggiuntiva o per impostare le dimensioni del messaggio a scopo di allocazione della memoria. Per altre informazioni, vedere Recupero di dati di lunghezza sconosciuta.

[in, out] pcbDecoded

Puntatore a un valore DWORD che specifica le dimensioni, in byte, del buffer pbDecoded . Quando la funzione viene restituita, questo DWORD contiene le dimensioni, in byte, del messaggio decodificato. Il messaggio decodificato non verrà restituito se questo parametro è NULL.

Nota Quando si elaborano i dati restituiti, le applicazioni devono usare le dimensioni effettive dei dati restituiti. Le dimensioni effettive possono essere leggermente inferiori alle dimensioni del buffer specificato nell'input. In caso di input, le dimensioni del buffer vengono in genere specificate sufficientemente grandi per garantire che i dati di output più grandi siano adatti al buffer. Nell'output la variabile a cui punta questo parametro viene aggiornata in modo da riflettere le dimensioni effettive dei dati copiati nel buffer.

[out, optional] ppSignerCert

Indirizzo di un puntatore della struttura CERT_CONTEXT che riceve il certificato del firmatario. Al termine dell'uso di questa struttura, liberarlo passando questo puntatore alla funzione CertFreeCertificateContext . Questo parametro può essere NULL se il certificato del firmatario non è necessario.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero. Ciò non significa necessariamente che la firma sia stata verificata. Nel caso di un messaggio scollegato, la variabile a cui punta pcbDecoded conterrà zero. In questo caso, questa funzione restituirà un valore diverso da zero, ma la firma non viene verificata. Per verificare la firma di un messaggio scollegato, usare la funzione CryptVerifyDetachedMessageSignature .

Se la funzione ha esito negativo, restituisce zero. Per informazioni sugli errori estesi, chiamare GetLastError.

Nella tabella seguente vengono illustrati i codici di errore restituiti più comunemente dalla funzione GetLastError .

Codice restituito	Descrizione
ERROR_MORE_DATA	Se il buffer specificato dal parametro pbDecoded non è sufficientemente grande da contenere i dati restituiti, la funzione imposta il codice ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie, in byte, nella variabile a cui punta il pcbDecoded.
E_INVALIDARG	Tipi di codifica di messaggi e certificati non validi. Attualmente sono supportati solo PKCS_7_ASN_ENCODING e X509_ASN_ENCODING_TYPE. CbSize non valido in *pVerifyPara.
CRYPT_E_UNEXPECTED_MSG_TYPE	Messaggio di crittografia non firmato.
CRYPT_E_NO_SIGNER	Il messaggio non ha firmatari o firmatari per l'oggetto dwSignerIndex specificato.
NTE_BAD_ALGID	Il messaggio è stato sottoposto a hashing e firmato usando un algoritmo sconosciuto o non supportato.
NTE_BAD_SIGNATURE	La firma del messaggio non è stata verificata.

Nota Gli errori delle funzioni chiamate CryptCreateHash, CryptHashData, CryptVerifySignature e CryptImportKey possono essere propagati a questa funzione.

Se la funzione ha esito negativo, GetLastError può restituire un errore di codifica/decodifica ASN.1 ( Abstract Syntax Notation One ). Per informazioni su questi errori, vedere Codifica ASN.1/Decodifica dei valori restituiti.

Commenti

Per un firmatario e un messaggio verificati, ppSignerCert viene aggiornato con il CERT_CONTEXT del firmatario. Deve essere liberato chiamando CertFreeCertificateContext. In caso contrario , ppSignerCert è impostato su NULL.

Per un messaggio che contiene solo certificati e CRL, pcbDecoded è impostato su NULL.

Esempio

Per un esempio che usa questa funzione, vedere Esempio di programma C: firma di un messaggio e verifica di una firma del messaggio.

Requisiti


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	Crypt32.lib
DLL	Crypt32.dll

Vedi anche

CryptSignMessage

CryptVerifyDetachedMessageSignature

Funzioni di messaggio semplificate

Condividi tramite