Función AddAuditAccessObjectAce (securitybaseapi.h)

Artículo
08/25/2023

La función AddAuditAccessObjectAce agrega una entrada de control de acceso (ACE) de auditoría del sistema al final de una lista de control de acceso del sistema (SACL). La nueva ACE puede auditar el acceso a un objeto o a un conjunto de propiedades o una propiedad en un objeto . También puede usar AddAuditAccessObjectAce para agregar una ACE que solo puede heredar un tipo especificado de objeto secundario.

Sintaxis

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
);

Parámetros

[in, out] pAcl

Puntero a una SACL. La función AddAuditAccessObjectAce agrega una ACE de auditoría del sistema al final de esta SACL. La ACE tiene la forma de una estructura SYSTEM_AUDIT_OBJECT_ACE .

[in] dwAceRevision

Especifica el nivel de revisión de la SACL que se va a modificar. Este valor debe ser ACL_REVISION_DS. Si el nivel de revisión de SACL es inferior a ACL_REVISION_DS, la función la cambia a ACL_REVISION_DS.

[in] AceFlags

Conjunto de marcas de bits que controlan la herencia ace y el tipo de intentos de acceso que se van a auditar. La función establece estas marcas en el miembro AceFlags de la estructura ACE_HEADER de la nueva ACE. Este parámetro puede ser una combinación de los valores siguientes.

Value	Significado
CONTAINER_INHERIT_ACE	Los objetos contenedores heredan la ACE.
FAILED_ACCESS_ACE_FLAG	Si establece esta marca o especifica TRUE para el parámetro bAuditFailure , los intentos erróneos de usar los derechos de acceso especificados hacen que el sistema genere un registro de auditoría en el registro de eventos de seguridad.
INHERIT_ONLY_ACE	La ACE no se aplica al objeto al que se asigna la lista de control de acceso (ACL), pero los objetos secundarios pueden heredarla.
INHERITED_ACE	Indica una ACE heredada. Esta marca permite que las operaciones que cambien la seguridad en un árbol de objetos modifiquen las ACE heredadas, al tiempo que no cambian los ACE que se aplicaron directamente al objeto.
NO_PROPAGATE_INHERIT_ACE	Los bits de OBJECT_INHERIT_ACE y CONTAINER_INHERIT_ACE no se propagan a una ACE heredada.
OBJECT_INHERIT_ACE	Los objetos que no son de contenedor heredan la ACE.
SUCCESSFUL_ACCESS_ACE_FLAG	Si establece esta marca o especifica TRUE para el parámetro bAuditSuccess, los usos correctos de los derechos de acceso especificados hacen que el sistema genere un registro de auditoría en el registro de eventos de seguridad.

[in] AccessMask

Un ACCESS_MASK que especifica los derechos de acceso que audita la nueva ACE para el identificador de seguridad (SID) especificado.

[in, optional] ObjectTypeGuid

Puntero a una estructura GUID que identifica el tipo de objeto, conjunto de propiedades o propiedad protegido por la nueva ACE. Si este parámetro es NULL, la nueva ACE protege el objeto al que se asigna la ACL.

[in, optional] InheritedObjectTypeGuid

Puntero a una estructura GUID que identifica el tipo de objeto que puede heredar la nueva ACE. Si este parámetro no es NULL, solo el tipo de objeto especificado puede heredar la ACE. Si es NULL, cualquier tipo de objeto secundario puede heredar la ACE. En cualquier caso, la herencia también se controla mediante el valor del parámetro AceFlags , así como por cualquier protección contra la herencia colocada en los objetos secundarios.

[in] pSid

Puntero a un SID que identifica al usuario, grupo o sesión de inicio de sesión para el que la nueva ACE audita el acceso.

[in] bAuditSuccess

Especifica si los usos correctos de los derechos de acceso especificados hacen que el sistema genere un registro de auditoría en el registro de eventos de seguridad. Si esta marca es TRUE o si el parámetro AceFlags especifica la marca SUCCESSFUL_ACCESS_ACE_FLAG, el sistema registra los intentos de acceso correctos; de lo contrario, no lo hace.

[in] bAuditFailure

Especifica si los intentos erróneos de usar los derechos de acceso especificados hacen que el sistema genere un registro de auditoría en el registro de eventos de seguridad. Si esta marca es TRUE o si el parámetro AceFlags especifica la marca FAILED_ACCESS_ACE_FLAG, el sistema registra los intentos de acceso erróneos; de lo contrario, no lo hace.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError. A continuación se muestran los posibles valores de error.

Código devuelto	Descripción
ERROR_ALLOTTED_SPACE_EXCEEDED	La nueva ACE no encaja en la ACL. Se requiere un búfer de ACL mayor.
ERROR_INVALID_ACL	La ACL especificada no tiene el formato correcto.
ERROR_INVALID_FLAGS	El parámetro AceFlags no es válido.
ERROR_INVALID_SID	El SID especificado no es estructuralmente válido.
ERROR_REVISION_MISMATCH	La revisión especificada no se conoce o es incompatible con la de la ACL.
ERROR_SUCCESS	La ACE se agregó correctamente.

Comentarios

Si ObjectTypeGuid y InheritedObjectTypeGuid son NULL, use la función AddAuditAccessAceEx en lugar de AddAuditAccessObjectAce. Esto se sugiere porque un SYSTEM_AUDIT_ACE es más pequeño y más eficaz que un SYSTEM_AUDIT_OBJECT_ACE.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll