Fonction AcquireCredentialsHandle (Général)

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

Notes

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

 

Pour plus d’informations sur l’utilisation de cette fonction avec un fournisseur de support de sécurité (SSP) spécifique, consultez les rubriques suivantes.

Rubrique	Description
AcquireCredentialsHandle (CredSSP)	Acquiert un handle pour les informations d’identification préexistantes d’un principal de sécurité qui utilise le fournisseur de prise en charge de la sécurité des informations d’identification (CredSSP).
AcquireCredentialsHandle (Digest)	Acquiert un handle pour les informations d’identification préexistantes d’un principal de sécurité qui utilise Digest.
AcquireCredentialsHandle (Kerberos)	Acquiert un handle pour les informations d’identification préexistantes d’un principal de sécurité qui utilise Kerberos.
AcquireCredentialsHandle (Negotiate)	Acquiert un handle pour les informations d’identification préexistantes d’un principal de sécurité qui utilise Negotiate.
AcquireCredentialsHandle (NTLM)	Acquiert un handle pour les informations d’identification préexistantes d’un principal de sécurité qui utilise NTLM.
AcquireCredentialsHandle (Schannel)	Acquiert un handle pour les informations d’identification préexistantes d’un principal de sécurité qui utilise Schannel.

 

Syntaxe

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

Paramètres

pszPrincipal [in]

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 partagés Digest, ce paramètre est facultatif.

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

Notes

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 s’exécute.

 

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 (Général) peut être appelé avec ulAttribute défini sur SECPKG_ATTR_PACKAGE_INFO pour retourner des informations sur le package de sécurité utilisé.

Lorsque vous utilisez le fournisseur de services partagés Digest, définissez ce paramètre sur WDIGEST_SP_NAME.

Lorsque vous utilisez le 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.

Valeur	Signification
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	La sécurité n’utilise pas les informations d’identification d’ouverture de session par défaut ou les informations d’identification du Gestionnaire d’informations d’identification. Cette valeur est prise en charge uniquement par la délégation contrainte Negotiate. Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
SECPKG_CRED_BOTH	Validez les informations d’identification entrantes ou utilisez des informations d’identification locales pour préparer un jeton sortant. Cet indicateur active les deux autres indicateurs. Cet indicateur n’est pas valide avec les SSP Digest et Schannel.
SECPKG_CRED_INBOUND	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 (Général) ou AcceptSecurityContext (Général) 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	Autoriser les informations d’identification d’un client local à préparer un jeton sortant.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	La fonction traite la stratégie de serveur et retourne SEC_E_NO_CREDENTIALS, indiquant que l’application doit demander des informations d’identification. Cette valeur est prise en charge uniquement par la délégation contrainte Negotiate. Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

 

pvLogonID [in]

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 SSP Schannel, ce paramètre n’est pas utilisé et doit être défini sur NULL.

pAuthData [in]

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 tout ce qui a été fourni dans RpcBindingSetAuthInfo.

Lorsque vous utilisez le fournisseur de services partagés Digest, ce paramètre est un pointeur vers une structure de SEC_WINNT_AUTH_IDENTITY qui contient des informations d’authentification à utiliser pour localiser les informations d’identification.

Lorsque vous utilisez le SSP SCHANNEL, spécifiez une structure de SCHANNEL_CRED qui indique le protocole à utiliser et les paramètres pour les différentes fonctionnalités de canal personnalisables.

Lorsque vous utilisez les packages NTLM ou Negotiate, les longueurs de caractères maximales pour le nom d’utilisateur, le mot de passe et le domaine sont respectivement de 256, 256 et 15.

pGetKeyFn [in]

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

pvGetKeyArgument [in]

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]

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.

Ce paramètre est défini sur une durée maximale constante. Il n’existe aucun délai d’expiration pour les informations d’identification ou le contexte de sécuritéDigest ou lors de l’utilisation du fournisseur de services partagés Digest.

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 le délai 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.

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 qui n’a pas été mappée à un code d’erreur SSPI s’est produite.
SEC_E_NO_CREDENTIALS	Aucune information d’identification n’est disponible dans la délégation contrainte.
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.

 

Notes

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

En général, AcquireCredentialsHandle (Général) 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’SE_TCB_NAME privilège a la possibilité de spécifier l’identificateur d’ouverture de session (LUID) de tout jeton de session d’ouverture de session existant pour obtenir un handle aux 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 des 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 de 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 .

Spécifications

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
En-tête	Sspi.h (include Security.h)
Bibliothèque	Secur32.lib
DLL	Secur32.dll
Noms Unicode et ANSI	AcquireCredentialsHandleW (Unicode) et AcquireCredentialsHandleA (ANSI)

Voir aussi

Fonctions SSPI

AcceptSecurityContext (Général)

InitializeSecurityContext (Général)

FreeCredentialsHandle