AcquireCredentialsHandleA, fonction (sspi.h)

Article
11/20/2024

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

Remarque Il ne s’agit pas d’une « connexion au réseau » et n’implique pas la collecte des 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 les informations d’identification sont référencées par le handle.

Remarque 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 aux informations d’identification de l’utilisateur sous lequel contexte de sécurité'il s’exécute.

[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 être l’une des valeurs suivantes.

Valeur	Signification
SECPKG_CRED_INBOUND 0x1	Validez 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ée. 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

Validez 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ée. 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 localement 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 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 être défini sur 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 dans l’heure locale.

Valeur de retour

Si la fonction réussit, elle retourne SEC_E_OK.

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

Retourner le code	Description
SEC_E_INSUFFICIENT_MEMORY	La mémoire disponible est insuffisante pour terminer 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 n’a pas les 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 renvoyer le handle à des informations d’identification préexistantes ou à des informations d’identification nouvellement créées et les renvoyer. 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 d’autres utilisateurs connectés au même ordinateur. Toutefois, un appelant avec SE_TCB_NAME privilège 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 au nom 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 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.

Lorsque 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.

Note

L’en-tête sspi.h définit AcquireCredentialsHandle comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	sspi.h (include Security.h)
bibliothèque	Secur32.lib
DLL	Secur32.dll

Voir aussi

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle

InitializeSecurityContext (CredSSP)

fonctions SSPI

Partager via