Funzione InitializeSecurityContext (CredSSP)

Articolo
03/18/2023

La funzione InitializeSecurityContext (CredSSP) avvia il contesto di sicurezza lato client da un handle di credenziali. La funzione crea un contesto di sicurezza tra l'applicazione client e un peer remoto. InitializeSecurityContext (CredSSP) restituisce un token che il client deve passare al peer remoto; il peer invia a sua volta tale token all'implementazione della sicurezza locale tramite la chiamata AcceptSecurityContext (CredSSP). Il token generato deve essere considerato opaco da tutti i chiamanti.

In genere, la funzione InitializeSecurityContext (CredSSP) viene chiamata in un ciclo fino a quando non viene stabilito un contesto di sicurezza sufficiente.

Sintassi

SECURITY_STATUS SEC_ENTRY InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parametri

phCredential[in, optional]

Handle per le credenziali restituite da AcquireCredentialsHandle (CredSSP). Questo handle viene usato per compilare il contesto di sicurezza. La funzione InitializeSecurityContext (CredSSP) richiede almeno le credenziali OUTBOUND.

phContext[in, optional]

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

Nella prima chiamata a InitializeSecurityContext (CredSSP) specificare NULL. Nelle chiamate future specificare il token ricevuto nel parametro phNewContext dopo la prima chiamata a questa funzione.

Avviso

Non usare lo stesso handle di contesto nelle chiamate simultanee a InitializeSecurityContext (CredSSP). L'implementazione dell'API nei provider di servizi di sicurezza non è thread-safe.

pTargetName[in, optional]

Puntatore a una stringa con terminazione Null che identifica in modo univoco il server di destinazione. Schannel usa questo valore per verificare il certificato del server. Schannel usa anche questo valore per individuare la sessione nella cache della sessione durante la riascritzione di una connessione. La sessione memorizzata nella cache viene usata solo se vengono soddisfatte tutte le condizioni seguenti:

Il nome della destinazione è lo stesso.
La voce della cache non è scaduta.
Il processo dell'applicazione che chiama la funzione è lo stesso.
La sessione di accesso è la stessa.
L'handle delle credenziali è lo stesso.

fContextReq[in]

Flag di bit che indicano le richieste per il contesto. Non tutti i pacchetti possono supportare tutti i requisiti. I flag usati per questo parametro sono preceduti da ISC_REQ_, ad esempio ISC_REQ_DELEGATE.

Questo parametro può essere uno o più dei flag di attributi seguenti.

Valore	Significato
ISC_REQ_ALLOCATE_MEMORY `0x100`	Il pacchetto di sicurezza alloca i buffer di output per il chiamante. Al termine dell'uso dei buffer di output, liberarli chiamando la funzione FreeContextBuffer .
ISC_REQ_CONNECTION `0x800`	Il contesto di sicurezza non gestirà i messaggi di formattazione.
ISC_REQ_EXTENDED_ERROR `0x4000`	Quando si verificano errori, l'entità remota riceverà una notifica.
ISC_REQ_MANUAL_CRED_VALIDATION `0x80000`	Il provider di supporto per la sicurezza delle credenziali (CredSSP) non deve autenticare automaticamente il server. Questo flag viene sempre impostato quando si usa CredSSP.
ISC_REQ_SEQUENCE_DETECT `0x8`	Rilevare i messaggi ricevuti fuori sequenza.
ISC_REQ_STREAM `0x8000`	Supportare una connessione orientata ai flussi.
ISC_REQ_USE_SUPPLIED_CREDS `0x80`	CredSSP non deve tentare di fornire automaticamente le credenziali per il client.
ISC_REQ_DELEGATE `0x1`	Indica che le credenziali dell'utente devono essere delegate al server. Se questo flag non viene specificato, al server viene delegato un set vuoto di credenziali. Windows Server 2008 e Windows Vista: Questo flag è obbligatorio.
ISC_REQ_MUTUAL_AUTH `0x2`	Indica che l'autenticazione server non è necessaria. I criteri di delega vengono comunque applicati se questo flag non è specificato. Windows Server 2008 e Windows Vista: Questo flag viene ignorato.

