AcquireCredentialsHandle (SChannel) (fonction)

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

Notes

Ce n’est pas une « connexion au réseau » et n’implique pas la collecte des 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 [ dans, facultatif]

Pointeur vers une chaîne se terminant par un caractère null qui spécifie le nom du principal dont les informations d’identification seront référencées par le handle.

Lorsque vous utilisez le SSP Schannel, ce paramètre n’est pas utilisé et doit avoir la valeur null.

Notes

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

pszPackage [ dans]

Pointeur vers une chaîne se terminant par un caractère 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é renvoyé 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 SSP Schannel, définissez ce paramètre sur UNISP _ Name.

fCredentialUse [ dans]

Indicateur qui spécifie la façon dont ces informations d’identification seront utilisées. Ce paramètre peut prendre les valeurs suivantes.

Valeur Signification
SECPKG _ cred _ entrant
Validez les informations d’identification du serveur entrant. Les informations d’identification entrantes peuvent être validées à l’aide d’une autorité d’authentification lorsque InitializeSecurityContext (SChannel) ou AcceptSecurityContext (SChannel) est appelé. Si une autorité de ce type n’est pas disponible, la fonction échoue et retourne SEC _ E _ no _ Authority Authentication _ . La validation est spécifique au package.
SECPKG _ cred _ sortant
Autorisez les informations d’identification du client local à préparer un jeton sortant.

pvLogonID [ dans, facultatif]

Pointeur vers un identificateur unique local (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 avoir la valeur null.

pAuthData [ dans, facultatif]

Pointeur vers des données spécifiques au package. Ce paramètre peut avoir la valeur null, ce qui indique que les informations d’identification par défaut pour ce package de sécurité doivent être utilisées. Pour utiliser les informations d’identification fournies, transmettez une structure d' _ _ _ identité Winnt auth s qui comprend 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 SSP Schannel, spécifiez une structure SCH_CREDENTIALS qui indique le protocole à utiliser, ainsi que les paramètres des différentes fonctionnalités de canal personnalisables.

pGetKeyFn [ dans, facultatif]

Ce paramètre n’est pas utilisé et doit avoir la valeur null.

pvGetKeyArgument [ dans, facultatif]

Ce paramètre n’est pas utilisé et doit avoir la valeur null.

phCredential [ à]

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

ptsExpiry [ out, facultatif]

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

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

Si la fonction s’exécute correctement, la fonction retourne SEC _ E _ OK.

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

Code de retour Description
s _ E _ mémoire insuffisante _
La mémoire disponible est insuffisante pour terminer l’action demandée.
SEC _ E _ _ erreur interne
Une erreur qui n’a pas été mappée à un code d’erreur SSPI s’est produite.
s _ E _ aucune _ information d’identification
Aucune information d’identification n’est disponible dans la délégation conpressionnelle.
SEC _ E _ non _ propriétaire
L’appelant de la fonction n’a pas les informations d’identification nécessaires.
SEC _ E _ SECPKG _ _ introuvable
Le package de sécurité demandé n’existe pas.
SEC _ E _ _ informations d’identification inconnues
Les informations d’identification fournies au package n’ont pas été reconnues.

Notes

La fonction AcquireCredentialsHandle (SChannel) retourne un handle vers les informations d’identification d’un principal, tel qu’un utilisateur ou un client, tel qu’il est utilisé par une délégation restreintespécifique. Il peut s’agir du descripteur des informations d’identification préexistantes, ou la fonction peut créer un nouvel ensemble d’informations d’identification et la retourner. Ce handle peut être utilisé dans les appels ultérieurs aux fonctions AcceptSecurityContext (SChannel) et InitializeSecurityContext (SChannel) .

En général, AcquireCredentialsHandle (SChannel) ne permet pas à un processus d’obtenir un descripteur des informations d’identification d’autres utilisateurs ayant ouvert une session sur le même ordinateur. toutefois, un appelant avec SE _ _ privilège nom TCB a la possibilité de spécifier l' identificateur de connexion (LUID) d’un jeton de session de connexion existant pour obtenir un descripteur des informations d’identification de cette session. En général, il 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 dans le 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 [Applications de bureau XP uniquement]
Serveur minimal pris en charge
Windows Serveur 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

AcceptSecurityContext (SChannel)

FreeCredentialsHandle

InitializeSecurityContext (SChannel)

SCH_CREDENTIALS

Fonctions SSPI