Funzione EncryptMessage (Digest)
La funzione EncryptMessage (Digest) crittografa un messaggio per fornire la privacy. EncryptMessage (Digest) consente all'applicazione di scegliere tra algoritmi crittografici 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 invece fornire un hash di integrità che può essere controllato.
Questa funzione è disponibile solo come meccanismo SASL.
Nota
EncryptMessage (Digest) e DecryptMessage (Digest) 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.
Sintassi
SECURITY_STATUS SEC_ENTRY EncryptMessage(
PCtxtHandle phContext,
unsigned long fQOP,
PSecBufferDesc pMessage,
unsigned long 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.
Quando si usa il provider di servizi di spostamento del digest, questo parametro deve essere impostato su zero.
-
pMessage [in, out]
-
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 di archiviazione del digest, è necessario avere 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.
-
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 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.
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 |
|---|---|
|
Il buffer di output è troppo piccolo. Per altre informazioni, vedere la sezione Osservazioni. |
|
L'applicazione fa riferimento a un contesto già chiuso. Un'applicazione scritta correttamente non deve ricevere questo errore. |
|
La crittografia scelta per il contesto di sicurezza non è supportata. |
|
Non è disponibile memoria sufficiente per completare l'azione richiesta. |
|
Handle di contesto non valido specificato nel parametro phContext . |
|
Non è stato trovato alcun buffer di tipo SECBUFFER_DATA. |
|
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. 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.
Quando si usa il provider di servizi di distribuzione del 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 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. |
Per prestazioni ottimali, le strutture pMessage devono essere allocate dalla memoria contigua.
Windows XP: Questa funzione è stata nota anche come SealMessage. Le applicazioni devono ora usare Solo EncryptMessage (Digest).
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato |
Windows XP [solo app desktop] |
| Server minimo supportato |
Windows Server 2003 [solo app desktop] |
| Intestazione |
|
| Libreria |
|
| DLL |
|
Vedi anche