Funzione SspiAcquireCredentialsHandleAsyncW (sspi.h)
La funzione SspiAcquireCredentialsHandleAsyncW acquisisce in modo asincrono un handle per preesistribuire le credenziali di un'entità di sicurezza.
Questo handle è richiesto dalle funzioni SspiInitializeSecurityContextAsync e SspiAcceptSecurityContextAsync . Queste possono essere credenziali preesistenti , che vengono stabilite tramite un accesso di sistema non descritto qui o il chiamante può fornire credenziali alternative.
Nota
Questa funzione funge da controparte asincrona di AcquireCredentialsHandle.
Sintassi
SECURITY_STATUS SspiAcquireCredentialsHandleAsyncW(
SspiAsyncContext *AsyncContext,
PSECURITY_STRING pszPrincipal,
PSECURITY_STRING pszPackage,
unsigned long fCredentialUse,
void *pvLogonId,
void *pAuthData,
SEC_GET_KEY_FN pGetKeyFn,
void *pvGetKeyArgument,
PCredHandle phCredential,
PTimeStamp ptsExpiry
);
Parametri
AsyncContext
Contesto di chiamata asincrona.
pszPrincipal
Puntatore a una stringa con terminazione null che specifica il nome dell'entità le cui credenziali l'handle farà riferimento in modo asincrono.
Nota
Se il processo che richiede l'handle non ha accesso alle credenziali, la funzione restituisce un errore. Una stringa Null indica che il processo richiede un handle per le credenziali dell'utente nel cui contesto di sicurezza viene eseguito.
pszPackage
Puntatore a una stringa con terminazione null che specifica il nome del pacchetto di sicurezza con cui verranno usate queste credenziali. Si tratta di un nome del pacchetto di sicurezza restituito nel membro Name di una struttura SecPkgInfo restituita dalla funzione EnumerateSecurityPackages . Dopo aver stabilito un contesto, QueryContextAttributes (CredSSP) può essere chiamato con ulAttribute impostato su SECPKG_ATTR_PACKAGE_INFO per restituire informazioni sul pacchetto di sicurezza in uso.
fCredentialUse
Flag che indica come verranno usate queste credenziali. Questo parametro può essere uno dei valori seguenti:
valore |
Significato |
|---|---|
| SECPKG_CRED_INBOUND | Convalidare le credenziali del server in ingresso. Le credenziali in ingresso possono essere convalidate usando un'autorità di autenticazione quando viene chiamato SspiInitializeSecurityContextAsync o SspiAcceptSecurityContextAsync . Se tale autorità non è disponibile, la funzione avrà esito negativo e restituirà SEC_E_NO_AUTHENTICATING_AUTHORITY. La convalida è specifica del pacchetto. |
| SECPKG_CRED_OUTBOUND | Consentire a una credenziale client locale di preparare un token in uscita. |
pvLogonId
Puntatore a un identificatore univoco locale (LUID) che identifica l'utente. Questo parametro viene fornito per i processi del file system, ad esempio i reindirizzamenti di rete. Questo parametro può essere NULL.
pAuthData
Puntatore a una struttura CREDSSP_CRED che specifica i dati di autenticazione per i pacchetti Schannel e Negotiate.
pGetKeyFn
Puntatore alla funzione GetKey().
pvGetKeyArgument
Passare a GetKey().
phCredential
Puntatore alla struttura CredHandle che riceverà l'handle delle credenziali.
ptsExpiry
Opzionale Puntatore a una struttura TimeStamp che riceve il momento in cui le credenziali restituite scadono. Il valore della struttura ricevuto dipende dal pacchetto di sicurezza, che deve specificare il valore nell'ora locale.
Valore restituito
Restituisce SEC_E_OK se la richiesta asincrona per acquisire un handle di credenziali è stata accodata correttamente per l'esecuzione. In caso contrario, restituisce l'errore generato tentando di accodarlo. Per recuperare lo stato dell'operazione, usare SspiGetAsyncCallStatus.
Se l'handle è stato acquisito, SspiGetAsyncCallStatus restituisce SEC_E_OK. In caso contrario, può restituire SEC_I_ASYNC_CALL_PENDING se la chiamata è ancora in corso o uno dei codici di errore irreversibili seguenti nella tabella seguente.
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 eseguito il mapping a un codice di errore SSPI. |
| SEC_E_NO_CREDENTIALS | Nessuna credenziale disponibile nel pacchetto di sicurezza |
| SEC_E_NOT_OWNER | Il chiamante della funzione non dispone delle credenziali necessarie. |
| SEC_E_SECPKG_NOT_FOUND | Il pacchetto di sicurezza richiesto non esiste. |
| SEC_E_UNKNOWN_CREDENTIALS | Le credenziali fornite al pacchetto non sono state riconosciute. |
Commenti
La funzione SspiAcquireCredentialsHandleAsyncW restituisce un handle alle credenziali di un'entità, ad esempio un utente o un client, come usato da un pacchetto di sicurezza specifico. La funzione può restituire l'handle a credenziali preesistenti o appena create e restituirla. Questo handle può essere usato nelle chiamate successive alle funzioni SspiAcceptSecurityContextAsync e SspiInitializeSecurityContextAsync .
In generale, SspiAcquireCredentialsHandleAsyncW non fornisce le credenziali di altri utenti connessi allo stesso computer. Tuttavia, un chiamante con privilegi SE_TCB_NAME può ottenere le credenziali di una sessione di accesso esistente specificando l'identificatore di accesso (LUID) di tale sessione. In genere, questo viene usato dai moduli in modalità kernel che devono agire per conto di un utente connesso.
Un pacchetto potrebbe chiamare la funzione in pGetKeyFn fornito dal trasporto di runtime RPC. Se il trasporto non supporta la nozione di callback per recuperare le credenziali, questo parametro deve essere NULL.
Per i chiamanti in modalità kernel, è necessario notare le differenze seguenti:
- I due parametri stringa devono essere stringhe Unicode .
- I valori del buffer devono essere allocati nella memoria virtuale del processo, non dal pool.
Al termine dell'uso delle credenziali restituite, liberare la memoria usata dalle credenziali chiamando la funzione SspiFreeCredentialsHandleAsync .
Requisiti
| Client minimo supportato | Windows 10 versione 1607 [solo driver in modalità kernel] |
| Server minimo supportato | Windows Server 2016 [solo driver in modalità kernel] |
| Intestazione | sspi.h |
Vedi anche
SspiAcceptSecurityContextAsync
SspiFreeCredentialsHandleAsync