Funzione AcquireCredentialsHandle (Schannel)

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

Sintassi

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

Parametri

pszPrincipal[in, optional]

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

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

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

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.

pvLogonID[in, optional]

Puntatore a un identificatore univoco locale (LUID) che identifica l'utente. Questo parametro viene fornito per i processi di 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, optional]

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 Schannel SSP, specificare una struttura SCH_CREDENTIALS che indica il protocollo da usare e le impostazioni per varie funzionalità del canale personalizzabili.

pGetKeyFn[in, optional]

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

pvGetKeyArgument[in, optional]

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, optional]

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.

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.

Commenti

La funzione AcquireCredentialsHandle (Schannel) restituisce un handle alle credenziali di un'entità, ad esempio un utente o un client, come usato da una delega vincolata specifica. Questo può essere l'handle per preesistribuire le credenziali oppure la funzione può creare un nuovo set di credenziali e restituirlo. Questo handle può essere usato nelle chiamate successive alle funzioni AcceptSecurityContext (Schannel) e InitializeSecurityContext (Schannel).

In generale , AcquireCredentialsHandle (Schannel) non consente a un processo di ottenere un handle alle credenziali di altri utenti connessi allo stesso computer. Tuttavia, un chiamante con privilegiSE_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 della 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

Vedi anche

AcceptSecurityContext (Schannel)

FreeCredentialsHandle

InitializeSecurityContext (Schannel)

SCH_CREDENTIALS

Funzioni SSPI