Função AccessCheckByTypeAndAuditAlarmW (securitybaseapi.h)
A função AccessCheckByTypeAndAuditAlarm 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 o acesso do cliente a uma hierarquia de objetos, como um objeto, seus conjuntos de propriedades e propriedades. A função concede ou nega acesso à hierarquia como um todo. 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.
No momento, não há suporte para alarmes.
Sintaxe
BOOL AccessCheckByTypeAndAuditAlarmW(
[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,
[out] LPDWORD GrantedAccess,
[out] LPBOOL AccessStatus,
[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.
Se o objeto protegido não representar uma entidade de segurança, defina esse parâmetro como NULL.
[in] DesiredAccess
Uma máscara de acesso que especifica os direitos de acesso a marcar. Essa máscara deve ter sido mapeada pela função MapGenericMask para não conter direitos de acesso genéricos.
Se esse parâmetro for MAXIMUM_ALLOWED, a função definirá a máscara de acesso 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 de 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 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 as entradas subordinadas para os subobjetos de nível 2 a 4. Portanto, 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, AccessCheckByTypeAndAuditAlarm 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.
[out] GrantedAccess
Um ponteiro para uma máscara de acesso que recebe os direitos de acesso concedidos. Se AccessStatus estiver definido como FALSE, a função definirá a máscara de acesso como zero. Se a função falhar, ela não definirá a máscara de acesso.
[out] AccessStatus
Um ponteiro para uma variável que recebe os resultados da marcar de acesso. Se o descritor de segurança permitir os direitos de acesso solicitados ao cliente, AccessStatus será definido como TRUE. Caso contrário, AccessStatus será definido como FALSE e você poderá chamar GetLastError para obter informações de erro estendidas.
[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 de como o AccessCheck funciona .
Se os parâmetros PrincipalSelfSid e ObjectTypeList forem NULL, o parâmetro AuditType será AuditEventObjectAccess e o parâmetro Flags for zero, AccessCheckByTypeAndAuditAlarm será executado da mesma forma que a função 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 AccessCheckByTypeAndAuditAlarm avalia ACEs que se aplicam ao próprio objeto e ACEs específicos do objeto para os tipos de objeto listados na matriz ObjectTypeList . A função ignora ACEs específicas do objeto para tipos de objeto não listados na matriz ObjectTypeList . Assim, os resultados retornados no parâmetro AccessStatus indicam o acesso permitido ao subconjunto do objeto definido pelo parâmetro ObjectTypeList , não ao objeto inteiro.
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 no 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 AccessCheckByTypeAndAuditAlarm 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, AccessCheckByTypeAndAuditAlarm 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
AccessCheckByTypeResultListAndAuditAlarm
Controle de Acesso cliente/servidor
Funções de Controle de Acesso 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