Funzione InitializeSecurityContext (Generale)

Articolo
10/18/2023

La funzione InitializeSecurityContext (Generale) avvia il contesto di sicurezza in uscita sul lato client da un handle di credenziali. La funzione viene usata per creare un contesto di sicurezza tra l'applicazione client e un peer remoto. InitializeSecurityContext (Generale) restituisce un token che il client deve passare al peer remoto, che il peer invia a sua volta all'implementazione della sicurezza locale tramite la chiamata AcceptSecurityContext (Generale). Il token generato deve essere considerato opaco da tutti i chiamanti.

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

Per informazioni sull'uso di questa funzione con un provider di supporto per la sicurezza specifico, vedere gli argomenti seguenti.

Argomento	Descrizione
InitializeSecurityContext (CredSSP)	Avvia il contesto di sicurezza lato client in uscita da un handle di credenziali usando il pacchetto di sicurezza CredSSP (Credential Security Support Provider).
InitializeSecurityContext (Digest)	Avvia il contesto di sicurezza in uscita sul lato client da un handle di credenziali usando il pacchetto di sicurezza Digest.
InitializeSecurityContext (Kerberos)	Avvia il contesto di sicurezza in uscita sul lato client da un handle di credenziali usando il pacchetto di sicurezza Kerberos.
InitializeSecurityContext (Negotiate)	Avvia il contesto di sicurezza in uscita sul lato client da un handle di credenziali usando il pacchetto di sicurezza Negotiate.
InitializeSecurityContext (NTLM)	Avvia il contesto di sicurezza in uscita sul lato client da un handle di credenziali usando il pacchetto di sicurezza NTLM.
InitializeSecurityContext (Schannel)	Avvia il contesto di sicurezza in uscita sul lato client da un handle di credenziali usando il pacchetto di sicurezza Schannel.

Sintassi

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

Parametri

phCredential[in, optional]

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

phContext[in, optional]

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

Questo parametro è facoltativo con il provider di servizi condivisi del digest Microsoft e può essere impostato su NULL.

Quando si usa il provider di servizi condivisi Schannel, nella prima chiamata a InitializeSecurityContext (Generale) 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 (Generale). L'implementazione dell'API nei provider di servizi di sicurezza non è thread-safe.

pTargetName[in, optional]

Puntatore a una stringa con terminazione Null che indica la destinazione del contesto. Il contenuto della stringa è specifico del pacchetto di sicurezza, come descritto nella tabella seguente. Questo elenco non è completo. È possibile aggiungere provider di servizi di sicurezza di sistema aggiuntivi e provider di servizi di sicurezza di terze parti a un sistema.