Gli attributi richiesti potrebbero non essere supportati dal client. Per altre informazioni, vedere il parametro pfContextAttr .

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

Riservato1[in]

Riservato. Questo parametro deve essere impostato su zero.

TargetDataRep[in]

Rappresentazione dei dati, ad esempio l'ordinamento dei byte, nella destinazione. Questo parametro può essere SECURITY_NATIVE_DREP o SECURITY_NETWORK_DREP.

pInput[in, out, optional]

Puntatore a una struttura SecBufferDesc che contiene puntatori ai buffer forniti come input per il pacchetto. A meno che il contesto client non sia stato avviato dal server, il valore di questo parametro deve essere NULL nella prima chiamata alla funzione. Nelle chiamate successive alla funzione o quando il contesto client è stato avviato dal server, il valore di questo parametro è un puntatore a un buffer allocato con memoria sufficiente per contenere il token restituito dal computer remoto.

Nelle chiamate a questa funzione dopo la chiamata iniziale, devono essere presenti due buffer. Il primo ha il tipo SECBUFFER_TOKEN e contiene il token ricevuto dal server. Il secondo buffer ha tipo SECBUFFER_EMPTY; impostare i membri pvBuffer e cbBuffer su zero.

Riservato2[in]

Riservato. Questo parametro deve essere impostato su zero.

phNewContext[in, out, optional]

Puntatore a una struttura CtxtHandle . Nella prima chiamata a InitializeSecurityContext (CredSSP) questo puntatore riceve il nuovo handle di contesto. Nella seconda chiamata , phNewContext può essere uguale all'handle specificato nel parametro phContext . phNewContext non deve mai essere NULL.

pOutput[out, optional]

Puntatore a una struttura SecBufferDesc . Questa struttura a sua volta 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 compilerà l'indirizzo nel descrittore del buffer per il token di sicurezza.

Se viene specificato il flag ISC_REQ_ALLOCATE_MEMORY , CredSSP allocherà memoria per il buffer e inserisce le informazioni appropriate in SecBufferDesc.

pfContextAttr[out]

Puntatore a 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 la negoziazione con un peer remoto.

ptsExpiry[out, optional]

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 funzione ha esito positivo, restituisce uno dei codici di esito positivo seguenti.

Codice restituito	Descrizione
SEC_E_INCOMPLETE_MESSAGE	I dati per l'intero messaggio non sono stati letti dalla rete. Quando viene restituito questo valore, il buffer pInput contiene una struttura SecBuffer con un membro BufferType di SECBUFFER_MISSING. Il membro cbBuffer di SecBuffer specifica il numero di byte aggiuntivi che la funzione deve leggere dal client prima che la funzione abbia esito positivo. Anche se questo numero non è sempre accurato, l'uso può contribuire a migliorare le prestazioni evitando più chiamate a questa funzione.
SEC_E_OK	Il contesto di sicurezza è stato inizializzato correttamente. Non è necessaria un'altra chiamata InitializeSecurityContext (CredSSP). Se la funzione restituisce un token di output, ovvero se il SECBUFFER_TOKEN in pOutput è di lunghezza diversa da zero, tale token deve essere inviato al server.
SEC_I_COMPLETE_AND_CONTINUE	Il client deve chiamare CompleteAuthToken e quindi passare l'output al server. Il client attende quindi un token restituito e lo passa, in un'altra chiamata, a InitializeSecurityContext (CredSSP).
SEC_I_COMPLETE_NEEDED	Il client deve completare la compilazione del messaggio e quindi chiamare la funzione CompleteAuthToken .
SEC_I_CONTINUE_NEEDED	Il client deve inviare il token di output al server e attendere un token restituito. Il client passa il token restituito in un'altra chiamata a InitializeSecurityContext (CredSSP). Il token di output può essere vuoto.
SEC_I_INCOMPLETE_CREDENTIALS	Il server ha richiesto l'autenticazione client, ma le credenziali fornite non includono un certificato o il certificato non è stato emesso da un'autorità di certificazione attendibile per il server. Per altre informazioni, vedere la sezione Osservazioni.

