Функция SetPrivateObjectSecurityEx (securitybaseapi.h)

Статья
03/08/2023

Функция SetPrivateObjectSecurityEx изменяет дескриптор безопасности частного объекта, поддерживаемого диспетчером ресурсов, вызывающим эту функцию. Функция SetPrivateObjectSecurityEx имеет параметр flags, указывающий, поддерживает ли диспетчер ресурсов автоматическое наследование записей управления доступом (ACE).

Синтаксис

BOOL SetPrivateObjectSecurityEx(
  [in]           SECURITY_INFORMATION SecurityInformation,
  [in]           PSECURITY_DESCRIPTOR ModificationDescriptor,
  [in, out]      PSECURITY_DESCRIPTOR *ObjectsSecurityDescriptor,
  [in]           ULONG                AutoInheritFlags,
  [in]           PGENERIC_MAPPING     GenericMapping,
  [in, optional] HANDLE               Token
);

Параметры

[in] SecurityInformation

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

[in] ModificationDescriptor

Указатель на структуру SECURITY_DESCRIPTOR . Части этого дескриптора безопасности, указанные параметром SecurityInformation , применяются к дескриптору безопасности ObjectsSecurityDescriptor .

[in, out] ObjectsSecurityDescriptor

Указатель на указатель на структуру SECURITY_DESCRIPTOR . Этот дескриптор безопасности должен иметь самостоятельную форму. Память для дескриптора безопасности должна быть выделена из кучи процесса (GetProcessHeap) с помощью функции HeapAlloc.

На входных данных это текущий дескриптор безопасности частного объекта. Функция изменяет его, чтобы создать новый дескриптор безопасности. При необходимости функция SetPrivateObjectSecurityEx выделяет дополнительную память для создания дескриптора безопасности большего размера.

[in] AutoInheritFlags

Задает автоматическое наследование ACE. Если защищенный сервер не реализует автоматическое наследование, он должен указать ноль; В противном случае можно указать сочетание следующих значений, определенных в Winnt.h.

Значение	Значение
SEF_DACL_AUTO_INHERIT 0x01	Новый список управления доступом на уровне пользователей (DACL) содержит ACE, унаследованные от DACL родительского объекта, а также все явные ACE, указанные в DACL дескриптора modificationDescriptor. Если этот флаг не задан, новый daCL не наследует ACE.
SEF_SACL_AUTO_INHERIT 0x02	Новый системный список управления доступом (SACL) содержит ACE, унаследованные от SACL дескриптора безопасности, связанного с родительским объектом объекта, а также все явные ACE, указанные в списке УПРАВЛЕНИЯ saCL дескриптора modificationDescriptor. Если этот флаг не задан, новый saCL не наследует ACE.
SEF_AVOID_PRIVILEGE_CHECK 0x08	Функция не выполняет проверку привилегий. Если также установлен флаг SEF_AVOID_OWNER_CHECK , параметр Token может иметь значение NULL. Используйте этот флаг при реализации автоматического наследования, чтобы избежать проверки привилегий для каждого обновляемого дочернего элемента.
SEF_AVOID_OWNER_CHECK 0x10	Функция не проверка допустимость владельца в результирующем объекте ObjectsSecurityDescriptor, как описано в разделе Примечания. Если флаг SEF_AVOID_PRIVILEGE_CHECK также установлен, параметр Token может иметь значение NULL.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	Владелец ObjectsSecurityDescriptor по умолчанию является владельцем родительского объекта. Если этот флаг не задан, владелец ObjectsSecurityDescriptor по умолчанию будет владельцем маркера, указанного параметром Token . Владелец маркера указывается в самом маркере. В любом случае, если параметр ModificationDescriptor не равен NULL, для владельца ObjectsSecurityDescriptor устанавливается владелец из ModificationDescriptor.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	Группа ObjectsSecurityDescriptor по умолчанию является группой владельца родительского объекта. Если этот флаг не задан, группа ObjectsSecurityDescriptor по умолчанию соответствует группе маркера, заданной параметром Token . Группа маркера указывается в самом маркере. В любом случае, если параметр ModificationDescriptor не равен NULL, группе ObjectsSecurityDescriptor присваивается группа из ModificationDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Субъект с обязательным уровнем ниже, чем у объекта , не может выполнять запись в объект .
SEF_MACL_NO_READ_UP 0x200	Субъект с обязательным уровнем ниже, чем у объекта , не может считать объект.
SEF_MACL_NO_EXECUTE_UP 0x400	Субъект с обязательным уровнем ниже, чем у объекта , не может выполнить объект .
SEF_AVOID_OWNER_RESTRICTION 0x1000	Любые ограничения, заданные владельцем родительского объекта, которые ограничивают возможность вызывающего объекта указывать DACL в ObjectsSecurityDescriptor , игнорируются.

[in] GenericMapping

Указатель на структуру GENERIC_MAPPING , которая указывает конкретные и стандартные права доступа, соответствующие каждому из универсальных прав доступа.

[in, optional] Token

Определяет маркер доступа для клиента, от имени которого изменяется безопасность частного объекта. Этот параметр необходим, чтобы убедиться, что клиент предоставил допустимое значение для нового идентификатора безопасности владельца (SID). Маркер должен быть открыт для доступа TOKEN_QUERY.

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

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

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

