Função AddAuditAccessObjectAce (securitybaseapi.h)

Artigo
03/01/2024

A função AddAuditAccessObjectAce adiciona uma ACE ( entrada de controle de acesso ) de auditoria do sistema ao final de uma SACL (lista de controle de acesso do sistema ). A nova ACE pode auditar o acesso a um objeto ou a um conjunto de propriedades ou propriedade em um objeto . Você também pode usar AddAuditAccessObjectAce para adicionar uma ACE que somente um tipo especificado de objeto filho pode herdar.

Sintaxe

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

Um ponteiro para uma SACL. A função AddAuditAccessObjectAce adiciona uma ACE de auditoria do sistema ao final dessa SACL. A ACE está na forma de uma estrutura SYSTEM_AUDIT_OBJECT_ACE .

[in] dwAceRevision

Especifica o nível de revisão da SACL que está sendo modificada. Esse valor deve ser ACL_REVISION_DS. Se o nível de revisão da SACL for menor que ACL_REVISION_DS, a função o alterará para ACL_REVISION_DS.

[in] AceFlags

Um conjunto de sinalizadores de bits que controlam a herança ace e o tipo de acesso tenta auditar. A função define esses sinalizadores no membro AceFlags da estrutura ACE_HEADER do novo ACE. Esse parâmetro pode ser uma combinação dos seguintes valores.

Valor	Significado
CONTAINER_INHERIT_ACE	A ACE é herdada por objetos de contêiner.
FAILED_ACCESS_ACE_FLAG	Se você definir esse sinalizador ou especificar TRUE para o parâmetro bAuditFailure , as tentativas com falha de usar os direitos de acesso especificados farão com que o sistema gere um registro de auditoria no log de eventos de segurança.
INHERIT_ONLY_ACE	A ACE não se aplica ao objeto ao qual a ACL ( lista de controle de acesso ) é atribuída, mas pode ser herdada por objetos filho.
INHERITED_ACE	Indica uma ACE herdada. Esse sinalizador permite que operações que alterem a segurança em uma árvore de objetos modifiquem ACEs herdadas, sem alterar ACEs que foram aplicadas diretamente ao objeto.
NO_PROPAGATE_INHERIT_ACE	Os bits OBJECT_INHERIT_ACE e CONTAINER_INHERIT_ACE não são propagados para uma ACE herdada.
OBJECT_INHERIT_ACE	O ACE é herdado por objetos não pertencentes a contêineres.
SUCCESSFUL_ACCESS_ACE_FLAG	Se você definir esse sinalizador ou especificar TRUE para o parâmetro bAuditSuccess , os usos bem-sucedidos dos direitos de acesso especificados farão com que o sistema gere um registro de auditoria no log de eventos de segurança.

[in] AccessMask

Um ACCESS_MASK que especifica os direitos de acesso que o novo ACE audita para o SID ( identificador de segurança ) especificado.

[in, optional] ObjectTypeGuid

Um ponteiro para uma estrutura GUID que identifica o tipo de objeto, conjunto de propriedades ou propriedade protegido pelo novo ACE. Se esse parâmetro for NULL, o novo ACE protegerá o objeto ao qual a ACL é atribuída.

[in, optional] InheritedObjectTypeGuid

Um ponteiro para uma estrutura GUID que identifica o tipo de objeto que pode herdar o novo ACE. Se esse parâmetro não for NULL, somente o tipo de objeto especificado poderá herdar o ACE. Se FOR NULL, qualquer tipo de objeto filho poderá herdar o ACE. Em ambos os casos, a herança também é controlada pelo valor do parâmetro AceFlags , bem como por qualquer proteção contra herança colocada nos objetos filho.

[in] pSid

Um ponteiro para um SID que identifica o usuário, o grupo ou a sessão de logon para o qual o novo ACE audita o acesso.

[in] bAuditSuccess

Especifica se os usos bem-sucedidos dos direitos de acesso especificados fazem com que o sistema gere um registro de auditoria no log de eventos de segurança. Se esse sinalizador for TRUE ou se o parâmetro AceFlags especificar o sinalizador SUCCESSFUL_ACCESS_ACE_FLAG, o sistema registrará tentativas de acesso bem-sucedidas; caso contrário, não.

[in] bAuditFailure

Especifica se as tentativas com falha de usar os direitos de acesso especificados fazem com que o sistema gere um registro de auditoria no log de eventos de segurança. Se esse sinalizador for TRUE ou se o parâmetro AceFlags especificar o sinalizador FAILED_ACCESS_ACE_FLAG, o sistema registrará tentativas de acesso com falha; caso contrário, não.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. Veja a seguir os possíveis valores de erro.

Código de retorno	Descrição
ERROR_ALLOTTED_SPACE_EXCEEDED	A nova ACE não se encaixa na ACL. Um buffer de ACL maior é necessário.
ERROR_INVALID_ACL	A ACL especificada não está formada corretamente.
ERROR_INVALID_FLAGS	O parâmetro AceFlags não é válido.
ERROR_INVALID_SID	O SID especificado não é estruturalmente válido.
ERROR_REVISION_MISMATCH	A revisão especificada não é conhecida ou é incompatível com a da ACL.
ERROR_SUCCESS	O ACE foi adicionado com êxito.

Comentários

Se ObjectTypeGuid e InheritedObjectTypeGuid forem NULL, use a função AddAuditAccessAceEx em vez de AddAuditAccessObjectAce. Isso é sugerido porque uma SYSTEM_AUDIT_ACE é menor e mais eficiente do que uma SYSTEM_AUDIT_OBJECT_ACE.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll