Função AccessCheckByTypeResultListAndAuditAlarmByHandleW (securitybaseapi.h)
A função AccessCheckByTypeResultListAndAuditAlarmByHandle determina se um descritor de segurança concede um conjunto especificado de direitos de acesso ao cliente que o thread de chamada está representando. A diferença entre essa função e AccessCheckByTypeResultListAndAuditAlarm é que essa função permite que o thread de chamada execute o marcar de acesso antes de representar o cliente.
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. No momento, não há suporte para alarmes.
Sintaxe
BOOL AccessCheckByTypeResultListAndAuditAlarmByHandleW(
[in] LPCWSTR SubsystemName,
[in] LPVOID HandleId,
[in] HANDLE ClientToken,
[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] ClientToken
Um identificador para um objeto de token que representa o cliente que solicitou a operação. Esse identificador deve ser obtido por meio de uma camada de sessão de comunicação, como um pipe nomeado local, para evitar possíveis violações de política de segurança. O chamador deve ter TOKEN_QUERY acesso para o token especificado.
[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. 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 a 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 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, AccessCheckByTypeResultListAndAuditAlarmByHandle 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 como 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 de como o AccessCheck funciona .
Assim como AccessCheckByTypeResultListAndAuditAlarm, a função AccessCheckByTypeResultListAndAuditAlarmByHandle é uma combinação das funções AccessCheckByTypeResultList e AccessCheckAndAuditAlarm . No entanto, AccessCheckByTypeResultListAndAuditAlarmByHandle também requer um identificador de token de cliente para fornecer informações de segurança sobre o cliente.
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 AccessCheckByTypeResultListAndAuditAlarmByHandle 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 .
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 AccessCheckByTypeResultListAndAuditAlarmByHandle 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, AccessCheckByTypeResultListAndAuditAlarmByHandle 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
AccessCheckByTypeResultListAndAuditAlarmClient/Server Controle de Acesso
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