Funzione SaslInitializeSecurityContextW (sspi.h)

  • Articolo

La funzione SaslInitializeSecurityContext esegue il wrapping di una chiamata standard alla funzione Security Support Provider Interface InitializeSecurityContext (Generale) e elabora i cookie del server SASL dal server.

Sintassi

SECURITY_STATUS SEC_ENTRY SaslInitializeSecurityContextW(
  [in]            PCredHandle    phCredential,
  [in]            PCtxtHandle    phContext,
  [in]            LPWSTR         pszTargetName,
  [in]            unsigned long  fContextReq,
  [in]            unsigned long  Reserved1,
  [in]            unsigned long  TargetDataRep,
  [in]            PSecBufferDesc pInput,
  [in]            unsigned long  Reserved2,
  [out]           PCtxtHandle    phNewContext,
  [in, out]       PSecBufferDesc pOutput,
  [out]           unsigned long  *pfContextAttr,
  [out, optional] PTimeStamp     ptsExpiry
);

Parametri

[in] phCredential

Handle per le credenziali restituite dall'oggetto
Funzione AcquireCredentialsHandle usata per compilare il contesto di sicurezza. L'uso della funzione SaslInitializeSecurityContext richiede almeno credenziali IN USCITA.

[in] phContext

Puntatore a una struttura CtxtHandle . Nella prima chiamata alla funzione SaslInitializeSecurityContext , questo puntatore è NULL. Nella seconda chiamata, questo parametro è un puntatore all'handle al contesto parzialmente formato restituito nel parametro phNewContext dalla prima chiamata.

[in] pszTargetName

Puntatore a una stringa Unicode o ANSI che indica la destinazione del contesto.

[in] fContextReq

Flag di bit che indicano i requisiti del contesto. I flag usati per questo parametro sono preceduti da ISC_REQ_; ad esempio: ISC_REQ_DELEGATE. Specificare le combinazioni dei flag di attributi seguenti.

Valore Significato
ISC_REQ_REPLAY_DETECT
 Rilevare i pacchetti riprodotti.
ISC_REQ_SEQUENCE_DETECT
 Rilevare i messaggi ricevuti fuori dalla sequenza.
ISC_REQ_CONFIDENTIALITY
 Crittografare i messaggi.
ISC_REQ_STREAM
 Supportare una connessione orientata al flusso.
ISC_REQ_EXTENDED_ERROR
 Quando si verificano errori, la parte remota riceverà una notifica.
ISC_REQ_CONNECTION
 Il contesto di sicurezza non gestisce i messaggi di formattazione.
ISC_REQ_MUTUAL_AUTH
 Il client e il server verranno autenticati.
ISC_REQ_INTEGRITY
 Firmare i messaggi e verificare le firme.
 

Per altre descrizioni dei vari attributi, vedere Requisiti di contesto.

[in] Reserved1

Valore riservato; deve essere zero.

[in] TargetDataRep

Indica la rappresentazione dei dati, ad esempio l'ordinamento di byte, nella destinazione. Può essere SECURITY_NATIVE_DREP o SECURITY_NETWORK_DREP.

[in] pInput

Puntatore a una struttura SecBufferDesc che contiene puntatori ai buffer forniti come input al pacchetto. Il puntatore deve essere NULL nella prima chiamata alla funzione. Nelle chiamate successive alla funzione, è un puntatore a un buffer allocato con memoria sufficiente per contenere il token restituito dal peer remoto.

SasL richiede un singolo buffer di tipo SECBUFFER_TOKEN che contiene la richiesta ricevuta dal server.

[in] Reserved2

Valore riservato; deve essere zero.

[out] phNewContext

Puntatore a una struttura CtxtHandle . Nella prima chiamata alla funzione SaslInitializeSecurityContext , questo puntatore riceve il nuovo handle di contesto. Nella seconda chiamata phNewContext può essere uguale all'handle specificato nel parametro phContext .

[in, out] pOutput

Puntatore a una struttura SecBufferDesc che contiene puntatori alla struttura SecBuffer che riceve i dati di output. Se un buffer è stato digitato come SEC_READWRITE nell'input, sarà presente nell'output. Il sistema allocherà un buffer per il token di sicurezza se richiesto (tramite ISC_REQ_ALLOCATE_MEMORY) e inserire l'indirizzo nel descrittore del buffer per il token di sicurezza.

[out] pfContextAttr

Puntatore a una variabile per ricevere un set di flag di bit che indicano gli attributi del contesto stabilito. Per una descrizione dei vari attributi, vedere Requisiti di contesto.

I flag usati per questo parametro sono preceduti da ISC_RET_, ad esempio ISC_RET_DELEGATE.

Per un elenco di valori validi, vedere il parametro fContextReq .

Non controllare gli attributi correlati alla sicurezza fino a quando la chiamata di funzione finale non restituisce correttamente. I flag di attributo non correlati alla sicurezza, ad esempio il flag ASC_RET_ALLOCATED_MEMORY, possono essere controllati prima della restituzione finale.

Nota Gli attributi di contesto specifici possono cambiare durante una negoziazione con un peer remoto.
 

[out, optional] ptsExpiry

Puntatore a una struttura TimeStamp che riceve l'ora di scadenza del contesto. È consigliabile che il pacchetto di sicurezza restituisca sempre questo valore in ora locale. Questo parametro è facoltativo e NULL deve essere passato per i client di breve durata.

Valore restituito

Se la chiamata viene completata correttamente, questa funzione restituisce SEC_E_OK. La tabella seguente mostra alcuni possibili valori restituiti dagli errori.

Codice restituito Descrizione
SEC_E_ALGORITHM_MISMATCH
 L'elaborazione di Authz non è consentita.
SEC_E_INSUFFICIENT_MEMORY
 Memoria insufficiente disponibile per completare la richiesta.
SEC_E_INVALID_TOKEN
 Nessun buffer token si trova nel parametro pOutput o il messaggio non è riuscito a decrittografare.

Commenti

Nota

L'intestazione sspi.h definisce SaslInitializeSecurityContext come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

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