Эта функция предназначена только для диспетчеров ресурсов. Чтобы реализовать стандартную семантику управления доступом Windows для обновления дескрипторов безопасности, диспетчер ресурсов должен проверить выполнение следующих условий перед вызовом Метода SetPrivateObjectSecurityEx:

Если задан владелец объекта, вызывающий процесс должен иметь разрешение WRITE_OWNER или быть владельцем объекта.
Если задается daCL объекта, вызывающий процесс должен иметь разрешение WRITE_DAC или быть владельцем объекта.
Если задается saCL объекта, для вызывающего процесса необходимо включить привилегию SE_SECURITY_NAME.

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

Процесс, вызывающий эту функцию, не должен олицетворение клиента, так как клиенты обычно не имеют соответствующих привилегий, необходимых для базовых операций с маркерами.

Если AutoInheritFlags указывает бит SEF_DACL_AUTO_INHERIT, функция применяет следующие правила к DACL, чтобы создать дескриптор безопасности из текущего дескриптора:

Если флаг SE_DACL_PROTECTED не задан в управляющих битах текущего дескриптора безопасности или Дескриптора модификации, функция создает дескриптор безопасности вывода из унаследованных ACE текущего дескриптора безопасности и ненаследуемых ACE дескриптора modificationDescriptor. То есть невозможно изменить унаследованный ACE путем изменения списка управления доступом (ACL) для объекта. Это поведение сохраняет унаследованные ACE так, как они были унаследованы от родительского контейнера.
Редактор ACL должен сделать унаследованные ACE недоступными, чтобы предотвратить их изменение.
Если SE_DACL_PROTECTED задано в ModificationDescriptor, текущий дескриптор безопасности игнорируется. Дескриптор безопасности выходных данных создается как копия Дескриптора изменений с отключенными битами INHERITED_ACE.
В идеале редактор ACL должен отключать INHERITED_ACE битов, которые указывают вызывающей стороне, что ACE, унаследованные от родительского объекта, теперь явно задаются для объекта .
Если SE_DACL_PROTECTED задано в текущем дескрипторове безопасности, а не в Дескрипторове изменений, текущий дескриптор безопасности игнорируется. Дескриптор безопасности выходных данных создается как копия Дескриптора изменений. Ответственность за обеспечение включения бита INHERITED_ACE в правильных ACE лежит на вызывающем объекте.

Если AutoInheritFlags указывает бит SEF_SACL_AUTO_INHERIT, функция применяет аналогичные правила к новому saCL.

Для списков DACL и SACL определенные типы ACE во входных объектах ObjectsSecurityDescriptor и в ModificationDescriptor будут заменены двумя ACE в выходном объекте ObjectsSecurityDescriptor. В частности, наследуемый элемент управления доступом, содержащий по крайней мере один из следующих сопоставляемых элементов, приведет к созданию двух ACE в выходном объекте ObjectsSecurityDescriptor. К сопоставляемым элементам относятся:

Универсальные права доступа в структуре ACCESS_MASK
Sid creator Owner SID или Creator Group SID в качестве идентификатора субъекта ACE

ACE с любым из этих сопоставляемых элементов приведет к следующим двум ACE в выходном объекте ObjectsSecurityDescriptor:

ACE, который является копией оригинала, но с установленным флагом INHERIT_ONLY
ACE, в котором включается бит INHERITED_ACE, а универсальные элементы сопоставляются с определенными элементами:
- Универсальные права доступа заменяются соответствующими стандартными и конкретными правами доступа, указанными во входных параметрах GenericMapping.
- Идентификатор безопасности владельца создателя заменяется владельцем в выходном securityDescriptor.
- Sid Creator Group заменяется на Group в выходном securityDescriptor.

Если autoInheritFlags не указывает бит SEF_AVOID_PRIVILEGE_CHECK, проверка допустимости владельца выполняется в соответствии со следующими правилами. Владелец в ModificationDescriptor:

Должен быть юридически сформированным SID
Должен соответствовать TokenUser в token

либо

Должен соответствовать группе в TokenGroups в token , где атрибуты группы:
- Включить SE_GROUP_OWNER
- Включить SE_GROUP_USE_FOR_DENY_ONLY

Диспетчер ресурсов, задающий владельца в поддереве объектов, может избежать накладных расходов, связанных с проверкой допустимости избыточности владельца. Если владелец в ModificationDescriptor и Token остаются неизменными для итеративных вызовов этой функции, бит SEF_AVOID_PRIVILEGE_CHECK может быть задан в AutoInheritFlags для вызовов после первоначального вызова, в котором выполняется проверка владельца на допустимость. Вызывающие абоненты, у которых нет доступа к маркеру клиента, который в конечном итоге будет задавать владельца, также должны пропустить проверку владельца.

Примечание Бит SEF_AVOID_PRIVILEGE_CHECK, используемый в функции SetPrivateObjectSecurityEx , эквивалентен SEF_AVOID_OWNER_CHECK биту, используемому в функции CreatePrivateObjectSecurityEx .

Требования

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