Condividi tramite

Funzione EncryptMessage (Schannel)

  • Articolo

La funzione EncryptMessage (Schannel) crittografa un messaggio per fornire la privacy. EncryptMessage (Schannel) consente a un'applicazione di scegliere tra algoritmi di crittografia supportati dal meccanismo scelto. La funzione EncryptMessage (Schannel) usa il contesto di sicurezza a cui fa riferimento l'handle di contesto. Alcuni pacchetti non hanno messaggi da crittografare o decrittografare, ma invece fornire un hash di integrità che può essere controllato.

Quando si usa Schannel SSP, questa funzione crittografa i messaggi usando una chiave di sessione negoziata con la parte remota che riceverà il messaggio. L'algoritmo di crittografia è determinato dall'uso di [suite di crittografia](crittografia-suites-in-schannel.md).

Nota

EncryptMessage (Schannel) e DecryptMessage (Schannel) può essere chiamato 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.

Sintassi

SECURITY_STATUS SEC_Entry EncryptMessage(
  _In_    PCtxtHandle    phContext,
  _In_    ULONG          fQOP,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo
);

Parametri

phContext [in]

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

fQOP [in]

Flag specifici del pacchetto che indicano la qualità della protezione. Un pacchetto di sicurezza può usare questo parametro per abilitare la selezione di algoritmi crittografici.

Questo parametro può essere il flag seguente.

Valore Significato
SECQOP_WRAP_OOB_DATA
 Inviare un messaggio di avviso Schannel. In questo caso, il parametro pMessage deve contenere un codice evento SSL/TLS standard a due byte. Questo valore è supportato solo da Schannel SSP.
Ad esempio, a partire da Windows Vista, il messaggio "server hello" inviato dal server durante il protocollo di riutenticazione deve essere crittografato come avviso TLS.

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 da crittografare. Il messaggio viene crittografato sul posto, sovrascrivendo il contenuto originale della struttura.

La funzione non elabora i buffer con l'attributo SECBUFFER_READONLY.

La lunghezza della struttura SecBuffer che contiene il messaggio non deve essere maggiore di cbMaximumMessage, ottenuta dalla funzione QueryContextAttributes (Schannel) ( SECPKG_ATTR_STREAM_SIZES).

MessageSeqNo [in]

Numero di sequenza assegnato all'applicazione di trasporto al messaggio. Se l'applicazione di trasporto non mantiene i numeri di sequenza, questo parametro deve essere zero.

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

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce SEC_E_OK.

Se la funzione ha esito negativo, restituisce uno dei codici di errore seguenti.

Codice restituito Descrizione
SEC_E_BUFFER_TOO_SMALL
 Il buffer di output è troppo piccolo. Per altre informazioni, vedere la sezione Osservazioni.
SEC_E_CONTEXT_EXPIRED
 L'applicazione fa riferimento a un contesto già chiuso. Un'applicazione scritta correttamente non deve ricevere questo errore.
SEC_E_CRYPTO_SYSTEM_INVALID
 La crittografia scelta per il contesto di sicurezza non è supportata.
SEC_E_INSUFFICIENT_MEMORY
 Non è disponibile memoria sufficiente per completare l'azione richiesta.
SEC_E_INVALID_HANDLE
 Handle di contesto non valido specificato nel parametro phContext .
SEC_E_INVALID_TOKEN
 Non è stato trovato alcun buffer di tipo SECBUFFER_DATA.
SEC_E_QOP_NOT_SUPPORTED
 Né la riservatezza né l'integrità sono supportate dal contesto di sicurezza.

Commenti

La funzione EncryptMessage (Schannel) crittografa un messaggio in base al messaggio e alla chiave di sessione da un contesto di sicurezza.

Se l'applicazione di trasporto ha creato il contesto di sicurezza per supportare il rilevamento della sequenza e il chiamante fornisce un numero di sequenza, la funzione include queste informazioni con il messaggio crittografato. Incluse queste informazioni proteggono dalla riproduzione, dall'inserimento e dall'eliminazione dei messaggi. Il pacchetto di sicurezza incorpora il numero di sequenza passato dall'applicazione di trasporto.

Se usato con Schannel SSP, il parametro pMessage deve contenere una struttura SecBufferDesc con i buffer seguenti.

Nota

Questi buffer devono essere forniti nell'ordine visualizzato.

Tipo di buffer Descrizione
SECBUFFER_STREAM_HEADER Per uso interno. Nessuna inizializzazione necessaria.
SECBUFFER_DATA Contiene il messaggio di testo non crittografato da crittografare.
SECBUFFER_STREAM_TRAILER Per uso interno. Nessuna inizializzazione necessaria.
SECBUFFER_EMPTY Per uso interno. Nessuna inizializzazione necessaria. Le dimensioni possono essere zero.

Quando si usa Schannel SSP, determinare la dimensione massima di ognuno dei buffer chiamando la funzione QueryContextAttributes (Schannel) e specificando l'attributo SECPKG_ATTR_STREAM_SIZES. Questa funzione restituisce una struttura SecPkgContext_StreamSizes i cui membri contengono le dimensioni massime per l'intestazione (membro cbHeader ), il messaggio (membro cbMaximumMessage ) e i buffer trailer (membro cbTrailer ).

Per prestazioni ottimali, le strutture pMessage devono essere allocate dalla memoria contigua.

Windows XP/2000: Questa funzione è stata nota anche come SealMessage. Le applicazioni devono ora usare Solo EncryptMessage (Schannel).

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