Funzione AcquireCredentialsHandle (Generale)

Articolo
06/13/2023

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

Nota

Non si tratta di un "accesso alla rete" e non implica la raccolta di credenziali.

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

Argomento	Descrizione
AcquireCredentialsHandle (CredSSP)	Acquisisce un handle per preesistribuire le credenziali di un'entità di sicurezza che usa il provider di supporto per la sicurezza delle credenziali (CredSSP).
AcquireCredentialsHandle (Digest)	Acquisisce un handle per preesistribuire le credenziali di un'entità di sicurezza che usa Digest.
AcquireCredentialsHandle (Kerberos)	Acquisisce un handle per preesistribuire le credenziali di un'entità di sicurezza che usa Kerberos.
AcquireCredentialsHandle (Negoziazione)	Acquisisce un handle per preesistribuire le credenziali di un'entità di sicurezza che usa Negotiate.
AcquireCredentialsHandle (NTLM)	Acquisisce un handle per preesistribuire le credenziali di un'entità di sicurezza che usa NTLM.
AcquireCredentialsHandle (Schannel)	Acquisisce un handle per preesistribuire le credenziali di un'entità di sicurezza che usa Schannel.

Sintassi

SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
  _In_  SEC_CHAR       *pszPrincipal,
  _In_  SEC_CHAR       *pszPackage,
  _In_  ULONG          fCredentialUse,
  _In_  PLUID          pvLogonID,
  _In_  PVOID          pAuthData,
  _In_  SEC_GET_KEY_FN pGetKeyFn,
  _In_  PVOID          pvGetKeyArgument,
  _Out_ PCredHandle    phCredential,
  _Out_ PTimeStamp     ptsExpiry
);

Parametri

pszPrincipal [in]

Puntatore a una stringa con terminazione null che specifica il nome dell'entità le cui credenziali fanno riferimento l'handle.

Quando si usa il provider di servizi di spostamento del digest, questo parametro è facoltativo.

Quando si usa Schannel SSP, questo parametro non viene usato e deve essere impostato su NULL.

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 [in]

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 (Generale) può essere chiamato con ulAttribute impostato su SECPKG_ATTR_PACKAGE_INFO per restituire informazioni sul pacchetto di sicurezza in uso.

Quando si usa il provider di servizi di spostamento del digest, impostare questo parametro su WDIGEST_SP_NAME.

Quando si usa Schannel SSP, impostare questo parametro su UNISP_NAME.

fCredentialUse [in]

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

Valore	Significato
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	La sicurezza non usa le credenziali di accesso predefinite o le credenziali da Credential Manager. Questo valore è supportato solo dalla delega vincolata Negoziata. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato.
SECPKG_CRED_BOTH	Convalidare una credenziale in ingresso o usare le credenziali locali per preparare un token in uscita. Questo flag abilita entrambi gli altri flag. Questo flag non è valido con gli SSP Digest e Schannel.
SECPKG_CRED_INBOUND	Convalidare le credenziali del server in ingresso. Le credenziali in ingresso possono essere convalidate usando un'autorità di autenticazione quando viene chiamata InitializeSecurityContext (Generale) o AcceptSecurityContext (Generale). 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.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	La funzione elabora i criteri del server e restituisce SEC_E_NO_CREDENTIALS, che indica che l'applicazione deve richiedere le credenziali. Questo valore è supportato solo dalla delega vincolata Negoziata. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato.

pvLogonID [in]

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.

Quando si usa Schannel SSP, questo parametro non viene usato e deve essere impostato su NULL.

pAuthData [in]

Puntatore ai dati specifici del pacchetto. Questo parametro può essere NULL, che indica che è necessario usare le credenziali predefinite per tale pacchetto di sicurezza . Per usare le credenziali fornite, passare una struttura SEC_WINNT_AUTH_IDENTITY che include tali credenziali in questo parametro. Il tempo di esecuzione RPC passa qualsiasi cosa fornita in RpcBindingSetAuthInfo.

Quando si usa il provider di servizi di spostamento del digest, questo parametro è un puntatore a una struttura SEC_WINNT_AUTH_IDENTITY che contiene le informazioni di autenticazione da usare per individuare le credenziali.

Quando si usa Schannel SSP, specificare una struttura SCHANNEL_CRED che indica il protocollo da usare e le impostazioni per varie funzionalità del canale personalizzabili.

Quando si usano i pacchetti NTLM o Negotiate, le lunghezze massime dei caratteri per nome utente, password e dominio sono rispettivamente 256, 256 e 15.

pGetKeyFn [in]

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

pvGetKeyArgument [in]

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

phCredential [out]

Puntatore a una struttura CredHandle per ricevere l'handle delle credenziali.

ptsExpiry [out]

Puntatore a una struttura TimeStamp che riceve il momento in cui le credenziali restituite scadono. Il valore restituito in questa struttura TimeStamp dipende dalla delega vincolata. Il pacchetto di sicurezza deve restituire questo valore nell'ora locale.

Questo parametro è impostato su un tempo massimo costante. Non è previsto alcun periodo di scadenza per il contesto di sicurezzadel digest o le credenziali o quando si usa il provider di servizi di gestione del digest.

Quando si usa Schannel SSP, questo parametro è facoltativo. Quando le credenziali da usare per l'autenticazione sono un certificato, questo parametro riceve l'ora di scadenza per tale certificato. Se non è stato fornito alcun certificato, viene restituito un valore di tempo massimo.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce SEC_E_OK.

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

Codice restituito	Descrizione
SEC_E_INSUFFICIENT_MEMORY	Non è disponibile memoria sufficiente 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 nella delega vincolata.
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 AcquireCredentialsHandle (Generale) restituisce un handle alle credenziali di un'entità, ad esempio un utente o un client, come usato da una delega vincolata specifica. Può trattarsi dell'handle di credenziali preesistenti oppure la funzione può creare un nuovo set di credenziali e restituirlo. Questo handle può essere usato nelle chiamate successive alle funzioni AcceptSecurityContext (Generale) e InitializeSecurityContext (Generale).

In generale , AcquireCredentialsHandle (Generale) non consente a un processo di ottenere un handle per le credenziali di altri utenti connessi allo stesso computer. Tuttavia, un chiamante con privilegi SE_TCB_NAME ha la possibilità di specificare l'identificatore di accesso (LUID) di qualsiasi token di sessione di accesso esistente per ottenere un handle per le credenziali 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 FreeCredentialsHandle .

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	AcquireCredentialsHandleW (Unicode) e AcquireCredentialsHandleA (ANSI)

Vedi anche

Funzioni SSPI
AcceptSecurityContext (Generale)
InitializeSecurityContext (Generale)
FreeCredentialsHandle