Función SetPrivateObjectSecurityEx (securitybaseapi.h)

Artículo
03/08/2023

La función SetPrivateObjectSecurityEx modifica el descriptor de seguridad de un objeto privado mantenido por el administrador de recursos que llama a esta función. La función SetPrivateObjectSecurityEx tiene un parámetro flags que especifica si el administrador de recursos admite la herencia automática de entradas de control de acceso (ACE).

Sintaxis

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

Parámetros

[in] SecurityInformation

Partes del descriptor de seguridad que se van a establecer. Este valor puede ser una combinación de las marcas de bits de SECURITY_INFORMATION.

[in] ModificationDescriptor

Puntero a una estructura SECURITY_DESCRIPTOR . Las partes de este descriptor de seguridad indicados por el parámetro SecurityInformation se aplican al descriptor de seguridad ObjectsSecurityDescriptor .

[in, out] ObjectsSecurityDescriptor

Puntero a un puntero a una estructura de SECURITY_DESCRIPTOR . Este descriptor de seguridad debe estar en forma auto relativa . La memoria del descriptor de seguridad debe asignarse desde el montón de procesos (GetProcessHeap) con la función HeapAlloc.

En la entrada, este es el descriptor de seguridad actual del objeto privado. La función lo modifica para generar el nuevo descriptor de seguridad. Si es necesario, la función SetPrivateObjectSecurityEx asigna memoria adicional para generar un descriptor de seguridad mayor.

[in] AutoInheritFlags

Especifica la herencia automática de ACE. Si el servidor protegido no implementa la herencia automática, debe especificar cero; de lo contrario, puede especificar una combinación de los valores siguientes, definidos en Winnt.h.

Valor	Significado
SEF_DACL_AUTO_INHERIT 0x01	La nueva lista de control de acceso discrecional (DACL) contiene ACE heredadas de la DACL del elemento primario del objeto, así como de las ACE explícitas especificadas en la DACL de ModificationDescriptor. Si no se establece esta marca, la nueva DACL no hereda las ACE.
SEF_SACL_AUTO_INHERIT 0x02	La nueva lista de control de acceso del sistema (SACL) contiene ACE heredadas de la SACL del descriptor de seguridad asociado al elemento primario del objeto, así como de las ACE explícitas especificadas en la SACL de ModificationDescriptor. Si no se establece esta marca, el nuevo SACL no hereda las ACE.
SEF_AVOID_PRIVILEGE_CHECK 0x08	La función no realiza la comprobación de privilegios. Si también se establece la marca SEF_AVOID_OWNER_CHECK , el parámetro Token puede ser NULL. Use esta marca al implementar la herencia automática para evitar comprobar los privilegios en cada elemento secundario actualizado.
SEF_AVOID_OWNER_CHECK 0x10	La función no comprueba la validez del propietario en el objeto ObjectsSecurityDescriptor resultante, como se describe en Comentarios. Si también se establece la marca SEF_AVOID_PRIVILEGE_CHECK , el parámetro Token puede ser NULL.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	El propietario de ObjectsSecurityDescriptor tiene como valor predeterminado el propietario del elemento primario del objeto. Si no se establece esta marca, el propietario de ObjectsSecurityDescriptor tiene como valor predeterminado el propietario del token especificado por el parámetro Token . El propietario del token se especifica en el propio token. En cualquier caso, si el parámetro ModificationDescriptor no es NULL, el propietario ObjectsSecurityDescriptor se establece en el propietario de ModificationDescriptor.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	El grupo de ObjectsSecurityDescriptor tiene como valor predeterminado el grupo del propietario del elemento primario del objeto. Si no se establece esta marca, el grupo de ObjectsSecurityDescriptor tiene como valor predeterminado el grupo del token especificado por el parámetro Token . El grupo del token se especifica en el propio token. En cualquier caso, si el parámetro ModificationDescriptor no es NULL, el grupo ObjectsSecurityDescriptor se establece en el grupo de ModificationDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Una entidad de seguridad con un nivel obligatorio inferior al del objeto no puede escribir en el objeto .
SEF_MACL_NO_READ_UP 0x200	Una entidad de seguridad con un nivel obligatorio inferior al del objeto no puede leer el objeto.
SEF_MACL_NO_EXECUTE_UP 0x400	Una entidad de seguridad con un nivel obligatorio inferior al del objeto no puede ejecutar el objeto .
SEF_AVOID_OWNER_RESTRICTION 0x1000	Se omiten las restricciones especificadas por el propietario del elemento primario del objeto que limitarían la capacidad del autor de la llamada para especificar una DACL en objectsSecurityDescriptor .

[in] GenericMapping

Puntero a una estructura de GENERIC_MAPPING que especifica los derechos de acceso específicos y estándar que corresponden a cada uno de los derechos de acceso genéricos.

[in, optional] Token

Identifica el token de acceso del cliente en cuyo nombre se está modificando la seguridad del objeto privado. Este parámetro es necesario para asegurarse de que el cliente ha proporcionado un valor legítimo para un nuevo identificador de seguridad de propietario (SID). El token debe estar abierto para TOKEN_QUERY acceso.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.

Si se produce un error en la función, devuelve cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Si el parámetro AutoInheritFlags es cero, SetPrivateObjectSecurityEx es idéntico a la función SetPrivateObjectSecurity .

