Funzione EncryptMessage (Generale)

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

Quando si usa il provider di supporto per la sicurezza digest , questa funzione è disponibile solo come meccanismo SASL.

Quando si usa il provider di servizi condivisi Schannel, questa funzione crittografa i messaggi usando una chiave di sessione negoziata con l'entità remota che riceverà il messaggio. L'algoritmo di crittografia è determinato dalla [suite di crittografia ](cipher-suites-in-schannel.md) in uso.

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

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 di crittografia.

Quando si usa il provider di servizi condivisi digest, questo parametro deve essere impostato su zero.

Questo parametro può essere uno dei flag seguenti.

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 (General) (SECPKG_ATTR_STREAM_SIZES).

Quando si usa il provider di servizi condivisi digest, deve essere presente un secondo buffer di tipo SECBUFFER_PADDING o SEC_BUFFER_DATA per contenere le informazioni sulla firma . Per ottenere le dimensioni del buffer di output, chiamare la funzione QueryContextAttributes (Generale) e specificare SECPKG_ATTR_SIZES. La funzione restituirà una struttura SecPkgContext_Sizes . Le dimensioni del buffer di output sono la somma dei valori nei membri cbMaxSignature e cbBlockSize .

Le applicazioni che non usano SSL devono fornire un secBuffer di tipo SECBUFFER_PADDING.

MessageSeqNo [in]

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

Quando si usa il provider di servizi condivisi digest, questo parametro deve essere impostato su zero. Il provider di servizi condivisi digest gestisce internamente la numerazione delle sequenze.

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.

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.

Commenti

La funzione EncryptMessage (Generale) 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. L'inclusione di queste informazioni protegge dalla riproduzione, dall'inserimento e dall'eliminazione dei messaggi. Il pacchetto di sicurezza incorpora il numero di sequenza passato dall'applicazione di trasporto.

Quando si usa il provider di servizi condivisi digest, ottenere le dimensioni del buffer di output chiamando la funzione QueryContextAttributes (Generale) e specificando SECPKG_ATTR_SIZES. La funzione restituirà una struttura SecPkgContext_Sizes . Le dimensioni del buffer di output sono la somma dei valori nei membri cbMaxSignature e cbBlockSize .

Se usato con il provider di servizi condivisi Schannel, il parametro pMessage deve contenere una struttura SecBufferDesc con i buffer seguenti.

Quando si usa SCHANNEL SSP, determinare la dimensione massima di ognuno dei buffer chiamando la funzione QueryContextAttributes (Generale) 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 (Generale).

Requisiti

Vedi anche

• Funzioni SSPI
• AcceptSecurityContext (Generale)
• DecryptMessage (Generale)
• InitializeSecurityContext (Generale)
• QueryContextAttributes (Generale)
• SecBuffer
• SecBufferDesc