Funzione DecryptMessage (Generale)

Articolo
09/02/2023

La funzione DecryptMessage (Generale) decrittografa un messaggio. Alcuni pacchetti non crittografano e decrittografano i messaggi, ma invece eseguono e controllano un hash di integrità.

Il provider di supporto per la sicurezza del digest fornisce la riservatezza della crittografia e della decrittografia per i messaggi scambiati tra client e server solo come meccanismo SASL.

Questa funzione viene usata anche con Schannel SSP per segnalare una richiesta da un mittente di messaggi per una rinegoziazione (redo) degli attributi di connessione o per un arresto della connessione.

Nota

EncryptMessage (Generale) e DecryptMessage (Generale) possono essere chiamati contemporaneamente da due thread diversi in un singolo contesto di interfaccia del provider di supporto della sicurezza (SSPI) se un thread sta crittografando e l'altro sta decrittografando. Se più thread crittografa o più thread decrittografa, ogni thread deve ottenere un contesto univoco.

Per informazioni sull'uso di questa funzione con un provider di servizi di rete specifico, vedere gli argomenti seguenti.

Argomento	Descrizione
DecryptMessage (Digest)	Decrittografa un messaggio usando Digest.
DecryptMessage (Kerberos)	Decrittografa un messaggio usando Kerberos.
DecryptMessage (Negozia)	Decrittografa un messaggio usando Negotiate.
DecryptMessage (NTLM)	Decrittografa un messaggio usando NTLM.
DecryptMessage (Schannel)	Decrittografa un messaggio usando Schannel.

Sintassi

SECURITY_STATUS SEC_Entry DecryptMessage(
  _In_    PCtxtHandle    phContext,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo,
  _Out_   PULONG         pfQOP
);

Parametri

phContext [in]

Handle per il contesto di sicurezza da usare per decrittografare il messaggio.

pMessage [in, out]

Puntatore a una struttura SecBufferDesc . In input, la struttura fa riferimento a una o più strutture SecBuffer . Uno di questi può essere di tipo SECBUFFER_DATA. Tale buffer contiene il messaggio crittografato. Il messaggio crittografato viene decrittografato sul posto, sovrascrivendo il contenuto originale del buffer.

Quando si usa il provider di servizi di gestione del digest, in input, la struttura fa riferimento a una o più strutture SecBuffer . Uno di questi deve essere di tipo SECBUFFER_DATA o SECBUFFER_STREAM e deve contenere il messaggio crittografato.

Quando si usa Schannel SSP con contesti non orientati alla connessione, in input, la struttura deve contenere quattro strutture SecBuffer . Esattamente un buffer deve essere di tipo SECBUFFER_DATA e contenere un messaggio crittografato, che viene decrittografato sul posto. I buffer rimanenti vengono usati per l'output e devono essere di tipo SECBUFFER_EMPTY. Per i contesti orientati alla connessione, è necessario specificare un buffer di tipo SECBUFFER_DATA, come indicato per contesti non orientati alla connessione. Inoltre, è necessario specificare anche un secondo buffer di tipo SECBUFFER_TOKEN che contiene un token di sicurezza.

MessageSeqNo [in]

Numero di sequenza previsto dall'applicazione di trasporto, se presente. Se l'applicazione di trasporto non mantiene i numeri di sequenza, questo parametro deve essere impostato su zero.

Quando si usa il provider di servizi di spostamento del digest, questo parametro deve essere impostato su zero. Il provider di servizi di gestione della sequenza gestisce internamente la numerazione della sequenza.

Quando si usa Schannel SSP, questo parametro deve essere impostato su zero. Schannel SSP non usa numeri di sequenza.

pfQOP [out]

Puntatore a una variabile di tipo ULONG che riceve flag specifici del pacchetto che indicano la qualità della protezione.

Quando si usa Schannel SSP, questo parametro non viene usato e deve essere impostato su NULL.

Questo parametro può essere uno dei flag seguenti.