Provider di servizi condivisi in uso	Significato
Digerire	Stringa con terminazione Null che identifica in modo univoco l'URI della risorsa richiesta. La stringa deve essere composta da caratteri consentiti in un URI e deve essere rappresentata dal set di codice ASCII degli Stati Uniti. La codifica percentuale può essere usata per rappresentare caratteri esterni al set di codice ASCII degli Stati Uniti.
Kerberos o Negotiate	Nome dell'entità servizio (SPN) o contesto di sicurezza del server di destinazione.
NTLM	Nome dell'entità servizio (SPN) o contesto di sicurezza del server di destinazione.
Schannel/SSL	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 riattivazione 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	Il pacchetto di sicurezza alloca i buffer di output. Al termine dell'uso dei buffer di output, liberarli chiamando la funzione FreeContextBuffer .
ISC_REQ_CONFIDENTIALITY	Crittografare i messaggi usando la funzione EncryptMessage .
ISC_REQ_CONNECTION	Il contesto di sicurezza non gestirà i messaggi di formattazione. Questo valore è l'impostazione predefinita per Kerberos, Negotiate e NTLM constrained delegations.
ISC_REQ_DELEGATE	Il server può usare il contesto per eseguire l'autenticazione ad altri server come client. Il flag ISC_REQ_MUTUAL_AUTH deve essere impostato per il funzionamento di questo flag. Valido per Kerberos. Ignorare questo flag per la delega vincolata.
ISC_REQ_EXTENDED_ERROR	Quando si verificano errori, l'entità remota riceverà una notifica.
ISC_REQ_HTTP	Usare digest per HTTP. Omettere questo flag per usare Digest come meccanismo SASL.
ISC_REQ_INTEGRITY	Firmare i messaggi e verificare le firme usando le funzioni EncryptMessage e MakeSignature .
ISC_REQ_MANUAL_CRED_VALIDATION	Schannel non deve autenticare automaticamente il server.
ISC_REQ_MUTUAL_AUTH	I criteri di autenticazione reciproca del servizio verranno soddisfatti. ATTENZIONE: ciò non significa necessariamente che venga eseguita l'autenticazione reciproca, ma solo che i criteri di autenticazione del servizio siano soddisfatti. Per assicurarsi che venga eseguita l'autenticazione reciproca, chiamare la funzione QueryContextAttributes (Generale).
ISC_REQ_NO_INTEGRITY	Se questo flag è impostato, il flag ISC_REQ_INTEGRITY viene ignorato. Questo valore è supportato solo dalla delegavincolata Negotiate e Kerberos.
ISC_REQ_REPLAY_DETECT	Rilevare i messaggi riprodotti codificati usando le funzioni EncryptMessage o MakeSignature .
ISC_REQ_edizione StandardQUENCE_DETECT	Rilevare i messaggi ricevuti fuori sequenza.
ISC_REQ_STREAM	Supportare una connessione orientata al flusso.
ISC_REQ_Uedizione Standard_edizione StandardSSION_KEY	È necessario negoziare una nuova chiave di sessione. Questo valore è supportato solo dalla delega vincolata Kerberos.
ISC_REQ_Uedizione Standard_SUPPLIED_CREDS	Schannel non deve tentare di fornire automaticamente le credenziali per il client.

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]

Questo parametro è riservato e deve essere impostato su zero.

TargetDataRep[in]

Rappresentazione dei dati, ad esempio l'ordinamento dei byte, nella destinazione. Questo parametro può essere edizione StandardCURITY_NATIVE_DREP o edizione StandardCURITY_NETWORK_DREP.

Questo parametro non viene usato con Digest o Schannel. Impostarlo su zero.