Se la funzione ha esito negativo, la funzione restituisce uno dei codici di errore seguenti.

Codice restituito	Descrizione
SEC_E_INSUFFICIENT_MEMORY	Memoria insufficiente per completare l'azione richiesta.
SEC_E_INTERNAL_ERROR	Si è verificato un errore che non è stato mappato a un codice di errore SSPI.
SEC_E_INVALID_HANDLE	L'handle passato alla funzione non è valido.
SEC_E_INVALID_TOKEN	Il token di input non è valido. Le possibili cause includono un token danneggiato in transito, un token di dimensioni non corrette e un token passato nel pacchetto di sicurezza errato. Questa ultima condizione può verificarsi se il client e il server non hanno negoziato il pacchetto di sicurezza appropriato.
SEC_E_LOGON_DENIED	Accesso non riuscito.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Non è stato possibile contattare alcuna autorità per l'autenticazione. Il nome di dominio della parte di autenticazione potrebbe essere errato, il dominio potrebbe non essere raggiungibile o potrebbe essersi verificato un errore di relazione di trust.
SEC_E_NO_CREDENTIALS	Nel pacchetto di sicurezza non sono disponibili credenziali.
SEC_E_TARGET_UNKNOWN	La destinazione non è stata riconosciuta.
SEC_E_UNSUPPORTED_FUNCTION	Il valore del parametro fContextReq non è valido. Non è stato specificato un flag obbligatorio oppure è stato specificato un flag non supportato da CredSSP.
SEC_E_WRONG_PRINCIPAL	L'entità che ha ricevuto la richiesta di autenticazione non corrisponde a quella passata nel parametro pszTargetName . Questo errore indica un errore nell'autenticazione reciproca.
SEC_E_DELEGATION_POLICY	I criteri non supportano la delega delle credenziali al server di destinazione.
SEC_E_POLICY_NLTM_ONLY	La delega delle credenziali al server di destinazione non è consentita quando non si ottiene l'autenticazione reciproca.
SEC_E_MUTUAL_AUTH_FAILED	L'autenticazione del server non è riuscita quando il flag ISC_REQ_MUTUAL_AUTH viene specificato nel parametro fContextReq .

Commenti

Il chiamante è responsabile della determinazione se gli attributi di contesto finali sono sufficienti. Se, ad esempio, è stata richiesta la riservatezza, ma non è stato possibile stabilire, alcune applicazioni possono scegliere di arrestare immediatamente la connessione.

Se gli attributi del contesto di sicurezza non sono sufficienti, il client deve liberare il contesto parzialmente creato chiamando la funzione DeleteSecurityContext .

Il client chiama la funzione InitializeSecurityContext (CredSSP) per inizializzare un contesto in uscita.

Per un contesto di sicurezza a due gambe, la sequenza chiamante è la seguente:

Il client chiama la funzione con phContext impostato su NULL e riempie il descrittore del buffer con il messaggio di input.
Il pacchetto di sicurezza esamina i parametri e costruisce un token opaco, inserendolo nell'elemento TOKEN nella matrice di buffer. Se il parametro fContextReq include il flag ISC_REQ_ALLOCATE_MEMORY , il pacchetto di sicurezza alloca la memoria e restituisce il puntatore nell'elemento TOKEN.
Il client invia il token restituito nel buffer pOutput al server di destinazione. Il server passa quindi il token come argomento di input in una chiamata alla funzione AcceptSecurityContext (CredSSP).
AcceptSecurityContext (CredSSP) può restituire un token. Il server invia questo token al client tramite una seconda chiamata InitializeSecurityContext (CredSSP) se la prima chiamata ha restituito SEC_I_CONTINUE_NEEDED.

Se il server ha risposto correttamente, il pacchetto di sicurezza restituisce SEC_E_OK e viene stabilita una sessione sicura.

Se la funzione restituisce una delle risposte di errore, la risposta del server non viene accettata e la sessione non viene stabilita.

