Função AccessCheckByType (securitybaseapi.h)

Artigo
08/25/2023

A função AccessCheckByType 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 concede ou nega acesso à hierarquia como um todo. Normalmente, os aplicativos de servidor usam essa função para marcar acesso a um objeto privado.

Sintaxe

BOOL AccessCheckByType(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus
);

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 entrada de controle de acesso 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] 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

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á a máscara de acesso GrantedAccess para indicar os direitos máximos de acesso que o descritor de segurança permite ao cliente.

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

Se ObjectTypeList for NULL, AccessCheckByType será o mesmo que a função AccessCheck .

[in] ObjectTypeListLength

Especifica 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. O membro GenericAll da estrutura GENERIC_MAPPING deve conter todos os direitos de acesso que podem ser concedidos pelo gerenciador de recursos, incluindo STANDARD_RIGHTS_ALL e todos os direitos definidos nos membros GenericRead, GenericWrite e GenericExecute .

[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

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

[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 identificado pelo token de acesso, 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.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será 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 AccessCheckByType compara o descritor de segurança especificado com o token de acesso especificado e indica, no parâmetro AccessStatus , se o acesso é concedido ou negado.

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

Se a DACL do descritor de segurança for NULL, o parâmetro AccessStatus retornará TRUE, indicando que o cliente tem o acesso solicitado.

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