Funzione SaslInitializeSecurityContextA (sspi.h)

  • Articolo

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

Sintassi

SECURITY_STATUS SEC_ENTRY SaslInitializeSecurityContextA(
  [in]            PCredHandle    phCredential,
  [in]            PCtxtHandle    phContext,
  [in]            LPSTR          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 da .
Funzione AcquireCredentialsHandle usata per compilare il contesto di sicurezza. L'uso della funzione SaslInitializeSecurityContext richiede almeno le credenziali OUTBOUND.

[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 sequenza.
ISC_REQ_CONFIDENTIALITY
 Crittografare i messaggi.
ISC_REQ_STREAM
 Supportare una connessione orientata ai flussi.
ISC_REQ_EXTENDED_ERROR
 Quando si verificano errori, l'entità remota riceverà una notifica.
ISC_REQ_CONNECTION
 Il contesto di sicurezza non gestirà 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 dei 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 per il pacchetto. Il puntatore deve essere NULL nella prima chiamata alla funzione. Nelle chiamate successive alla funzione, si tratta di 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 contenente 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 compilerà 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 verificare la presenza di attributi correlati alla sicurezza finché la chiamata di funzione finale non viene restituita 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 Determinati attributi di contesto 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 nell'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. Nella tabella seguente vengono illustrati alcuni possibili valori restituiti da errori.

Codice restituito Descrizione
SEC_E_ALGORITHM_MISMATCH
 L'elaborazione dell'autenticazione non è consentita.
SEC_E_INSUFFICIENT_MEMORY
 Memoria insufficiente 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito Valore
Client minimo supportato Nessuno supportato
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