Funzione DecryptMessage (Schannel)

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

Questa funzione viene usata anche con il provider di supporto per la sicurezza SCHANNEL per segnalare una richiesta da un mittente del messaggio per una rinegoziazione (rollforward) degli attributi di connessione o per un arresto della connessione.

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 utilizzare 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 condivisi Schannel con contesti che non sono orientati alla connessione, all'input, la struttura deve contenere quattro strutture SecBuffer . 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 i 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 gestisce i numeri di sequenza, questo parametro deve essere impostato su zero.

Quando si usa il provider di servizi condivisi Schannel, questo parametro deve essere impostato su zero. Il provider di servizi condivisi Schannel 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 il provider di servizi condivisi Schannel, questo parametro non viene usato e deve essere impostato su NULL.

Questo parametro può essere il flag seguente.

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.

Commenti

A volte un'applicazione leggerà i dati dall'entità remota, tenterà di decrittografarlo usando DecryptMessage (Schannel) e rileverà che DecryptMessage (Schannel) è riuscito, ma i buffer di output sono vuoti. Si tratta di un comportamento normale e le applicazioni devono essere in grado di gestirle.

Quando si usa il provider di servizi condivisi Schannel, 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.

Se si usa TLS 1.0, potrebbe essere necessario chiamare questa funzione più volte, modificando il buffer di input in ogni chiamata, per decrittografare un intero messaggio.

La funzione DecryptMessage (Schannel) restituisce SEC_I_RENEGOTIATE quando viene ricevuto un messaggio di protocollo TLS post-handshake diverso dai dati dell'applicazione. Dopo che la funzione DecryptMessage (Schannel) ha restituito SEC_I_RENEGOTIATE, eventuali altre chiamate EncryptMessage() e DecryptMessage() avranno esito negativo con SEC_E_CONTEXT_EXPIRED. Un'applicazione gestisce questa situazione chiamando AcceptSecurityContext (Schannel) ( lato server) o InitializeSecurityContext ( lato client) e passando SECBUFFER_EXTRA restituiti da DecryptMessage(). Dopo che questa chiamata iniziale restituisce un valore, procedere come se l'applicazione creasse una nuova connessione. L'applicazione può quindi continuare a chiamare EncryptMessage() e DecryptMessage(). Per altre informazioni, vedere Creazione di un contesto di sicurezza Schannel.

Requisiti

Vedi anche

• Funzioni SSPI
• EncryptMessage (Schannel)
• SecBuffer
• SecBufferDesc