Funzione AcquireCredentialsHandle (CredSSP)
La funzione AcquireCredentialsHandle (CredSSP) acquisisce un handle per preesistribuire le credenziali di un'entità di sicurezza. Questo handle è richiesto dalle funzioni InitializeSecurityContext (CredSSP) e AcceptSecurityContext (CredSSP). 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.
Sintassi
SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandle(
_In_opt_ SEC_CHAR *pszPrincipal,
_In_ SEC_CHAR *pszPackage,
_In_ unsigned long fCredentialUse,
_In_opt_ void *pvLogonID,
_In_opt_ void *pAuthData,
_In_opt_ SEC_GET_KEY_FN pGetKeyFn,
_Reserved_ void *pvGetKeyArgument,
_Out_ PCredHandle phCredential,
_Out_opt_ PTimeStamp ptsExpiry
);
Parametri
pszPrincipal [in, facoltativo]
Puntatore a una stringa con terminazione null che specifica il nome dell'entità le cui credenziali fanno 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 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 (CredSSP) può essere chiamato con ulAttribute impostato su SECPKG_ATTR_PACKAGE_INFO per restituire informazioni sul pacchetto di sicurezza in uso.
fCredentialUse [in]
Flag che indica come verranno usate queste credenziali. Questo parametro può avere 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 chiamata 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 0x0 |
Consentire a una credenziale client locale di preparare un token in uscita. |
pvLogonId [in, facoltativo]
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 [in, facoltativo]
Puntatore a una struttura CREDSSP_CRED che specifica i dati di autenticazione per i pacchetti Schannel e Negotiate.
pGetKeyFn [in, facoltativo]
Riservato. Questo parametro non viene usato e deve essere impostato su NULL.
pvGetKeyArgument [in, facoltativo]
Riservato. Questo parametro deve essere impostato su NULL.
phCredential [out]
Puntatore alla struttura CredHandle che riceverà l'handle delle credenziali.
ptsExpiry [out, facoltativo]
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
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 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 AcquireCredentialsHandle (CredSSP) 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 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 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 FreeCredentialsHandle .
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Intestazione | Sspi.h (include Security.h) |
| Libreria | Secur32.lib |
| DLL | Secur32.dll |
| Nomi Unicode e ANSI | AcquireCredentialsHandleW (Unicode) e AcquireCredentialsHandleA (ANSI) |