Fonction AcquireCredentialsHandleA (sspi.h)

Article
08/26/2023

La fonction AcquireCredentialsHandle (CredSSP) acquiert un handle pour les informations d’identification préexistantes d’un principal de sécurité. Ce handle est requis par les fonctions InitializeSecurityContext (CredSSP) et AcceptSecurityContext (CredSSP). 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.

Note Il ne s’agit pas d’une « connexion au réseau » et n’implique pas la collecte d’informations d’identification.

Syntaxe

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

Paramètres

[in, optional] pszPrincipal

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.

Note Si le processus qui demande le handle n’a pas accès aux informations d’identification, la fonction retourne une erreur. Une chaîne null indique que le processus nécessite un handle pour les informations d’identification de l’utilisateur sous lequel il exécute le contexte de sécurité .

[in] pszPackage

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 (CredSSP) 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.

[in] fCredentialUse

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

Valeur	Signification
SECPKG_CRED_INBOUND 0x1	Valider les informations d’identification d’un serveur entrant. Les informations d’identification entrantes peuvent être validées à l’aide d’une autorité d’authentification lorsque InitializeSecurityContext (CredSSP) ou AcceptSecurityContext (CredSSP) est appelé. Si une telle autorité n’est pas disponible, la fonction échoue et retourne SEC_E_NO_AUTHENTICATING_AUTHORITY. La validation est spécifique au package.
SECPKG_CRED_OUTBOUND 0x2	Autoriser les informations d’identification d’un client local à préparer un jeton sortant.

Valeur

Signification

SECPKG_CRED_INBOUND
0x1

Valider les informations d’identification d’un serveur entrant. Les informations d’identification entrantes peuvent être validées à l’aide d’une autorité d’authentification lorsque InitializeSecurityContext (CredSSP) ou AcceptSecurityContext (CredSSP) est appelé. Si une telle autorité n’est pas disponible, la fonction échoue et retourne SEC_E_NO_AUTHENTICATING_AUTHORITY. La validation est spécifique au package.

SECPKG_CRED_OUTBOUND
0x2

Autoriser les informations d’identification d’un client local à préparer un jeton sortant.

[in, optional] pvLogonId

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.

[in, optional] pAuthData

Pointeur vers une structure de CREDSSP_CRED qui spécifie les données d’authentification pour les packages Schannel et Negotiate.

[in, optional] pGetKeyFn

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

[in, optional] pvGetKeyArgument

Réservé. Ce paramètre doit avoir la valeur NULL.

[out] phCredential

Pointeur vers la structure CredHandle qui recevra le handle d’informations d’identification.

[out, optional] ptsExpiry

Pointeur vers une structure TimeStamp qui reçoit l’heure à laquelle les informations d’identification retournées expirent. La valeur de structure reçue dépend du package de sécurité, qui doit spécifier la valeur en heure locale.

Valeur retournée

Si la fonction réussit, elle retourne SEC_E_OK.

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

Code de retour	Description
SEC_E_INSUFFICIENT_MEMORY	La mémoire disponible est insuffisante pour effectuer l’action demandée.
SEC_E_INTERNAL_ERROR	Une erreur s’est produite qui n’a pas été mappée à un code d’erreur SSPI.
SEC_E_NO_CREDENTIALS	Aucune information d’identification n’est disponible dans le package de sécurité.
SEC_E_NOT_OWNER	L’appelant de la fonction ne dispose pas des informations d’identification nécessaires.
SEC_E_SECPKG_NOT_FOUND	Le package de sécurité demandé n’existe pas.
SEC_E_UNKNOWN_CREDENTIALS	Les informations d’identification fournies au package n’ont pas été reconnues.

Remarques

La fonction AcquireCredentialsHandle (CredSSP) retourne un handle aux informations d’identification d’un principal, comme un utilisateur ou un client, tel qu’utilisé par un package de sécurité spécifique. La fonction peut retourner le handle à des informations d’identification préexistantes ou des informations d’identification nouvellement créées et le retourner. Ce handle peut être utilisé dans les appels suivants aux fonctions AcceptSecurityContext (CredSSP) et InitializeSecurityContext (CredSSP).

En général, AcquireCredentialsHandle (CredSSP) ne fournit pas les informations d’identification des autres utilisateurs connectés au même ordinateur. Toutefois, un appelant disposant d’un privilège SE_TCB_NAME peut obtenir les informations d’identification d’une session d’ouverture de session existante en spécifiant l’identificateur d’ouverture de session (LUID) 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 avoir la valeur 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 .

Notes

L’en-tête sspi.h définit AcquireCredentialsHandle comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise


Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	sspi.h (include Security.h)
Bibliothèque	Secur32.lib
DLL	Secur32.dll

Voir aussi

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle

InitializeSecurityContext (CredSSP)

Fonctions SSPI