AuthzAccessCheck, fonction (authz.h)

Article
08/22/2023

La fonction AuthzAccessCheck détermine les bits d’accès qui peuvent être accordés à un client pour un ensemble donné de descripteurs de sécurité. La structure AUTHZ_ACCESS_REPLY retourne un tableau de masques d’accès accordés et de status d’erreur. Si vous le souhaitez, les masques d’accès qui seront toujours accordés peuvent être mis en cache et un handle aux valeurs mises en cache est retourné.

Syntaxe

AUTHZAPI BOOL AuthzAccessCheck(
  [in]            DWORD                              Flags,
  [in]            AUTHZ_CLIENT_CONTEXT_HANDLE        hAuthzClientContext,
  [in]            PAUTHZ_ACCESS_REQUEST              pRequest,
  [in, optional]  AUTHZ_AUDIT_EVENT_HANDLE           hAuditEvent,
  [in]            PSECURITY_DESCRIPTOR               pSecurityDescriptor,
  [in, optional]  PSECURITY_DESCRIPTOR               *OptionalSecurityDescriptorArray,
  [in, optional]  DWORD                              OptionalSecurityDescriptorCount,
  [in, out]       PAUTHZ_ACCESS_REPLY                pReply,
  [out, optional] PAUTHZ_ACCESS_CHECK_RESULTS_HANDLE phAccessCheckResults
);

Paramètres

[in] Flags

Valeur DWORD qui spécifie la façon dont le descripteur de sécurité est copié. Ce paramètre peut prendre les valeurs suivantes.

À compter de Windows 8 et Windows Server 2012, lorsque vous appelez cette fonction sur un handle de contexte distant, les 16 bits supérieurs doivent être zéro.

Valeur	Signification
0	Si phAccessCheckResults n’a pas la valeur NULL, une copie approfondie du descripteur de sécurité est copiée dans le handle référencé par phAccessCheckResults.
AUTHZ_ACCESS_CHECK_NO_DEEP_COPY_SD 1	Aucune copie approfondie du descripteur de sécurité n’est effectuée. L’application appelante doit passer l’adresse d’un handle AUTHZ_ACCESS_CHECK_RESULTS_HANDLE dans phAccessCheckResults. La fonction AuthzAccessCheck définit ce handle sur un descripteur de sécurité qui doit rester valide lors des appels suivants à AuthzCachedAccessCheck.

[in] hAuthzClientContext

Handle d’une structure qui représente le client.

À compter de Windows 8 et Windows Server 2012, le contexte client peut être local ou distant.

[in] pRequest

Pointeur vers une structure de AUTHZ_ACCESS_REQUEST qui spécifie le masque d’accès souhaité, l’identificateur d’auto-sécurité du principal (SID) et la structure de liste de types d’objets, s’il existe.

[in, optional] hAuditEvent

Structure qui contient des informations d’audit spécifiques à l’objet. Lorsque la valeur de ce paramètre n’est pas null, un audit est automatiquement demandé. Les informations d’audit statiques sont lues à partir de la structure resource manager.

À compter de Windows 8 et Windows Server 2012, lorsque vous utilisez cette fonction avec un handle de contexte distant, la valeur du paramètre doit être NULL.

[in] pSecurityDescriptor

Pointeur vers une structure de SECURITY_DESCRIPTOR à utiliser pour les vérifications d’accès. Le SID propriétaire de l’objet est choisi à partir de ce descripteur de sécurité. Une liste de contrôle d’accès discrétionnaire (DACL) NULL dans ce descripteur de sécurité représente une liste DACL NULL pour l’ensemble de l’objet. Vérifiez que le descripteur de sécurité contient des informations OWNER et DACL, ou qu’un message de code d’erreur 87 ou « paramètre non valide » est généré.

Les DACL NULL importantes autorisent tous les types d’accès à tous les utilisateurs ; Par conséquent, n’utilisez pas de DLL NULL. Pour plus d’informations sur la création d’un DACL, consultez Création d’un DACL.

Une liste de contrôle d’accès système (SACL) NULL dans ce descripteur de sécurité est traitée de la même façon qu’une liste de contrôle d’accès système (SACL) vide.

[in, optional] OptionalSecurityDescriptorArray

Tableau de structures SECURITY_DESCRIPTOR . Les listes de contrôle d’accèsNULL (ACL) dans ces descripteurs de sécurité sont traitées comme des listes de contrôle d’accès vides. La liste de contrôle d’accès de l’objet entier est la concaténation logique de toutes les listes de contrôle d’accès.

[in, optional] OptionalSecurityDescriptorCount

Nombre de descripteurs de sécurité non compris le descripteur de sécurité principal.

[in, out] pReply

Pointeur vers une structure AUTHZ_ACCESS_REPLY qui contient les résultats du case activée d’accès. Avant d’appeler la fonction AuthzAccessCheck , une application doit allouer de la mémoire aux membres GrantedAccessMask et SaclEvaluationResults de la structure AUTHZ_ACCESS_REPLY référencée par pReply.

[out, optional] phAccessCheckResults

Pointeur pour retourner un handle aux résultats mis en cache du case activée d’accès. Lorsque cette valeur de paramètre n’est pas null, les résultats de cet accès case activée appel sont mis en cache. Cela entraîne une MAXIMUM_ALLOWED case activée.

À compter de Windows 8 et Windows Server 2012, lorsque vous utilisez cette fonction avec un handle de contexte distant, la valeur du paramètre doit être NULL.

Valeur retournée

Si la fonction réussit, la fonction retourne TRUE.

Si la fonction échoue, elle retourne FALSE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La fonction de rappel AuthzAccessCheckCallback est appelée si la liste DACL de la structure SECURITY_DESCRIPTOR pointée par le paramètre pSecurityDescriptor contient une entrée de contrôle d’accès (ACE) de rappel.

Les variables d’attribut de sécurité doivent être présentes dans le contexte client si elles sont référencées dans une expression conditionnelle. Sinon, le terme d’expression conditionnelle qui les référence sera considéré comme inconnu. Pour plus d’informations, consultez la rubrique Security Descriptor Definition Language for Conditional ACEs .

Pour plus d’informations, consultez Les vues d’ensemble du fonctionnement d’AccessCheck et de la stratégie d’autorisation centralisée .

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	authz.h
Bibliothèque	Authz.lib
DLL	Authz.dll
Composant redistribuable	Windows Server 2003 Administration Tools Pack sur Windows XP