Fonction AcquireCredentialsHandle (Schannel)

La fonction AcquireCredentialsHandle (Schannel) acquiert un handle pour les informations d’identification préexistantes d’un principal de sécurité. Ce handle est requis par les fonctions InitializeSecurityContext (Schannel) et AcceptSecurityContext (Schannel). Il peut s’agir d’informations d’identification préexistantes, qui sont établies via une ouverture de session système qui n’est pas décrite ici, ou l’appelant peut fournir d’autres informations d’identification.

Syntaxe

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
);

Paramètres

pszPrincipal[in, optional]

Pointeur vers une chaîne terminée par null qui spécifie le nom du principal dont le handle référencera les informations d’identification.

Lorsque vous utilisez le fournisseur de services SSP Schannel, ce paramètre n’est pas utilisé et doit être défini sur NULL.

pszPackage[in]

Pointeur vers une chaîne terminée par null qui spécifie le nom du package de sécurité avec lequel ces informations d’identification seront utilisées. Il s’agit d’un nom de package de sécurité retourné dans le membre Name d’une structure SecPkgInfo retournée par la fonction EnumerateSecurityPackages . Une fois qu’un contexte est établi, QueryContextAttributes (Schannel) peut être appelé avec ulAttribute défini sur SECPKG_ATTR_PACKAGE_INFO pour retourner des informations sur le package de sécurité en cours d’utilisation.

Lorsque vous utilisez le fournisseur de services SSP Schannel, définissez ce paramètre sur UNISP_NAME.

fCredentialUse[in]

Indicateur qui indique comment ces informations d’identification seront utilisées. Ce paramètre peut prendre les valeurs suivantes.

pvLogonID[in, optional]

Pointeur vers un identificateur local unique (LUID) qui identifie l’utilisateur. Ce paramètre est fourni pour les processus de système de fichiers tels que les redirecteurs réseau. Ce paramètre peut être NULL.

Lorsque vous utilisez le fournisseur de services SSP Schannel, ce paramètre n’est pas utilisé et doit être défini sur NULL.

pAuthData[in, optional]

Pointeur vers des données spécifiques au package. Ce paramètre peut être NULL, ce qui indique que les informations d’identification par défaut de ce package de sécurité doivent être utilisées. Pour utiliser les informations d’identification fournies, transmettez une structure SEC_WINNT_AUTH_IDENTITY qui inclut ces informations d’identification dans ce paramètre. Le temps d’exécution RPC passe ce qui a été fourni dans RpcBindingSetAuthInfo.

Lorsque vous utilisez le fournisseur de services SSP Schannel, spécifiez une structure SCH_CREDENTIALS qui indique le protocole à utiliser et les paramètres des différentes fonctionnalités de canal personnalisables.

pGetKeyFn[in, optional]

Ce paramètre n’est pas utilisé et doit être défini sur NULL.

pvGetKeyArgument[in, optional]

Ce paramètre n’est pas utilisé et doit être défini sur NULL.

phCredential[out]

Pointeur vers une structure CredHandle pour recevoir le handle d’informations d’identification.

ptsExpiry[out, optional]

Pointeur vers une structure TimeStamp qui reçoit l’heure à laquelle les informations d’identification retournées expirent. La valeur retournée dans cette structure TimeStamp dépend de la délégation contrainte. Le package de sécurité doit retourner cette valeur en heure locale.

Lorsque vous utilisez le fournisseur SSP Schannel, ce paramètre est facultatif. Lorsque les informations d’identification à utiliser pour l’authentification sont un certificat, ce paramètre reçoit l’heure d’expiration de ce certificat. Si aucun certificat n’a été fourni, une valeur de temps maximale est retournée.

Valeur retournée

Si la fonction réussit, la fonction retourne SEC_E_OK.

Si la fonction échoue, elle retourne l’un des codes d’erreur suivants.

Remarques

La fonction AcquireCredentialsHandle (Schannel) retourne un handle aux informations d’identification d’un principal, comme un utilisateur ou un client, tel qu’utilisé par une délégation contrainte spécifique. Il peut s’agir du handle des informations d’identification préexistantes, ou la fonction peut créer un nouvel ensemble d’informations d’identification et le retourner. Ce handle peut être utilisé dans les appels suivants aux fonctions AcceptSecurityContext (Schannel) et InitializeSecurityContext (Schannel).

En général, AcquireCredentialsHandle (Schannel) n’autorise pas un processus à obtenir un handle pour les informations d’identification d’autres utilisateurs connectés au même ordinateur. Toutefois, un appelant disposant d’unprivilège SE_TCB_NAME a la possibilité de spécifier l’identificateur d’ouverture de session (LUID) de n’importe quel jeton de session d’ouverture de session existant pour obtenir un handle des informations d’identification de cette session. En règle générale, cela est utilisé par les modules en mode noyau qui doivent agir pour le compte d’un utilisateur connecté.

Un package peut appeler la fonction dans pGetKeyFn fournie par le transport d’exécution RPC. Si le transport ne prend pas en charge la notion de rappel pour récupérer les informations d’identification, ce paramètre doit être NULL.

Pour les appelants en mode noyau, les différences suivantes doivent être notées :

• Les deux paramètres de chaîne doivent être des chaînes Unicode .
• Les valeurs de mémoire tampon doivent être allouées dans la mémoire virtuelle du processus, et non à partir du pool.

Une fois que vous avez terminé d’utiliser les informations d’identification retournées, libérez la mémoire utilisée par les informations d’identification en appelant la fonction FreeCredentialsHandle .

Spécifications

Voir aussi

AcceptSecurityContext (Schannel)

FreeCredentialsHandle

InitializeSecurityContext (Schannel)

SCH_CREDENTIALS

Fonctions SSPI