Função AccessCheck (securitybaseapi.h)

Artigo
08/25/2023

A função AccessCheck determina se um descritor de segurança concede um conjunto especificado de direitos de acesso ao cliente identificado por um token de acesso. Normalmente, os aplicativos de servidor usam essa função para marcar acesso a um objeto privado.

Sintaxe

BOOL AccessCheck(
  [in]            PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]            HANDLE               ClientToken,
  [in]            DWORD                DesiredAccess,
  [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] 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] 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

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 AccessCheck 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. Se o acesso for concedido, a máscara de acesso solicitada se tornará a máscara de acesso concedida do objeto.

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

A função AccessCheck falhará com ERROR_INVALID_SECURITY_DESCR se o descritor de segurança não contiver SIDs de proprietário e grupo.

A função AccessCheck não gera uma auditoria. Se o aplicativo exigir auditorias para verificações de acesso, use funções como AccessCheckAndAuditAlarm, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm ou AccessCheckByTypeResultListAndAuditAlarmByHandle, em vez de AccessCheck.

Exemplos

Para obter um exemplo que usa essa função, consulte Verificando o acesso do cliente com ACLs.

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