Funzione AcquireCredentialsHandleA (sspi.h)

Articolo
11/20/2024

La funzione AcquireCredentialsHandle (AcquireCredentialsHandle) acquisisce un handle per preesistribuire credenziali di un'entità di sicurezza . Questo handle è richiesto dalle funzioni InitializeSecurityContext (CredSSP) e AcceptSecurityContext (CredSSP). Queste credenziali possono essere preesistenti credenziali, che vengono stabilite tramite un accesso di sistema non descritto qui oppure il chiamante può fornire credenziali alternative.

Nota Questo non è un "accesso alla rete" e non implica la raccolta di credenziali.

Sintassi

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
  [in, optional]  LPSTR          pszPrincipal,
  [in]            LPSTR          pszPackage,
  [in]            unsigned long  fCredentialUse,
  [in, optional]  void           *pvLogonId,
  [in, optional]  void           *pAuthData,
  [in, optional]  SEC_GET_KEY_FN pGetKeyFn,
  [in, optional]  void           *pvGetKeyArgument,
  [out]           PCredHandle    phCredential,
  [out, optional] PTimeStamp     ptsExpiry
);

Parametri

[in, optional] pszPrincipal

Puntatore a una stringa con terminazione Null che specifica il nome dell'entità di cui farà riferimento l'handle.

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 con il contesto di sicurezza in esecuzione.

[in] 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 nome di una struttura SecPkgInfo restituita dalla funzione EnumerateSecurityPackages. Dopo aver stabilito un contesto, è possibile chiamare QueryContextAttributes (CredSSP) con ulAttribute impostato su SECPKG_ATTR_PACKAGE_INFO per restituire informazioni sul pacchetto di sicurezza in uso.

[in] fCredentialUse

Flag che indica come verranno usate queste credenziali. Questo parametro può essere uno dei valori seguenti.

Valore	Significato
SECPKG_CRED_INBOUND 0x1	Convalidare le credenziali del server in ingresso. Le credenziali in ingresso possono essere convalidate usando un'autorità di autenticazione quando viene chiamato InitializeSecurityContext (CredSSP) o AcceptSecurityContext (CredSSP). 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 0x2	Consentire a credenziali client locali di preparare un token in uscita.

Valore

Significato

SECPKG_CRED_INBOUND
0x1

Convalidare le credenziali del server in ingresso. Le credenziali in ingresso possono essere convalidate usando un'autorità di autenticazione quando viene chiamato InitializeSecurityContext (CredSSP) o AcceptSecurityContext (CredSSP). 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
0x2

Consentire a credenziali client locali di preparare un token in uscita.

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

[in, optional] pAuthData

Puntatore a una struttura CREDSSP_CRED che specifica i dati di autenticazione per i pacchetti Schannel e Negotiate.

[in, optional] pGetKeyFn

Riservato. Questo parametro non viene usato e deve essere impostato su NULL.

[in, optional] pvGetKeyArgument

Riservato. Questo parametro deve essere impostato su NULL.

[out] phCredential

Puntatore alla struttura CredHandle che riceverà l'handle delle credenziali.

[out, optional] ptsExpiry

Puntatore a una struttura di TimeStamp che riceve l'ora di scadenza delle credenziali restituite. Il valore della struttura ricevuto dipende dal pacchetto di sicurezza, che deve specificare il valore nell'ora locale.

Valore restituito

Se la funzione ha esito positivo, restituisce SEC_E_OK.

Se la funzione ha esito negativo, 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_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.

Osservazioni

La funzione AcquireCredentialsHandle (CredSSP) restituisce un handle alle credenziali di un'entità, ad esempio un utente o un client, 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 AcceptSecurityContext (CredSSP) e InitializeSecurityContext (CredSSP).

In generale, AcquireCredentialsHandle (CredSSP) 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 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 FreeCredentialsHandle.

Nota

L'intestazione sspi.h definisce AcquireCredentialsHandle come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2008 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	sspi.h (include Security.h)
libreria	Secur32.lib
dll	Secur32.dll

Vedere anche

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle

InitializeSecurityContext (CredSSP)

funzioni SSPI

Condividi tramite