Condividi tramite


Funzione AcceptSecurityContext (Schannel)

La funzione AcceptSecurityContext (Schannel) consente al componente server di un'applicazione di trasporto di stabilire un contesto di sicurezza tra il server e un client remoto. Il client remoto usa la funzione InitializeSecurityContext (Schannel) per avviare il processo di definizione di un contesto di sicurezza. Il server può richiedere uno o più token di risposta dal client remoto per completare la definizione del contesto di sicurezza.

Sintassi

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsTimeStamp
);

Parametri

phCredential[in, optional]

Handle per le credenziali del server. Il server chiama la funzione AcquireCredentialsHandle (Schannel) con il flag SECPKG_CRED_INBOUND o SECPKG_CRED_BOTH impostato per recuperare questo handle.

phContext[in, out, optional]

Puntatore a una struttura CtxtHandle . Nella prima chiamata a AcceptSecurityContext (Schannel), questo puntatore è NULL. Nelle chiamate successive , phContext è l'handle del contesto parzialmente formato restituito nel parametro phNewContext dalla prima chiamata.

Avviso

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

pInput[in, optional]

Puntatore a una struttura SecBufferDesc generata da una chiamata client a InitializeSecurityContext (Schannel) che contiene il descrittore del buffer di input.

Quando si usa il provider di supporto per la sicurezza Schannel, il primo buffer deve essere di tipo SECBUFFER_TOKEN e contenere il token di sicurezza ricevuto dal client. Il secondo buffer deve essere di tipo SECBUFFER_EMPTY.

fContextReq[in]

Flag bit che specificano gli attributi richiesti dal server per stabilire il contesto. I flag bit possono essere combinati usando operazioni BIT-OR . Questo parametro può essere uno o più dei valori seguenti.

Valore Significato
ASC_REQ_ALLOCATE_MEMORY Digest e Schannel allocare i buffer di output per l'utente. Al termine dell'uso dei buffer di output, liberarli chiamando la funzione FreeContextBuffer .
ASC_REQ_CONFIDENTIALITY Crittografare e decrittografare i messaggi.
Il provider di servizi di gestione del digest supporta questo flag solo per SASL.
ASC_REQ_CONNECTION Il contesto di sicurezza non gestisce i messaggi di formattazione.
ASC_REQ_EXTENDED_ERROR Quando si verificano errori, la parte remota riceverà una notifica.
ASC_REQ_MUTUAL_AUTH Il client deve fornire un certificato da usare per l'autenticazione client.
ASC_REQ_REPLAY_DETECT Rilevare i pacchetti riprodotti.
ASC_REQ_SEQUENCE_DETECT Rilevare i messaggi ricevuti fuori dalla sequenza.
ASC_REQ_STREAM Supportare una connessione orientata al flusso.
Questo flag è supportato solo da Schannel.

Per i possibili flag di attributo e i relativi significati, vedere Requisiti di contesto. I flag usati per questo parametro sono preceduti da ASC_REQ, ad esempio ASC_REQ_DELEGATE.

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

TargetDataRep[in]

Questo parametro non viene usato con Schannel. Specificare zero per questo parametro.

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

Puntatore a una struttura SecBufferDesc contenente il descrittore del buffer di output. Questo buffer viene inviato al client per l'input in chiamate aggiuntive a InitializeSecurityContext (Schannel). Un buffer di output può essere generato anche se la funzione restituisce SEC_E_OK. Qualsiasi buffer generato deve essere inviato nuovamente all'applicazione client.

In output, questo buffer riceve un token per il contesto di sicurezza. Il token deve essere inviato al client. La funzione può anche restituire un buffer di tipo SECBUFFER_EXTRA. Inoltre, il chiamante deve passare un buffer di tipo SECBUFFER_ALERT. Nell'output, se viene generato un avviso, questo buffer contiene informazioni su tale avviso e la funzione ha esito negativo.

pfContextAttr[out]

Puntatore a una variabile che riceve 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 ASC_RET, ad esempio ASC_RET_DELEGATE.

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.