pInput[in, 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.

Riservato2[in]

Questo parametro è riservato e deve essere impostato su zero.

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

Puntatore a una struttura SecBufferDesc che contiene puntatori alla struttura SecBuffer che riceve i dati di output. Se un buffer è stato digitato come edizione StandardC_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.

Quando si usa il provider di servizi condivisi Microsoft Digest, questo parametro riceve la risposta di verifica che deve essere inviata al server.

Quando si usa il provider di servizi condivisi Schannel, se viene specificato il flag ISC_REQ_ALLOCATE_MEMORY, il provider di servizi condivisi Schannel allocherà memoria per il buffer e inserisce le informazioni appropriate in SecBufferDesc. Inoltre, il chiamante deve passare un buffer di tipo edizione StandardCBUFFER_ALERT. In caso di output, se viene generato un avviso, questo buffer contiene informazioni sull'avviso e la funzione ha esito negativo.

pfContextAttr[out]

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 fino a quando 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

Gli attributi di contesto specifici 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.

Non è prevista alcuna scadenza per le credenziali o i contesti di sicurezza del provider di servizicondivisi del digest Microsoft.

Valore restituito

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

Codice restituito	Descrizione
edizione StandardC_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 (Generale).The client then wait for a returned token and pass it, in another call, to InitializeSecurityContext (General).
edizione StandardC_I_COMPLETE_Nedizione Enterprise DED	Il client deve completare la compilazione del messaggio e quindi chiamare la funzione CompleteAuthToken .
edizione StandardC_I_CONTINUE_Nedizione Enterprise DED	Il client deve inviare il token di output al server e attendere un token restituito. Il token restituito viene quindi passato in un'altra chiamata a InitializeSecurityContext (Generale).The returned token is then pass in another call to InitializeSecurityContext (General). Il token di output può essere vuoto.
edizione StandardC_I_INCOMPLETE_CREDENTIALS	Usare con Schannel. Il server ha richiesto l'autenticazione client e le credenziali fornite non includono un certificato o il certificato non è stato emesso da un'autorità di certificazione attendibile dal server. Per altre informazioni, vedere la sezione Note.
edizione StandardC_E_INCOMPLETE_MESSAGE	Usare con Schannel. 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 edizione StandardCBUFFER_MISSING. Il membro cbBuffer di SecBuffer contiene un valore che indica il numero di byte aggiuntivi che la funzione deve leggere dal client prima che questa 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.
edizione StandardC_E_OK	Il contesto di sicurezza è stato inizializzato correttamente. Non è necessario un'altra chiamata InitializeSecurityContext (Generale). Se la funzione restituisce un token di output, ovvero se il edizione StandardCBUFFER_TOKEN in pOutput è di lunghezza diversa da zero, tale token deve essere inviato al server.

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

Codice restituito	Descrizione
edizione StandardC_E_INSUFFICIENT_MEMORY	Memoria insufficiente per completare l'azione richiesta.
edizione StandardC_E_INTERNAL_ERROR	Si è verificato un errore che non è stato mappato a un codice di errore SSPI.
edizione StandardC_E_INVALID_HANDLE	L'handle passato alla funzione non è valido.
edizione StandardC_E_INVALID_TOKEN	L'errore è dovuto a un token di input in formato non valido, ad esempio un token danneggiato in transito, un token di dimensioni non corrette o un token passato nel pacchetto di sicurezza errato. Il passaggio di un token al pacchetto errato può verificarsi se il client e il server non hanno negoziato il pacchetto di sicurezza appropriato.
edizione StandardC_E_LOGON_DENIED	Accesso non riuscito.
edizione StandardC_E_NO_AUTHENTICATING_AUTHORITY	Non è stato possibile contattare alcuna autorità per l'autenticazione. Il nome di dominio della parte di autenticazione potrebbe non essere corretto, il dominio potrebbe non essere raggiungibile o potrebbe verificarsi un errore di relazione di trust.
edizione StandardC_E_NO_CREDENTIALS	Nessuna credenziale è disponibile nel pacchetto di sicurezza.
edizione StandardC_E_TARGET_UNKNOWN	La destinazione non è stata riconosciuta.
edizione StandardC_E_UNSUPPORTED_FUNCTION	Nel parametro fContextReq è stato specificato un flag di attributo di contesto non valido (ISC_REQ_DELEGATE o ISC_REQ_PROMPT_FOR_CREDS).
edizione StandardC_E_WRONG_PRINCIPAL	L'entità che ha ricevuto la richiesta di autenticazione non corrisponde a quella passata al parametro pszTargetName . Ciò indica un errore nell'autenticazione reciproca.

Osservazioni

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 .

La funzione InitializeSecurityContext (Generale) viene usata da un client 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 (Generale).
AcceptSecurityContext (Generale) può restituire un token che il server invia al client per una seconda chiamata a InitializeSecurityContext (Generale) se la prima chiamata ha restituito edizione StandardC_I_CONTINUE_Nedizione Enterprise DED.

Per i contestidi sicurezza a più fasi, ad esempio l'autenticazione reciproca, la sequenza chiamante è la seguente:

Il client chiama la funzione come descritto in precedenza, ma il pacchetto restituisce il codice di operazione riuscita edizione StandardC_I_CONTINUE_Nedizione Enterprise DED.
Il client invia il token di output al server e attende la risposta del server.
Dopo la ricezione della risposta del server, il client chiama nuovamente InitializeSecurityContext (Generale), con phContext impostato sull'handle restituito dall'ultima chiamata. Il token ricevuto dal server viene fornito nel parametro pInput .
Non usare il valore phContext nelle chiamate simultanee a InitializeSecurityContext (Generale).Do not use the phContext value in concurrent calls to InitializeSecurityContext (General). L'implementazione nei provider di sicurezza non è thread-safe.

Se il server ha risposto correttamente, il pacchetto di sicurezza restituisce edizione StandardC_E_OK e viene stabilita una sessione protetta.

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 edizione StandardC_I_CONTINUE_Nedizione Enterprise DED, edizione StandardC_I_COMPLETE_Nedizione Enterprise DED o edizione StandardC_I_COMPLETE_AND_CONTINUE, i passaggi 2 e 3 vengono ripetuti.

Per inizializzare un contesto di sicurezza, potrebbero essere necessarie più chiamate 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. Il parametro pfContextAttributes è valido per qualsiasi restituzione riuscita, ma solo in caso di esito positivo finale, è necessario esaminare i flag relativi agli aspetti di sicurezza del contesto. I valori restituiti intermedi possono essere impostati, ad esempio, il flag ISC_RET_ALLOCATED_MEMORY.

Se il flag ISC_REQ_Uedizione Standard_SUPPLIED_CREDS è impostato, il pacchetto di sicurezza deve cercare un tipo di buffer edizione StandardCBUFFER_PKG_PARAMS nel buffer di input pInput. Questa non è una soluzione generica, ma 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 sfida di 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 è edizione StandardC_E_OK, non verrà eseguita alcuna seconda chiamata InitializeSecurityContext (Generale) e non sarà prevista alcuna risposta dal server. Se il codice restituito è edizione StandardC_I_CONTINUE_Nedizione Enterprise DED, il client prevede un token in risposta dal server e lo passa in una seconda chiamata a InitializeSecurityContext (Generale).If the return code is edizione StandardC_I_CONTINUE_Nedizione Enterprise DED, the client expects a token in response from the server and pass it in a second call to InitializeSecurityContext (General). Il codice restituito edizione StandardC_I_COMPLETE_Nedizione Enterprise DED indica che il client deve completare la compilazione del messaggio e chiamare la funzione CompleteAuthToken. Il codice edizione StandardC_I_COMPLETE_AND_CONTINUE incorpora entrambe queste azioni.

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

Il client può chiamare di nuovo InitializeSecurityContext (Generale) al termine dell'operazione. Indica al pacchetto di sicurezza che è necessario eseguire di nuovo l'autenticazione.

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

Quando si usa il provider di servizi condivisi Schannel, se la funzione restituisce edizione StandardC_I_INCOMPLETE_CREDENTIALS, verificare di aver specificato un certificato valido e attendibile nelle credenziali. Il certificato viene specificato quando si chiama la funzione AcquireCredentialsHandle (Generale). Il certificato deve essere un certificato di autenticazione client emesso da un'autorità di certificazione (CA) attendibile dal server. Per ottenere un elenco delle ca attendibili dal server, chiamare la funzione QueryContextAttributes (Generale) e specificare l'attributo edizione StandardCPKG_ATTR_ISSUER_LIST_EX.

Quando si usa il provider di servizi condivisi Schannel, dopo che un'applicazione client riceve un certificato di autenticazione da una CA considerata attendibile dal server, l'applicazione crea una nuova credenziale chiamando la funzione AcquireCredentialsHandle (Generale) e quindi chiamando nuovamente InitializeSecurityContext (Generale), specificando le nuove credenziali nel parametro phCredential .

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Intestazione	Sspi.h (include Security.h)
Libreria	Secur32.lib
DLL	Secur32.dll
Nomi Unicode e ANSI	InitializeSecurityContextW (Unicode) e InitializeSecurityContextA (ANSI)