Funzione SspiAcquireCredentialsHandleAsyncA (sspi.h)

  • Articolo

La funzione SspiAcquireCredentialsHandleAsyncA acquisisce in modo asincrono un handle per preesistribuire le credenziali di un'entità di sicurezza.

Questo handle è richiesto dalle funzioni SspiInitializeSecurityContextAsync e SspiAcceptSecurityContextAsync . Possono trattarsi di credenziali preesistenti, stabilite tramite un accesso di sistema non descritto qui oppure il chiamante può fornire credenziali alternative.

Nota

Questa funzione funge da controparte asincrona di AcquireCredentialsHandle.

Sintassi

SECURITY_STATUS SspiAcquireCredentialsHandleAsyncA(
  SspiAsyncContext *AsyncContext,
  LPSTR            pszPrincipal,
  LPSTR            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.

pszPackage

Puntatore a una stringa con terminazione Null che specifica il nome del pacchetto di sicurezza con cui verranno usate queste credenziali.

Vedere AcquireCredentialsHandleA: pszPackage

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 di 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 durante il tentativo 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 mappato 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 SspiAcquireCredentialsHandleAsyncA 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 alle credenziali preesistenti o alle credenziali appena create e restituirla. Questo handle può essere usato nelle chiamate successive alle funzioni SspiAcceptSecurityContextAsync e SspiInitializeSecurityContextAsync .

In generale, SspiAcquireCredentialsHandleAsyncA 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 fornita dal trasporto rpc in fase di esecuzione. 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

Requisito Valore
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

AcquireCredentialsHandle

SspiAcceptSecurityContextAsync

SspiFreeCredentialsHandleAsync

SspiInitializeSecurityContextAsync

Funzioni SSPI