Função GetSecurityInfo (aclapi.h)

Artigo
08/22/2023

A função GetSecurityInfo recupera uma cópia do descritor de segurança para um objeto especificado por um identificador.

Sintaxe

DWORD GetSecurityInfo(
  [in]            HANDLE               handle,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parâmetros

[in] handle

Um identificador para o objeto do qual recuperar informações de segurança.

[in] ObjectType

SE_OBJECT_TYPE valor de enumeração que indica o tipo de objeto.

[in] SecurityInfo

Um conjunto de sinalizadores de bits que indicam o tipo de informações de segurança a serem recuperadas. Esse parâmetro pode ser uma combinação dos sinalizadores de bits SECURITY_INFORMATION .

[out, optional] ppsidOwner

Um ponteiro para uma variável que recebe um ponteiro para o SID proprietário no descritor de segurança retornado em ppSecurityDescriptor. O ponteiro retornado será válido somente se você definir o sinalizador OWNER_SECURITY_INFORMATION. Esse parâmetro poderá ser NULL se você não precisar do SID proprietário.

[out, optional] ppsidGroup

Um ponteiro para uma variável que recebe um ponteiro para o SID do grupo primário no descritor de segurança retornado. O ponteiro retornado será válido somente se você definir o sinalizador GROUP_SECURITY_INFORMATION. Esse parâmetro poderá ser NULL se você não precisar do SID do grupo.

[out, optional] ppDacl

Um ponteiro para uma variável que recebe um ponteiro para a DACL no descritor de segurança retornado. O ponteiro retornado será válido somente se você definir o sinalizador DACL_SECURITY_INFORMATION. Esse parâmetro poderá ser NULL se você não precisar da DACL.

[out, optional] ppSacl

Um ponteiro para uma variável que recebe um ponteiro para o SACL no descritor de segurança retornado. O ponteiro retornado será válido somente se você definir o sinalizador SACL_SECURITY_INFORMATION. Esse parâmetro poderá ser NULL se você não precisar do SACL.

[out, optional] ppSecurityDescriptor

Um ponteiro para uma variável que recebe um ponteiro para o descritor de segurança do objeto. Quando terminar de usar o ponteiro, libere o buffer retornado chamando a função LocalFree .

Esse parâmetro será necessário se qualquer um dos parâmetros ppsidOwner, ppsidGroup, ppDacl ou ppSacl não for NULL.

Retornar valor

Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um código de erro diferente de zero definido em WinError.h.

Comentários

Se os parâmetros ppsidOwner, ppsidGroup, ppDacl e ppSacl não forem NULL e o parâmetro SecurityInfo especificar que eles serão recuperados do objeto, esses parâmetros apontarão para os parâmetros correspondentes no descritor de segurança retornado em ppSecurityDescriptor.

Para ler o proprietário, o grupo ou a DACL do descritor de segurança do objeto, o processo de chamada deve ter sido concedido READ_CONTROL acesso quando o identificador foi aberto. Para obter READ_CONTROL acesso, o chamador deve ser o proprietário do objeto ou a DACL do objeto deve conceder o acesso.

Para ler o SACL do descritor de segurança, o processo de chamada deve ter sido concedido ACCESS_SYSTEM_SECURITY acesso quando o identificador foi aberto. A maneira adequada de obter esse acesso é habilitar o privilégio SE_SECURITY_NAME no token atual do chamador, abrir o identificador para acesso ACCESS_SYSTEM_SECURITY e, em seguida, desabilitar o privilégio. Para obter informações sobre as implicações de segurança da habilitação de privilégios, consulte Executando com privilégios especiais.

Você pode usar a função GetSecurityInfo com os seguintes tipos de objetos:

Arquivos ou diretórios locais ou remotos em um sistema de arquivos NTFS
Pipes nomeados
Impressoras locais ou remotas
Serviços locais ou remotos do Windows
Compartilhamentos de rede
Chaves do Registro
Semáforos, eventos, mutexes e temporizadores de espera
Processos, threads, trabalhos e objetos de mapeamento de arquivos
Estações de janela de serviço interativa e áreas de trabalho
Objetos de serviço de diretório

Essa função não lida com condições de corrida. Se o thread chamar essa função no momento aproximado em que outro thread alterar o descritor de segurança do objeto, essa função poderá falhar.

Exemplos

Para obter um exemplo que usa essa função, consulte Localizando o proprietário de um objeto de arquivo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	aclapi.h
Biblioteca	Advapi32.lib
DLL	Advapi32.dll