Se la funzione restituisce SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED o SEC_I_COMPLETE_AND_CONTINUE, i passaggi 2 e 3 vengono ripetuti.

L'inizializzazione del contesto di sicurezza può richiedere più di una chiamata a questa funzione, a seconda del meccanismo di autenticazione sottostante e delle scelte specificate nel parametro fContextReq .

I parametri fContextReq e pfContextAttributes sono maschera di bit che rappresentano vari attributi di contesto. Per una descrizione dei vari attributi, vedere Requisiti di contesto. Anche se il parametro pfContextAttributes è valido per qualsiasi risultato restituito correttamente, è necessario esaminare i flag che riguardano gli aspetti di sicurezza del contesto solo in caso di esito positivo finale. I valori intermedi possono essere impostati, ad esempio, il flag ISC_RET_ALLOCATED_MEMORY .

Se il flag ISC_REQ_USE_SUPPLIED_CREDS è impostato, il pacchetto di sicurezza deve cercare un tipo di buffer SECBUFFER_PKG_PARAMS nel buffer di input pInput . Anche se non si tratta di una soluzione generica, consente un'associazione avanzata di pacchetti di sicurezza e applicazione quando appropriato.

Se è stato specificato ISC_REQ_ALLOCATE_MEMORY, il chiamante deve liberare la memoria chiamando la funzione FreeContextBuffer .

Ad esempio, il token di input potrebbe essere la richiesta da un gestore LAN. In questo caso, il token di output sarà la risposta crittografata NTLM alla richiesta.

L'azione eseguita dal client dipende dal codice restituito da questa funzione. Se il codice restituito è SEC_E_OK, non sarà prevista alcuna seconda chiamata InitializeSecurityContext (CredSSP) e non è prevista alcuna risposta dal server. Se il codice restituito è SEC_I_CONTINUE_NEEDED, il client prevede un token in risposta dal server e lo passa in una seconda chiamata a InitializeSecurityContext (CredSSP). Il codice restituito SEC_I_COMPLETE_NEEDED indica che il client deve completare la compilazione del messaggio e chiamare la funzione CompleteAuthToken . Il codice SEC_I_COMPLETE_AND_CONTINUE incorpora entrambe queste azioni.

Se InitializeSecurityContext (CredSSP) restituisce l'esito positivo nella prima chiamata (o solo), il chiamante deve infine chiamare la funzione DeleteSecurityContext sull'handle restituito, anche se la chiamata ha esito negativo in una fase successiva dello scambio di autenticazione.

Il client può chiamare nuovamente InitializeSecurityContext (CredSSP) dopo il completamento. Ciò indica al pacchetto di sicurezza che è necessario eseguire una nuova autenticazione.

I chiamanti in modalità kernel presentano le differenze seguenti: il nome di destinazione è una stringa Unicode che deve essere allocata nella memoria virtuale usando VirtualAlloc; non deve essere allocata dal pool. I buffer passati e forniti in pInput e pOutput devono essere in memoria virtuale, non nel pool.

Se la funzione restituisce SEC_I_INCOMPLETE_CREDENTIALS, verificare che le credenziali r passate alla funzione AcquireCredentialsHandle (CredSSP) siano specificate un certificato valido e attendibile Il certificato deve essere un certificato di autenticazione client rilasciato da un'autorità di certificazione attendibile dal server. Per ottenere un elenco delle autorità di certificazione attendibili dal server, chiamare la funzione QueryContextAttributes (CredSSP) con l'attributo SECPKG_ATTR_ISSUER_LIST_EX .

Dopo aver ricevuto un certificato di autenticazione da un'autorità di certificazione attendibile dal server, l'applicazione client crea una nuova credenziale. Lo fa chiamando di nuovo la funzione AcquireCredentialsHandle (CredSSP) e quindi chiamando InitializeSecurityContext (CredSSP), specificando di nuovo la nuova credenziale nel parametro phCredential .

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Intestazione	Sspi.h (include Security.h)
Libreria	Secur32.lib
DLL	Secur32.dll