Esta función está pensada solo para que la usen los administradores de recursos. Para implementar la semántica de control de acceso estándar de Windows para actualizar los descriptores de seguridad, un administrador de recursos debe comprobar que se cumplen las condiciones siguientes antes de llamar a SetPrivateObjectSecurityEx:

Si se establece el propietario del objeto, el proceso de llamada debe tener WRITE_OWNER permiso o ser el propietario del objeto.
Si se establece la DACL del objeto, el proceso de llamada debe tener WRITE_DAC permiso o ser el propietario del objeto.
Si se establece la SACL del objeto, se debe habilitar el privilegio SE_SECURITY_NAME para el proceso de llamada.

Si no se cumplen las condiciones anteriores, no se produce un error en una llamada a esta función, pero no se aplica la directiva de acceso estándar de Windows.

El proceso que llama a esta función no debe suplantar a un cliente porque los clientes no suelen tener los privilegios adecuados necesarios para las operaciones de token subyacentes.

Si AutoInheritFlags especifica el bit de SEF_DACL_AUTO_INHERIT, la función aplica las siguientes reglas a la DACL para crear el nuevo descriptor de seguridad a partir del descriptor actual:

Si la marca de SE_DACL_PROTECTED no está establecida en los bits de control del descriptor de seguridad actual o del modificationDescriptor, la función construye el descriptor de seguridad de salida a partir de los ACE heredados del descriptor de seguridad actual y los ACE noheritados de ModificationDescriptor. Es decir, es imposible cambiar una ACE heredada cambiando la lista de control de acceso (ACL) en un objeto. Este comportamiento conserva los ASE heredados a medida que se heredan del contenedor primario.
Un editor de ACL debe hacer que las ACE heredadas no estén disponibles para evitar que se modifiquen.
Si SE_DACL_PROTECTED se establece en ModificationDescriptor, se omite el descriptor de seguridad actual. El descriptor de seguridad de salida se crea como una copia de ModificationDescriptor con los bits de INHERITED_ACE desactivados.
Lo ideal es que un editor de ACL desactive los bits de INHERITED_ACE que indican a su autor de la llamada que los ACE heredan del elemento primario del objeto ahora se establecen explícitamente en el objeto .
Si SE_DACL_PROTECTED se establece en el descriptor de seguridad actual y no en ModificationDescriptor, se omite el descriptor de seguridad actual. El descriptor de seguridad de salida se crea como una copia de ModificationDescriptor. Es responsabilidad del autor de la llamada asegurarse de que los ACE correctos tienen activado el bit de INHERITED_ACE.

Si AutoInheritFlags especifica el bit de SEF_SACL_AUTO_INHERIT, la función aplica reglas similares a la nueva SACL.

Para las DACL y SACL, determinados tipos de ACL en los objetos de entradaSecurityDescriptor y en ModificationDescriptor se reemplazarán por dos ACE en el objeto ObjectsSecurityDescriptor de salida. En concreto, una ACE heredable que contenga al menos uno de los siguientes elementos asignables dará como resultado dos ACE en el objeto ObjectsSecurityDescriptor de salida. Entre los elementos asignables se incluyen:

Derechos de acceso genéricos en la estructura de ACCESS_MASK
SID de propietario del creador o SID del grupo de creadores como identificador del sujeto ace

Las ACE con cualquiera de estos elementos asignables darán lugar a las dos ACE siguientes en el objeto ObjectsSecurityDescriptor de salida:

Ace que es una copia del original, pero con la marca INHERIT_ONLY establecida
Ace en la que se activa el bit de INHERITED_ACE y los elementos genéricos se asignan a elementos específicos:
- Los derechos de acceso genéricos se reemplazan por los derechos de acceso estándar y específicos correspondientes indicados en la entrada GenericMapping.
- El SID del propietario del creador se reemplaza por el propietario en la salida SecurityDescriptor
- El SID del grupo de creadores se reemplaza por el grupo en el securityDescriptor de salida.

Si AutoInheritFlags no especifica el bit de SEF_AVOID_PRIVILEGE_CHECK, la comprobación de validez del propietario se realiza según las reglas siguientes. Propietario en ModificationDescriptor:

Debe ser un SID con formato legal
Debe coincidir con TokenUser en Token

Debe coincidir con un grupo de TokenGroups en Token donde los atributos del grupo:
- Incluir SE_GROUP_OWNER
- Incluir SE_GROUP_USE_FOR_DENY_ONLY

Un administrador de recursos que establece el propietario en un subárbol de objetos puede evitar la sobrecarga de la comprobación de validez del propietario redundante. Si el propietario de ModificationDescriptor y token siguen siendo los mismos para las llamadas iterativas a esta función, el bit de SEF_AVOID_PRIVILEGE_CHECK se puede establecer en AutoInheritFlags para las llamadas posteriores a una llamada inicial en la que se realiza la comprobación de validez del propietario. Los autores de llamadas que no tienen acceso al token del cliente que, en última instancia, establecerán el propietario también deben optar por omitir la comprobación de validación del propietario.

Nota El bit de SEF_AVOID_PRIVILEGE_CHECK como se usa en la función SetPrivateObjectSecurityEx es equivalente al bit de SEF_AVOID_OWNER_CHECK usado en la función CreatePrivateObjectSecurityEx .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll