Fonction AccessCheck (securitybaseapi.h)

Article
08/25/2023

La fonction AccessCheck détermine si un descripteur de sécurité accorde un ensemble spécifié de droits d’accès au client identifié par un jeton d’accès. En règle générale, les applications serveur utilisent cette fonction pour case activée l’accès à un objet privé.

Syntaxe

BOOL AccessCheck(
  [in]            PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]            HANDLE               ClientToken,
  [in]            DWORD                DesiredAccess,
  [in]            PGENERIC_MAPPING     GenericMapping,
  [out, optional] PPRIVILEGE_SET       PrivilegeSet,
  [in, out]       LPDWORD              PrivilegeSetLength,
  [out]           LPDWORD              GrantedAccess,
  [out]           LPBOOL               AccessStatus
);

Paramètres

[in] pSecurityDescriptor

Pointeur vers une structure SECURITY_DESCRIPTOR sur laquelle l’accès est vérifié.

[in] ClientToken

Handle d’un jeton d’emprunt d’identité qui représente le client qui tente d’obtenir l’accès. Le handle doit avoir TOKEN_QUERY accès au jeton ; sinon, la fonction échoue avec ERROR_ACCESS_DENIED.

[in] DesiredAccess

Masque d’accès qui spécifie les droits d’accès à case activée. Ce masque doit avoir été mappé par la fonction MapGenericMask pour ne contenir aucun droit d’accès générique.

Si ce paramètre est MAXIMUM_ALLOWED, la fonction définit le masque d’accès GrantedAccess pour indiquer les droits d’accès maximum autorisés par le descripteur de sécurité au client.

[in] GenericMapping

Pointeur vers la structure GENERIC_MAPPING associée à l’objet pour lequel l’accès est vérifié.

[out, optional] PrivilegeSet

Pointeur vers une structure de PRIVILEGE_SET qui reçoit les privilèges utilisés pour effectuer la validation de l’accès. Si aucun privilège n’a été utilisé, la fonction définit le membre PrivilegeCount sur zéro.

[in, out] PrivilegeSetLength

Spécifie la taille, en octets, de la mémoire tampon pointée vers le paramètre PrivilegeSet .

[out] GrantedAccess

Pointeur vers un masque d’accès qui reçoit les droits d’accès accordés. Si AccessStatus a la valeur FALSE, la fonction définit le masque d’accès sur zéro. Si la fonction échoue, elle ne définit pas le masque d’accès.

[out] AccessStatus

Pointeur vers une variable qui reçoit les résultats du case activée d’accès. Si le descripteur de sécurité autorise les droits d’accès demandés au client identifié par le jeton d’accès, AccessStatus a la valeur TRUE. Sinon, AccessStatus a la valeur FALSE et vous pouvez appeler GetLastError pour obtenir des informations d’erreur étendues.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour plus d’informations, consultez Vue d’ensemble du fonctionnement d’AccessCheck .

La fonction AccessCheck compare le descripteur de sécurité spécifié avec le jeton d’accès spécifié et indique, dans le paramètre AccessStatus , si l’accès est accordé ou refusé. Si l’accès est accordé, le masque d’accès demandé devient le masque d’accès accordé à l’objet.

Si la liste DACL du descripteur de sécurité est NULL, le paramètre AccessStatus retourne TRUE, ce qui indique que le client dispose de l’accès demandé.

La fonction AccessCheck échoue avec ERROR_INVALID_SECURITY_DESCR si le descripteur de sécurité ne contient pas de SID de propriétaire et de groupe.

La fonction AccessCheck ne génère pas d’audit. Si votre application nécessite des audits pour les vérifications d’accès, utilisez des fonctions telles que AccessCheckAndAuditAlarm, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm ou AccessCheckByTypeResultListAndAuditAlarmByHandle, au lieu d’AccessCheck.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Vérification de l’accès client avec des listes de contrôle d’accès.

Configuration requise

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]
Plateforme cible	Windows
En-tête	securitybaseapi.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll