Partager via

AcquireCredentialsHandle (CredSSP), fonction

  • Article

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.

Notes

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 AcquireCredentialsHandle(
  _In_opt_   SEC_CHAR       *pszPrincipal,
  _In_       SEC_CHAR       *pszPackage,
  _In_       unsigned long  fCredentialUse,
  _In_opt_   void           *pvLogonID,
  _In_opt_   void           *pAuthData,
  _In_opt_   SEC_GET_KEY_FN pGetKeyFn,
  _Reserved_ void           *pvGetKeyArgument,
  _Out_      PCredHandle    phCredential,
  _Out_opt_  PTimeStamp     ptsExpiry
);

Paramètres

pszPrincipal [in, facultatif]

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.

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

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_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
0x0		 Autoriser les informations d’identification d’un client local à préparer un jeton sortant.

pvLogonId [in, facultatif]

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.

pAuthData [in, facultatif]

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

pGetKeyFn [in, facultatif]

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

pvGetKeyArgument [in, facultatif]

Réservé. Ce paramètre doit être défini sur NULL.

phCredential [out]

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

ptsExpiry [out, facultatif]

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

Notes

La fonction AcquireCredentialsHandle (CredSSP) retourne un handle aux informations d’identification d’un principal, tel qu’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 la 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’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 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 Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [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