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 |
|---|---|
|
La mémoire disponible est insuffisante pour terminer l’action demandée. |
|
Une erreur qui n’a pas été mappée à un code d’erreur SSPI s’est produite. |
|
Aucune information d’identification n’est disponible dans la délégation conpressionnelle. |
|
L’appelant de la fonction n’a pas les informations d’identification nécessaires. |
|
Le package de sécurité demandé n’existe pas. |
|
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 |
|
| Bibliothèque |
|
| DLL |
|
| Noms Unicode et ANSI |
AcquireCredentialsHandleW (Unicode) et AcquireCredentialsHandleA (ANSI) |
Voir aussi
InitializeSecurityContext (SChannel)