Funzione AcquireCredentialsHandleA (sspi.h)
La funzione AcquireCredentialsHandle (CredSSP) acquisisce un handle per anteporre le credenziali di un'entità di sicurezza. Questo handle è richiesto dalle funzioni InitializeSecurityContext (CredSSP) e AcceptSecurityContext (CredSSP). Possono trattarsi di credenziali preesistenti, stabilite tramite un accesso di sistema non descritto qui oppure il chiamante può fornire credenziali alternative.
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.
[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 Name 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ò avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Convalidare le credenziali del server in ingresso. È possibile convalidare le credenziali in ingresso 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. |
|
Consentire a una credenziale client locale 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 di 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 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 |
|---|---|
|
Memoria insufficiente per completare l'azione richiesta. |
|
Si è verificato un errore che non è stato mappato a un codice di errore SSPI. |
|
Nel pacchetto di sicurezza non sono disponibili credenziali. |
|
Il chiamante della funzione non dispone delle credenziali necessarie. |
|
Il pacchetto di sicurezza richiesto non esiste. |
|
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 alle credenziali preesistenti o alle credenziali 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 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.
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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | sspi.h (include Security.h) |
| Libreria | Secur32.lib |
| DLL | Secur32.dll |
Vedi anche
AcceptSecurityContext (CredSSP)
Commenti e suggerimenti
Presto disponibile: nel corso del 2024 verranno dismessi i problemi di GitHub come meccanismo di feedback per il contenuto e verranno sostituiti con un nuovo sistema di feedback. Per altre informazioni, vedere: https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per