Valore	Significato
SECQOP_WRAP_NO_ENCRYPT	Il messaggio non è stato crittografato, ma è stata prodotta un'intestazione o un trailer. Nota: KERB_WRAP_NO_ENCRYPT ha lo stesso valore e lo stesso significato.
SIGN_ONLY	Quando si usa il provider di servizi di avvio del digest, usare questo flag quando il contesto di sicurezza è impostato per verificare solo la firma . Per altre informazioni, vedere Qualità della protezione.

Valore restituito

Se la funzione verifica che il messaggio sia stato ricevuto nella sequenza corretta, la funzione restituisce SEC_E_OK.

Se la funzione non riesce a decrittografare il messaggio, restituisce uno dei codici di errore seguenti.

Codice restituito	Descrizione
SEC_E_BUFFER_TOO_SMALL	Il buffer dei messaggi è troppo piccolo. Usato con il provider di servizi di gestione del digest.
SEC_E_CRYPTO_SYSTEM_INVALID	La crittografia scelta per il contesto di sicurezza non è supportata. Usato con il provider di servizi di gestione del digest.
SEC_E_INCOMPLETE_MESSAGE	I dati nel buffer di input sono incompleti. L'applicazione deve leggere di nuovo altri dati dal server e chiamare di nuovo DecryptMessage (Generale).
SEC_E_INVALID_HANDLE	Handle di contesto non valido specificato nel parametro phContext . Usato con gli SSP digest e Schannel.
SEC_E_INVALID_TOKEN	I buffer sono di tipo errato o nessun buffer di tipo SECBUFFER_DATA è stato trovato. Usato con Schannel SSP.
SEC_E_MESSAGE_ALTERED	Il messaggio è stato modificato. Usato con gli SSP digest e Schannel.
SEC_E_OUT_OF_SEQUENCE	Il messaggio non è stato ricevuto nella sequenza corretta.
SEC_E_QOP_NOT_SUPPORTED	Né la riservatezza né l'integrità sono supportate dal contesto di sicurezza. Usato con il provider di servizi di gestione del digest.
SEC_I_CONTEXT_EXPIRED	Il mittente del messaggio ha completato l'uso della connessione e ha avviato un arresto. Per informazioni sull'avvio o il riconoscimento di un arresto, vedere Arresto di una connessione Schannel. Usato con Schannel SSP.
SEC_I_RENEGOTIATE	La parte remota richiede una nuova sequenza handshake o l'applicazione ha appena avviato un arresto. Tornare al ciclo di negoziazione e chiamare AcceptSecurityContext (Generale) o InitializeSecurityContext (Generale), passando buffer di input vuoti. Se la funzione restituisce un buffer di tipo SEC_BUFFER_EXTRA, questa operazione deve essere passata alla funzione AcceptSecurityContext (Generale) come buffer di input. Usato con Schannel SSP. La rinegoziazione non è supportata per la modalità kernel Schannel. Il chiamante deve ignorare questo valore restituito o arrestare la connessione. Se il valore viene ignorato, il client o il server potrebbe arrestare la connessione di conseguenza.

Commenti

Quando si usa Schannel SSP, la funzione DecryptMessage (Generale) restituisce SEC_I_CONTEXT_EXPIRED quando il mittente del messaggio ha arrestato la connessione. Per informazioni sull'avvio o il riconoscimento di un arresto, vedere Arresto di una connessione Schannel.

Quando si usa Schannel SSP, DecryptMessage (Generale) restituisce SEC_I_RENEGOTIATE quando il mittente del messaggio vuole rinegoziare la connessione (contesto di sicurezza). Un'applicazione gestisce una rinegoziazione richiesta chiamando AcceptSecurityContext (Generale) o InitializeSecurityContext (generale ) e passando i buffer di input vuoti. Dopo questa chiamata iniziale restituisce un valore, procedere come se l'applicazione creasse una nuova connessione. Per altre informazioni, vedere [Creazione di un contesto di sicurezza Schannel](creating-an-schannel-security-context.md).

Per informazioni sull'interoperabilità con GSSAPI, vedere Interoperabilità SSPI/Kerberos con GSSAPI.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Intestazione	Sspi.h (include Security.h)
Libreria	Secur32.lib
DLL	Secur32.dll

Vedi anche

Funzioni SSPI
EncryptMessage (Generale)
SecBuffer
SecBufferDesc

Condividi tramite