ptsTimeStamp[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 in ora locale.

Questo è facoltativo quando si usa Schannel SSP. Quando la entità remota ha fornito un certificato da usare per l'autenticazione, questo parametro riceve l'ora di scadenza per tale certificato. Se non è stato specificato alcun certificato, viene restituito un valore di tempo massimo.

Nota

Fino all'ultima chiamata del processo di autenticazione, la scadenza del contesto può essere errata perché altre informazioni verranno fornite durante le fasi successive della negoziazione. Pertanto, ptsTimeStamp deve essere NULL fino all'ultima chiamata alla funzione.

Valore restituito

Questa funzione restituisce uno dei valori seguenti.

Codice/valore restituitoDescrizione
SEC_E_INCOMPLETE_MESSAGE
0x80090318L
Funzione completata. I dati nel buffer di input sono incompleti. L'applicazione deve leggere di nuovo dati aggiuntivi dal client e chiamare [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md).
Quando viene restituito questo valore, il buffer pInput contiene una struttura [SecBuffer](/windows/win32/api/sspi/ns-sspi-secbuffer) con un membro BufferType di SECBUFFER_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ò aiutare le prestazioni evitando più chiamate a questa funzione.
SEC_E_INSUFFICIENT_MEMORY
0x80090300L
La funzione non è riuscita. Non è disponibile memoria sufficiente per completare l'azione richiesta.
SEC_E_INTERNAL_ERROR
0x80090304L
La funzione non è riuscita. Si è verificato un errore che non è stato eseguito il mapping a un codice di errore SSPI.
SEC_E_INVALID_HANDLE
0x80100003L
La funzione non è riuscita. L'handle passato alla funzione non è valido.
SEC_E_INVALID_TOKEN
0x80090308L
La funzione non è riuscita. Il token passato alla funzione non è valido.
SEC_E_LOGON_DENIED
0x8009030CL
L'accesso non è riuscito.
SEC_E_NO_AUTHENTICATING_AUTHORITY
0x80090311L
La funzione non è riuscita. Non è possibile contattare alcuna autorità per l'autenticazione. Ciò potrebbe essere dovuto alle condizioni seguenti:
  • Il nome di dominio della parte di autenticazione non è corretto.
  • Il dominio non è disponibile.
  • La relazione di trust non è riuscita.
SEC_E_NO_CREDENTIALS
0x8009030EL
La funzione non è riuscita. L'handle delle credenziali specificato nel parametro phCredential non è valido. Questo valore può essere restituito quando si usa il provider di servizi di azure digest o Schannel.
SEC_E_OK
0x00000000L
Funzione completata. [*contesto di sicurezza*](.. /secgloss/s-gly.md ricevuti dal client è stato accettato. Se un token di output è stato generato dalla funzione, deve essere inviato al processo client.
SEC_E_UNSUPPORTED_FUNCTION
0x80090302L
La funzione non è riuscita. Un flag di attributo di contesto non valido (ASC_REQ_DELEGATE o ASC_REQ_PROMPT_FOR_CREDS) è stato specificato nel parametro fContextReq .
SEC_E_APPLICATION_PROTOCOL_MISMATCH
0x80090367L
Non esiste alcun protocollo applicazione comune tra il client e il server.
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L
Funzione completata. Il server deve chiamare [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) e passare il token di output al client. Il server attende quindi un token restituito dal client e quindi effettua un'altra chiamata a [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md).
SEC_I_COMPLETE_NEEDED
0x00090313L
Funzione completata. Il server deve completare la compilazione del messaggio dal client e quindi chiamare la funzione [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken).
SEC_I_CONTINUE_NEEDED
0x00090312L
Funzione completata. Il server deve inviare il token di output al client e attendere che venga restituito un token. Il token restituito deve essere passato in pInput per un'altra chiamata a [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md).
STATUS_LOGON_FAILURE
0xC000006DL
La funzione non è riuscita. La funzione [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) è stata chiamata dopo la creazione del contesto specificato. Questo valore può essere restituito quando si usa il provider di servizi di gestione del digest.

Commenti

La funzione AcceptSecurityContext (Schannel) è la controparte del server alla funzione InitializeSecurityContext (Schannel).

Quando il server riceve una richiesta da un client, il server usa il parametro fContextReq per specificare le richieste della sessione. In questo modo, un server può specificare che i client devono essere in grado di usare una sessione riservata o controllata dall'integrità e possono rifiutare i client che non possono soddisfare tale domanda. In alternativa, un server può richiedere nulla e qualsiasi cosa il client possa fornire o richiedere venga restituito nel parametro pfContextAttr .

Per un pacchetto che supporta l'autenticazione a più gambe, ad esempio l'autenticazione reciproca, la sequenza chiamante è il seguente:

  1. Il client trasmette un token al server.
  2. Il server chiama AcceptSecurityContext (Schannel) la prima volta, che genera un token di risposta che viene quindi inviato al client.
  3. Il client riceve il token e lo passa a InitializeSecurityContext (Schannel). Se InitializeSecurityContext (Schannel) restituisce SEC_E_OK, l'autenticazione reciproca è stata completata e una sessione sicura può iniziare. Se InitializeSecurityContext (Schannel) restituisce un codice di errore, la negoziazione di autenticazione reciproca termina. In caso contrario, il token di sicurezza restituito da InitializeSecurityContext (Schannel) viene inviato al client e i passaggi 2 e 3 vengono ripetuti.
  4. Non usare il valore phContext nelle chiamate simultanee a AcceptSecurityContext (Schannel). L'implementazione nei provider di sicurezza non è thread-safe.

I parametri fContextReq e pfContextAttr sonomask bit che rappresentano vari attributi di contesto. Per una descrizione dei vari attributi, vedere Requisiti di contesto.

Nota

Il parametro pfContextAttr è valido in qualsiasi restituzione riuscita, ma solo sulla restituzione finale dovrebbe essere esaminato i flag relativi agli aspetti di sicurezza del contesto. I valori intermedi possono essere impostati, ad esempio, il flag di ISC_RET_ALLOCATED_MEMORY.

Il chiamante è responsabile per determinare se gli attributi di contesto finali sono sufficienti. Se, ad esempio, è stata richiesta la riservatezza (crittografia), ma non è stato possibile stabilire, alcune applicazioni possono scegliere di arrestare immediatamente la connessione. Se non è possibile stabilire il contesto di sicurezza , il server deve liberare il contesto parzialmente creato chiamando la funzione DeleteSecurityContext . Per informazioni su quando chiamare la funzione DeleteSecurityContext , vedere DeleteSecurityContext.

Dopo aver stabilito il contesto di sicurezza , l'applicazione server può usare la funzione QuerySecurityContextToken per recuperare un handle all'account utente a cui è stato eseguito il mapping del certificato client. Inoltre, il server può usare la funzione ImpersonateSecurityContext per rappresentare l'utente.

Requisiti

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

Vedi anche

Funzioni SSPI

DeleteSecurityContext

InitializeSecurityContext (Schannel)