AddAuditAccessObjectAce, fonction (securitybaseapi.h)

Article
08/25/2023

La fonction AddAuditAccessObjectAce ajoute une entrée de contrôle d’accès d’audit système (ACE) à la fin d’une liste de contrôle d’accès système (SACL). Le nouvel ACE peut auditer l’accès à un objet, à un jeu de propriétés ou à une propriété sur un objet. Vous pouvez également utiliser AddAuditAccessObjectAce pour ajouter un ACE que seul un type spécifié d’objet enfant peut hériter.

Syntaxe

BOOL AddAuditAccessObjectAce(
  [in, out]      PACL  pAcl,
  [in]           DWORD dwAceRevision,
  [in]           DWORD AceFlags,
  [in]           DWORD AccessMask,
  [in, optional] GUID  *ObjectTypeGuid,
  [in, optional] GUID  *InheritedObjectTypeGuid,
  [in]           PSID  pSid,
  [in]           BOOL  bAuditSuccess,
  [in]           BOOL  bAuditFailure
);

Paramètres

[in, out] pAcl

Pointeur vers une liste de contrôle d’accès partagé. La fonction AddAuditAccessObjectAce ajoute un ACE d’audit système à la fin de cette LISTE SACL. L’ACE se présente sous la forme d’une structure SYSTEM_AUDIT_OBJECT_ACE .

[in] dwAceRevision

Spécifie le niveau de révision de la liste de contrôle d’accès partagé en cours de modification. Cette valeur doit être ACL_REVISION_DS. Si le niveau de révision de la liste de contrôle d’accès partagé est inférieur à ACL_REVISION_DS, la fonction le remplace par ACL_REVISION_DS.

[in] AceFlags

Ensemble d’indicateurs de bits qui contrôlent l’héritage ACE et le type de tentatives d’audit d’accès. La fonction définit ces indicateurs dans le membre AceFlags de la structure ACE_HEADER du nouvel ACE. Ce paramètre peut être une combinaison des valeurs suivantes.

Valeur	Signification
CONTAINER_INHERIT_ACE	L’ACE est hérité par les objets conteneur.
FAILED_ACCESS_ACE_FLAG	Si vous définissez cet indicateur ou spécifiez TRUE pour le paramètre bAuditFailure , l’échec des tentatives d’utilisation des droits d’accès spécifiés entraîne la génération d’un enregistrement d’audit dans le journal des événements de sécurité.
INHERIT_ONLY_ACE	L’ACE ne s’applique pas à l’objet auquel la liste de contrôle d’accès (ACL) est affectée, mais elle peut être héritée par des objets enfants.
INHERITED_ACE	Indique un ACE hérité. Cet indicateur permet aux opérations qui modifient la sécurité d’une arborescence d’objets de modifier les AFC hérités, sans modifier les AFC qui ont été directement appliqués à l’objet.
NO_PROPAGATE_INHERIT_ACE	Les bits OBJECT_INHERIT_ACE et CONTAINER_INHERIT_ACE ne sont pas propagés vers un ACE hérité.
OBJECT_INHERIT_ACE	L’ACE est hérité par les objets non-contenus.
SUCCESSFUL_ACCESS_ACE_FLAG	Si vous définissez cet indicateur ou spécifiez TRUE pour le paramètre bAuditSuccess, les utilisations réussies des droits d’accès spécifiés entraînent le système à générer un enregistrement d’audit dans le journal des événements de sécurité.

[in] AccessMask

Un ACCESS_MASK qui spécifie les droits d’accès audités par le nouvel ACE pour l’identificateur de sécurité (SID) spécifié.

[in, optional] ObjectTypeGuid

Pointeur vers une structure GUID qui identifie le type d’objet, de jeu de propriétés ou de propriété protégé par le nouvel ACE. Si ce paramètre a la valeur NULL, la nouvelle ACE protège l’objet auquel l’ACL est affectée.

[in, optional] InheritedObjectTypeGuid

Pointeur vers une structure GUID qui identifie le type d’objet qui peut hériter du nouvel ACE. Si ce paramètre n’est pas NULL, seul le type d’objet spécifié peut hériter de l’ACE. Si la valeur est NULL, n’importe quel type d’objet enfant peut hériter de l’ACE. Dans les deux cas, l’héritage est également contrôlé par la valeur du paramètre AceFlags , ainsi que par toute protection contre l’héritage placé sur les objets enfants.

[in] pSid

Pointeur vers un SID qui identifie l’utilisateur, le groupe ou la session d’ouverture de session auquel les nouveaux audits ACE accèdent.

[in] bAuditSuccess

Spécifie si l’utilisation réussie des droits d’accès spécifiés entraîne la génération par le système d’un enregistrement d’audit dans le journal des événements de sécurité. Si cet indicateur a la valeur TRUE ou si le paramètre AceFlags spécifie l’indicateur SUCCESSFUL_ACCESS_ACE_FLAG, le système enregistre les tentatives d’accès réussies ; sinon, ce n’est pas le cas.

[in] bAuditFailure

Spécifie si l’échec des tentatives d’utilisation des droits d’accès spécifiés entraîne la génération d’un enregistrement d’audit dans le journal des événements de sécurité. Si cet indicateur a la valeur TRUE ou si le paramètre AceFlags spécifie l’indicateur FAILED_ACCESS_ACE_FLAG, le système enregistre les tentatives d’accès ayant échoué ; sinon, ce n’est pas le cas.

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. Voici les valeurs d’erreur possibles.

Code de retour	Description
ERROR_ALLOTTED_SPACE_EXCEEDED	La nouvelle ACE ne s’intègre pas dans la liste de contrôle d’accès. Une mémoire tampon ACL plus grande est requise.
ERROR_INVALID_ACL	La liste de contrôle d’accès spécifiée n’est pas correctement formée.
ERROR_INVALID_FLAGS	Le paramètre AceFlags n’est pas valide.
ERROR_INVALID_SID	Le SID spécifié n’est pas structurellement valide.
ERROR_REVISION_MISMATCH	La révision spécifiée n’est pas connue ou est incompatible avec celle de la liste de contrôle d’accès.
ERROR_SUCCESS	L’ACE a été ajouté avec succès.

Remarques

Si ObjectTypeGuid et InheritedObjectTypeGuid ont la valeur NULL, utilisez la fonction AddAuditAccessAceEx plutôt que AddAuditAccessObjectAce. Cela est suggéré parce qu’un SYSTEM_AUDIT_ACE est plus petit et plus efficace qu’un SYSTEM_AUDIT_OBJECT_ACE.

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