Функция GetSecurityInfo (aclapi.h)

Статья
02/23/2024

Функция GetSecurityInfo извлекает копию дескриптора безопасности для объекта, указанного дескриптором.

Синтаксис

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
);

Параметры

[in] handle

Дескриптор объекта , из которого извлекаются сведения о безопасности.

[in] ObjectType

SE_OBJECT_TYPE значение перечисления, указывающее тип объекта.

[in] SecurityInfo

Набор битовых флагов, указывающих тип извлекаемых сведений о безопасности. Этот параметр может быть сочетанием SECURITY_INFORMATION битовых флагов.

[out, optional] ppsidOwner

Указатель на переменную, которая получает указатель на идентификатор безопасности владельца в дескрипторе безопасности, возвращенном в ppSecurityDescriptor. Возвращаемый указатель действителен, только если задан флаг OWNER_SECURITY_INFORMATION. Этот параметр может иметь значение NULL , если идентификатор безопасности владельца не нужен.

[out, optional] ppsidGroup

Указатель на переменную, получающую указатель на идентификатор безопасности основной группы в возвращенном дескрипторе безопасности. Возвращаемый указатель действителен, только если задан флаг GROUP_SECURITY_INFORMATION. Этот параметр может иметь значение NULL , если идентификатор безопасности группы не нужен.

[out, optional] ppDacl

Указатель на переменную, получающую указатель на DACL в возвращенном дескрипторе безопасности. Возвращаемый указатель действителен только в том случае, если задан флаг DACL_SECURITY_INFORMATION. Если список DACL не требуется, этот параметр может иметь значение NULL .

[out, optional] ppSacl

Указатель на переменную, которая получает указатель на saCL в возвращенном дескрипторове безопасности. Возвращаемый указатель действителен только в том случае, если задан флаг SACL_SECURITY_INFORMATION. Этот параметр может иметь значение NULL , если не требуется saCL.

[out, optional] ppSecurityDescriptor

Указатель на переменную, получающую указатель на дескриптор безопасности объекта . Завершив использование указателя, освободите возвращенный буфер, вызвав функцию LocalFree .

Этот параметр является обязательным, если какой-либо из параметров ppsidOwner, ppsidGroup, ppDacl или ppSacl не имеет значения NULL.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение представляет собой код ошибки, отличный от нуля, определенный в WinError.h.

Если параметры ppsidOwner, ppsidGroup, ppDacl и ppSacl не имеют значения NULL, а параметр SecurityInfo указывает, что они будут получены из объекта , эти параметры будут указывать на соответствующие параметры в дескрипторе безопасности, возвращенном в ppSecurityDescriptor.

Чтобы считывать владельца, группу или DACL из дескриптора безопасности объекта, вызывающему процессу должен быть предоставлен READ_CONTROL доступ при открытии дескриптора. Чтобы получить доступ READ_CONTROL, вызывающий объект должен быть владельцем объекта или DACL объекта должен предоставить доступ.

Чтобы считывать saCL из дескриптора безопасности, вызывающему процессу должен быть предоставлен доступ ACCESS_SYSTEM_SECURITY при открытии дескриптора. Правильный способ получить этот доступ — включить привилегию SE_SECURITY_NAME в текущем маркере вызывающего объекта, открыть дескриптор для ACCESS_SYSTEM_SECURITY доступа, а затем отключить привилегию. Сведения о влиянии на безопасность включения привилегий см. в разделе Запуск с особыми привилегиями.

Функцию GetSecurityInfo можно использовать со следующими типами объектов:

Локальные или удаленные файлы или каталоги в файловой системе NTFS
Именованные каналы
Локальные или удаленные принтеры
Локальные или удаленные службы Windows
Сетевые общие папки
Разделы реестра
Семафоры, события, мьютексы и таймеры ожидания
Процессы, потоки, задания и объекты сопоставления файлов
Станции и настольные компьютеры с интерактивным окном обслуживания
Объекты службы каталогов

Эта функция не обрабатывает условия гонки. Если поток вызывает эту функцию в приблизительное время, когда другой поток изменяет дескриптор безопасности объекта, эта функция может завершиться ошибкой.

Примеры

Пример использования этой функции см. в разделе Поиск владельца объекта file.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	aclapi.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll