Funzione EncryptMessage (sspi.h)

Articolo
08/26/2023

La funzione EncryptMessage (Digest) crittografa un messaggio per fornire la privacy. EncryptMessage (Digest) consente all'applicazione di scegliere tra gli algoritmi di crittografia supportati dal meccanismo scelto. La funzione EncryptMessage (Digest) 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.

Questa funzione è disponibile solo come meccanismo SASL.

NotaEncryptMessage (Digest) e DecryptMessage (Digest) possono essere chiamati contemporaneamente da due thread diversi in un unico contesto SSPI ( Security Support Provider Interface ) se un thread esegue la crittografia 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]      unsigned long  fQOP,
  [in, out] PSecBufferDesc pMessage,
  [in]      unsigned long  MessageSeqNo
);

Parametri

[in] phContext

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

[in] fQOP

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.

[in, out] pMessage

Puntatore a una struttura SecBufferDesc . In input, la struttura fa riferimento a una o più strutture SecBuffer che possono 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 (Digest) (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 (Digest) 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.

[in] MessageSeqNo

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.

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	Memoria insufficiente 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 (Digest) 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 (Digest) 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 .

Nota Questi buffer devono essere specificati nell'ordine indicato.

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 pari a zero.

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

Windows XP: Questa funzione era nota anche come SealMessage. Le applicazioni ora usano solo EncryptMessage (Digest).

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	sspi.h (include Security.h)
Libreria	Secur32.lib
DLL	Secur32.dll