Função AccessCheckByTypeResultListAndAuditAlarmW (securitybaseapi.h)
A função AccessCheckByTypeResultListAndAuditAlarm determina se um descritor de segurança concede um conjunto especificado de direitos de acesso ao cliente que está sendo representado pelo thread de chamada. A função pode marcar acesso a uma hierarquia de objetos, como um objeto, seus conjuntos de propriedades e propriedades. A função relata os direitos de acesso concedidos ou negados a cada tipo de objeto na hierarquia. Se o descritor de segurança tiver uma SACL ( lista de controle de acesso do sistema ) com ACEs (entradas de controle de acesso ) que se aplicam ao cliente, a função gerará todas as mensagens de auditoria necessárias no log de eventos de segurança. Atualmente, não há suporte para alarmes.
Sintaxe
BOOL AccessCheckByTypeResultListAndAuditAlarmW(
[in] LPCWSTR SubsystemName,
[in] LPVOID HandleId,
[in] LPCWSTR ObjectTypeName,
[in, optional] LPCWSTR ObjectName,
[in] PSECURITY_DESCRIPTOR SecurityDescriptor,
[in, optional] PSID PrincipalSelfSid,
[in] DWORD DesiredAccess,
[in] AUDIT_EVENT_TYPE AuditType,
[in] DWORD Flags,
[in, out, optional] POBJECT_TYPE_LIST ObjectTypeList,
[in] DWORD ObjectTypeListLength,
[in] PGENERIC_MAPPING GenericMapping,
[in] BOOL ObjectCreation,
LPDWORD GrantedAccessList,
[out] LPDWORD AccessStatusList,
[out] LPBOOL pfGenerateOnClose
);
Parâmetros
[in] SubsystemName
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do subsistema que chama a função. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.
[in] HandleId
Um ponteiro para um valor exclusivo que representa o identificador do cliente para o objeto . Se o acesso for negado, o sistema ignorará esse valor.
[in] ObjectTypeName
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o tipo de objeto que está sendo criado ou acessado. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.
[in, optional] ObjectName
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do objeto que está sendo criado ou acessado. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.
[in] SecurityDescriptor
Um ponteiro para uma estrutura de SECURITY_DESCRIPTOR na qual o acesso é verificado.
[in, optional] PrincipalSelfSid
Um ponteiro para um SID ( identificador de segurança ). Se o descritor de segurança estiver associado a um objeto que representa uma entidade de segurança (por exemplo, um objeto de usuário), o parâmetro PrincipalSelfSid deverá ser o SID do objeto. Ao avaliar o acesso, esse SID substitui logicamente o SID em qualquer ACE que contenha o SID de PRINCIPAL_SELF conhecido (S-1-5-10). Para obter informações sobre SIDs conhecidos, consulte SIDs conhecidos.
Defina esse parâmetro como NULL se o objeto protegido não representar uma entidade de segurança.
[in] DesiredAccess
Uma máscara de acesso que especifica os direitos de acesso para marcar. Essa máscara deve ter sido mapeada pela função MapGenericMask para que ela não contenha direitos de acesso genéricos.
Se esse parâmetro for MAXIMUM_ALLOWED, a função definirá a máscara de acesso em GrantedAccess para indicar os direitos máximos de acesso que o descritor de segurança permite ao cliente.
[in] AuditType
O tipo de auditoria a ser gerado. Esse pode ser um dos valores do tipo de enumeração AUDIT_EVENT_TYPE .
[in] Flags
Um sinalizador que controla o comportamento da função se o processo de chamada não tiver o privilégio SE_AUDIT_NAME habilitado. Se o sinalizador AUDIT_ALLOW_NO_PRIVILEGE estiver definido, a função executará o marcar de acesso sem gerar mensagens de auditoria quando o privilégio não estiver habilitado. Se esse parâmetro for zero, a função falhará se o privilégio não estiver habilitado.
[in, out, optional] ObjectTypeList
Um ponteiro para uma matriz de estruturas de OBJECT_TYPE_LIST que identificam a hierarquia de tipos de objeto para os quais marcar acesso. Cada elemento na matriz especifica um GUID que identifica o tipo de objeto e um valor que indica o nível do tipo de objeto na hierarquia de tipos de objeto. A matriz não deve ter dois elementos com o mesmo GUID.
A matriz deve ter pelo menos um elemento. O primeiro elemento na matriz deve estar no nível zero e identificar o próprio objeto. A matriz pode ter apenas um elemento de nível zero. O segundo elemento é um subobjeto, como um conjunto de propriedades, no nível 1. Seguindo cada entrada de nível 1 estão entradas subordinadas para os subobjetos de nível 2 a 4. Assim, os níveis para os elementos na matriz podem ser {0, 1, 2, 2, 1, 2, 3}. Se a lista de tipos de objeto estiver fora de ordem, AccessCheckByTypeResultListAndAuditAlarm falhará e GetLastError retornará ERROR_INVALID_PARAMETER.
[in] ObjectTypeListLength
O número de elementos na matriz ObjectTypeList .
[in] GenericMapping
Um ponteiro para a estrutura GENERIC_MAPPING associada ao objeto para o qual o acesso está sendo verificado.
[in] ObjectCreation
Um sinalizador que determina se o aplicativo de chamada criará um novo objeto quando o acesso for concedido. Um valor true indica que o aplicativo criará um novo objeto. Um valor false indica que o aplicativo abrirá um objeto existente.
GrantedAccessList
[out] AccessStatusList
Um ponteiro para uma matriz de códigos status para os elementos correspondentes na lista de tipos de objeto. A função define um elemento como zero para indicar êxito ou para um valor diferente de zero para indicar o erro específico durante a marcar de acesso. Se a função falhar, ela não definirá nenhum dos elementos na matriz.
[out] pfGenerateOnClose
Um ponteiro para um sinalizador definido pela rotina de geração de auditoria quando a função retorna. Passe esse sinalizador para a função ObjectCloseAuditAlarm quando o identificador do objeto for fechado.
Retornar valor
Se a função for bem-sucedida, a função retornará diferente de zero.
Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.
Comentários
Para obter mais informações, consulte a visão geral como o AccessCheck funciona .
A função AccessCheckByTypeResultListAndAuditAlarm é uma combinação das funções AccessCheckByTypeResultList e AccessCheckAndAuditAlarm .
A matriz ObjectTypeList não representa necessariamente todo o objeto definido. Em vez disso, ele representa esse subconjunto do objeto para o qual marcar acesso. Por exemplo, para marcar acesso a duas propriedades em um conjunto de propriedades, especifique uma lista de tipos de objeto com quatro elementos: o próprio objeto no nível zero, a propriedade definida no nível 1 e as duas propriedades no nível 2.
A função AccessCheckByTypeResultListAndAuditAlarm avalia ACEs que se aplicam ao próprio objeto e ACEs específicos ao objeto para os tipos de objeto listados na matriz ObjectTypeList . A função ignora ACEs específicos do objeto para tipos de objeto não listados na matriz ObjectTypeList .
Para obter mais informações sobre como uma hierarquia de ACEs controla o acesso a um objeto e seus subobjetos, consulte ACEs para controlar o acesso às propriedades de um objeto.
Para gerar mensagens de auditoria no log de eventos de segurança, o processo de chamada deve ter o privilégio SE_AUDIT_NAME habilitado. O sistema verifica esse privilégio no token primário do processo de chamada, não o token de representação do thread. Se o parâmetro Flags incluir o sinalizador AUDIT_ALLOW_NO_PRIVILEGE, a função executará o marcar de acesso sem gerar mensagens de auditoria quando o privilégio não estiver habilitado.
A função AccessCheckByTypeResultListAndAuditAlarm falhará se o thread de chamada não estiver representando um cliente.
Se o descritor de segurança não contiver SIDs de proprietário e grupo, AccessCheckByTypeResultListAndAuditAlarm falhará com ERROR_INVALID_SECURITY_DESCR.
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 |
Confira também
AUDIT_EVENT_TYPE
AccessCheck
AccessCheckAndAuditAlarm
AccessCheckByType
AccessCheckByTypeResultList
Controle de Acesso cliente/servidor
Funções de Controle de Acesso de cliente/servidor
GENERIC_MAPPING
Como o AccessCheck funciona
MakeAbsoluteSD
MapGenericMask
OBJECT_TYPE_LIST
ObjectCloseAuditAlarm
PRIVILEGE_SET
SECURITY_DESCRIPTOR
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de