SspiAcquireCredentialsHandleAsyncW, fonction (sspi.h)

Article
08/26/2023

La fonction SspiAcquireCredentialsHandleAsyncW acquiert de manière asynchrone un handle pour les informations d’identification préexistantes d’un principal de sécurité.

Ce handle est requis par les fonctions SspiInitializeSecurityContextAsync et SspiAcceptSecurityContextAsync . 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

Cette fonction sert d’équivalent asynchrone à AcquireCredentialsHandle.

Syntaxe

SECURITY_STATUS SspiAcquireCredentialsHandleAsyncW(
  SspiAsyncContext *AsyncContext,
  PSECURITY_STRING pszPrincipal,
  PSECURITY_STRING pszPackage,
  unsigned long    fCredentialUse,
  void             *pvLogonId,
  void             *pAuthData,
  SEC_GET_KEY_FN   pGetKeyFn,
  void             *pvGetKeyArgument,
  PCredHandle      phCredential,
  PTimeStamp       ptsExpiry
);

Paramètres

AsyncContext

Contexte d’appel asynchrone.

pszPrincipal

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 de manière asynchrone.

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 exécute le contexte de sécurité .

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.

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	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 SspiInitializeSecurityContextAsync ou SspiAcceptSecurityContextAsync 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.

Valeur

Signification

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 SspiInitializeSecurityContextAsync ou SspiAcceptSecurityContextAsync 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.

pvLogonId

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

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

pGetKeyFn

Pointeur vers la fonction GetKey().

pvGetKeyArgument

Passez à GetKey().

phCredential

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

ptsExpiry

Optionnel 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

Retourne SEC_E_OK si la demande asynchrone d’acquisition d’un handle d’informations d’identification a été correctement mise en file d’attente pour l’exécution. Sinon, il retourne l’erreur générée lors de la tentative de mise en file d’attente. Pour récupérer les status de l’opération, utilisez SspiGetAsyncCallStatus.

Si le handle a été acquis, SspiGetAsyncCallStatus retourne SEC_E_OK. Sinon, il peut retourner SEC_I_ASYNC_CALL_PENDING si l’appel est toujours en cours, ou l’un des codes d’erreur irrécupérables suivants dans le tableau ci-dessous.

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

Remarques

La fonction SspiAcquireCredentialsHandleAsyncW 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 retourner le handle à des informations d’identification préexistantes ou des informations d’identification nouvellement créées et le retourner. Ce handle peut être utilisé dans les appels suivants aux fonctions SspiAcceptSecurityContextAsync et SspiInitializeSecurityContextAsync .

En général, SspiAcquireCredentialsHandleAsyncW ne fournit pas les informations d’identification des autres utilisateurs connectés au même ordinateur. Toutefois, un appelant disposant d’un privilège SE_TCB_NAME 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 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 à partir du pool.

Une fois que 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 SspiFreeCredentialsHandleAsync .

Configuration requise


Client minimal pris en charge	Windows 10, version 1607 [pilotes en mode noyau uniquement]
Serveur minimal pris en charge	Windows Server 2016 [pilotes en mode noyau uniquement]
En-tête	sspi.h

Voir aussi

AcquireCredentialsHandle

SspiAcceptSecurityContextAsync

SspiFreeCredentialsHandleAsync

SspiInitializeSecurityContextAsync

Fonctions SSPI

Partager via