Funzione AddAuditAccessObjectAce (securitybaseapi.h)

Articolo
03/05/2024

La funzione AddAuditAccessObjectAce aggiunge una voce di controllo degli accessi di sistema (ACE) alla fine di un elenco di controllo di accesso del sistema (SACL). Il nuovo ACE può controllare l'accesso a un oggetto o a un set di proprietà o a una proprietà in un oggetto. È anche possibile usare AddAuditAccessObjectAce per aggiungere un ACE che solo un tipo specificato di oggetto figlio può ereditare.

Sintassi

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

Parametri

[in, out] pAcl

Puntatore a un SACL. La funzione AddAuditAccessObjectAce aggiunge un ACE di controllo di sistema alla fine di questo SACL. L'ACE è sotto forma di una struttura SYSTEM_AUDIT_OBJECT_ACE .

[in] dwAceRevision

Specifica il livello di revisione dell'oggetto SACL da modificare. Questo valore deve essere ACL_REVISION_DS. Se il livello di revisione di SACL è inferiore a ACL_REVISION_DS, la funzione lo modifica in ACL_REVISION_DS.

[in] AceFlags

Set di flag di bit che controllano l'ereditarietà ACE e il tipo di tentativi di accesso di controllare. La funzione imposta questi flag nel membro AceFlags della struttura ACE_HEADER del nuovo ACE. Questo parametro può essere una combinazione dei valori seguenti.

Valore	Significato
CONTAINER_INHERIT_ACE	L'ACE viene ereditato dagli oggetti contenitore.
FAILED_ACCESS_ACE_FLAG	Se si imposta questo flag o si specifica TRUE per il parametro bAuditFailure , i tentativi di utilizzo dei diritti di accesso specificati causano la generazione di un record di controllo nel registro eventi di sicurezza.
INHERIT_ONLY_ACE	L'ACE non si applica all'oggetto a cui viene assegnato l'elenco di controllo di accesso , ma può essere ereditato dagli oggetti figlio.
INHERITED_ACE	Indica un ACE ereditato. Questo flag consente alle operazioni che modificano la sicurezza in un albero di oggetti per modificare gli ACL ereditati, senza modificare gli ACL applicati direttamente all'oggetto.
NO_PROPAGATE_INHERIT_ACE	I bit di OBJECT_INHERIT_ACE e CONTAINER_INHERIT_ACE non vengono propagati a un ACE ereditato.
OBJECT_INHERIT_ACE	L'ACE viene ereditato da oggetti noncontainer.
SUCCESSFUL_ACCESS_ACE_FLAG	Se si imposta questo flag o si specifica TRUE per il parametro bAuditSuccess , l'uso dei diritti di accesso specificati causa la generazione di un record di controllo nel registro eventi di sicurezza.

[in] AccessMask

ACCESS_MASK che specifica i diritti di accesso controllati dal nuovo ACE per l'identificatore di sicurezza specificato.

[in, optional] ObjectTypeGuid

Puntatore a una struttura GUID che identifica il tipo di oggetto, il set di proprietà o la proprietà protetta dal nuovo ACE. Se questo parametro è NULL, il nuovo ACE protegge l'oggetto a cui viene assegnato l'ACL.

[in, optional] InheritedObjectTypeGuid

Puntatore a una struttura GUID che identifica il tipo di oggetto che può ereditare il nuovo ACE. Se questo parametro non è NULL, solo il tipo di oggetto specificato può ereditare l'ACE. Se NULL, qualsiasi tipo di oggetto figlio può ereditare l'ACE. In entrambi i casi, l'ereditarietà è controllata anche dal valore del parametro AceFlags , nonché da qualsiasi protezione contro l'ereditarietà inserita negli oggetti figlio.

[in] pSid

Puntatore a un SID che identifica la sessione di accesso , gruppo o utente per cui il nuovo controllo ACE accede.

[in] bAuditSuccess

Specifica se l'uso corretto dei diritti di accesso specificati causa la generazione di un record di controllo nel registro eventi di sicurezza. Se questo flag è TRUE o se il parametro AceFlags specifica il flag di SUCCESSFUL_ACCESS_ACE_FLAG, il sistema registra tentativi di accesso riusciti; in caso contrario, non lo fa.

[in] bAuditFailure

Specifica se i tentativi non riusciti di usare i diritti di accesso specificati causano la generazione di un record di controllo nel registro eventi di sicurezza. Se questo flag è TRUE o se il parametro AceFlags specifica il flag di FAILED_ACCESS_ACE_FLAG, i record di sistema non sono riusciti a tentare di accesso; in caso contrario, non lo fa.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError. Di seguito sono riportati i valori di errore possibili.

Codice restituito	Descrizione
ERROR_ALLOTTED_SPACE_EXCEEDED	Il nuovo ACE non rientra nell'ACL. È necessario un buffer ACL più grande.
ERROR_INVALID_ACL	L'elenco di controllo di accesso specificato non è formato correttamente.
ERROR_INVALID_FLAGS	Il parametro AceFlags non è valido.
ERROR_INVALID_SID	Il SID specificato non è valido in modo strutturale.
ERROR_REVISION_MISMATCH	La revisione specificata non è nota o non è compatibile con quella dell'ACL.
ERROR_SUCCESS	L'ACE è stato aggiunto correttamente.

Commenti

Se sia ObjectTypeGuid che InheritedObjectTypeGuid sono NULL, usare la funzione AddAuditAccessAceEx anziché AddAuditAccessObjectAce. Questo è suggerito perché un SYSTEM_AUDIT_ACE è più piccolo e più efficiente di un SYSTEM_AUDIT_OBJECT_ACE.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll