Função AccessCheckByTypeResultList (securitybaseapi.h)

Artigo
03/13/2024

A função AccessCheckByTypeResultList determina se um descritor de segurança concede um conjunto especificado de direitos de acesso ao cliente identificado por um token de acesso. 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 relata os direitos de acesso concedidos ou negados a cada tipo de objeto na hierarquia. Normalmente, os aplicativos de servidor usam essa função para marcar acesso a um objeto privado.

Sintaxe

BOOL AccessCheckByTypeResultList(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [out]               PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList
);

Parâmetros

[in] pSecurityDescriptor

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 ( entrada de controle de acesso ) que contenha o CONHECIDO PRINCIPAL_SELF SID (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] ClientToken

Um identificador para um token de representação que representa o cliente que está tentando obter acesso. O identificador deve ter TOKEN_QUERY acesso ao token; caso contrário, a função falhará com ERROR_ACCESS_DENIED.

[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 não conter direitos de acesso genéricos.

Se esse parâmetro for MAXIMUM_ALLOWED, a função definirá as máscaras de acesso na matriz GrantedAccess para indicar os direitos máximos de acesso do cliente a cada elemento na lista de tipos de objeto.

[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, AccessCheckByTypeResultList falhará e GetLastError retornará ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

O número de elementos na matriz ObjectTypeList . Esse também é o número de elementos nas matrizes apontadas pelos parâmetros GrantedAccessList e AccessStatusList .

[out] GenericMapping

Um ponteiro para a estrutura GENERIC_MAPPING associada ao objeto para o qual o acesso está sendo verificado.

[out, optional] PrivilegeSet

Um ponteiro para uma estrutura PRIVILEGE_SET que recebe os privilégios usados para executar a validação de acesso. Se nenhum privilégio tiver sido usado, a função definirá o membro PrivilegeCount como zero.

[in, out] PrivilegeSetLength

O tamanho, em bytes, do buffer apontado pelo parâmetro PrivilegeSet .

[out] GrantedAccessList

Um ponteiro para uma matriz de máscaras de acesso. A função define cada máscara de acesso para indicar os direitos de acesso concedidos ao elemento correspondente na lista de tipos de objeto. Se a função falhar, ela não definirá as máscaras de acesso.

[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 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.

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 AccessCheckByTypeResultList compara o descritor de segurança especificado com o token de acesso especificado e indica, no parâmetro AccessStatusList , se o acesso é concedido ou negado para cada um dos elementos na lista de tipos de objeto.

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 AccessCheckByTypeResultList 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íficos do objeto para tipos de objeto não listados na matriz ObjectTypeList . Assim, os resultados retornados para o elemento zero no parâmetro AccessStatusList 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.

Se a DACL ( lista de controle de acesso discricionário ) do descritor de segurança for NULL, a função concederá o acesso solicitado a todos os elementos na lista de tipos de objeto.

Se o descritor de segurança não contiver SIDs de proprietário e grupo, AccessCheckByTypeResultList 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