Función CreatePrivateObjectSecurityEx (securitybaseapi.h)

Artículo
03/08/2023

La función CreatePrivateObjectSecurityEx asigna e inicializa un descriptor de seguridad auto relativo para un nuevo objeto privado creado por el administrador de recursos que llama a esta función.

Sintaxis

BOOL CreatePrivateObjectSecurityEx(
  [in, optional] PSECURITY_DESCRIPTOR ParentDescriptor,
  [in, optional] PSECURITY_DESCRIPTOR CreatorDescriptor,
  [out]          PSECURITY_DESCRIPTOR *NewDescriptor,
  [in, optional] GUID                 *ObjectType,
  [in]           BOOL                 IsContainerObject,
  [in]           ULONG                AutoInheritFlags,
  [in, optional] HANDLE               Token,
  [in]           PGENERIC_MAPPING     GenericMapping
);

Parámetros

[in, optional] ParentDescriptor

Puntero al descriptor de seguridad del contenedor primario del objeto . Si no hay ningún contenedor primario, este parámetro es NULL.

[in, optional] CreatorDescriptor

Puntero a un descriptor de seguridad proporcionado por el creador del objeto. Si el creador del objeto no pasa explícitamente información de seguridad para el nuevo objeto, este parámetro puede ser NULL. Como alternativa, este parámetro puede apuntar a un descriptor de seguridad predeterminado.

[out] NewDescriptor

Puntero a una variable que recibe un puntero al descriptor de seguridad autodirección asignado recientemente. Cuando haya terminado de usar el descriptor de seguridad, puede liberarlo llamando a .
Función DestroyPrivateObjectSecurity .

[in, optional] ObjectType

Puntero a una estructura GUID que identifica el tipo de objeto asociado a NewDescriptor. Si el objeto no tiene un GUID, establezca ObjectType en NULL.

[in] IsContainerObject

Especifica si el nuevo objeto puede contener otros objetos. Un valor true indica que el nuevo objeto es un contenedor. Un valor false indica que el nuevo objeto no es un contenedor.

[in] AutoInheritFlags

Un conjunto de marcas de bits que controlan cómo se heredan las entradas de control de acceso (ACE) de ParentDescriptor. Este parámetro puede ser una combinación de los valores siguientes.

Value	Significado
SEF_AVOID_OWNER_CHECK 0x10	La función no comprueba la validez del propietario en el NewDescriptor resultante, tal como se describe en Comentarios a continuación. Si también se establece la marca SEF_AVOID_PRIVILEGE_CHECK, el parámetro Token puede ser NULL.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Se omiten las restricciones especificadas por el ParentDescriptor que limitarían la capacidad del autor de la llamada para especificar una DACL en CreatorDescriptor .
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. Esta marca es útil al implementar la herencia automática para evitar comprobar los privilegios en cada elemento secundario actualizado.
SEF_DACL_AUTO_INHERIT 0x01	La nueva lista de control de acceso discrecional (DACL) contiene ACE heredadas de la DACL de ParentDescriptor, así como de las ACE explícitas especificadas en la DACL de CreatorDescriptor. Si no se establece esta marca, la nueva DACL no hereda las ACE.
SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT 0x04	CreatorDescriptor es el descriptor predeterminado para el tipo de objeto especificado por ObjectType. Por lo tanto, CreatorDescriptor se omite si ParentDescriptor tiene cualquier ACE específica del objeto para el tipo de objeto especificado por el parámetro ObjectType . Si no se hereda este tipo de ACE, CreatorDescriptor se controla como si no se especificara esta marca.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	El grupo de NewDescriptor tiene como valor predeterminado el grupo de ParentDescriptor. Si no se establece, el grupo de NewDescriptor 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 CreatorDescriptor no es NULL, el grupo NewDescriptor se establece en el grupo desde CreatorDescriptor.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	El propietario de NewDescriptor tiene como valor predeterminado el propietario de ParentDescriptor. Si no se establece, el propietario de NewDescriptor 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 CreatorDescriptor no es NULL, el propietario de NewDescriptor se establece en el propietario de CreatorDescriptor.
SEF_MACL_NO_EXECUTE_UP 0x400	Cuando se establece esta marca, la etiqueta obligatoria ACE en CreatorDescriptor no se usa para crear una etiqueta obligatoria ACE en NewDescriptor. En su lugar, se agrega un nuevo SYSTEM_MANDATORY_LABEL_ACE con una máscara de acceso de SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP y el SID de integridad del token a NewDescriptor.
SEF_MACL_NO_READ_UP 0x200	Cuando se establece esta marca, la etiqueta obligatoria ACE en CreatorDescriptor no se usa para crear una etiqueta obligatoria ACE en NewDescriptor. En su lugar, se agrega un nuevo SYSTEM_MANDATORY_LABEL_ACE con una máscara de acceso de SYSTEM_MANDATORY_LABEL_NO_READ_UP y el SID de integridad del token a NewDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Cuando se establece esta marca, la etiqueta obligatoria ACE en CreatorDescriptor no se usa para crear una etiqueta obligatoria ACE en NewDescriptor. En su lugar, se agrega un nuevo SYSTEM_MANDATORY_LABEL_ACE con una máscara de acceso de SYSTEM_MANDATORY_LABEL_NO_WRITE_UP y el SID de integridad del token a NewDescriptor.
SEF_SACL_AUTO_INHERIT 0x02	La nueva lista de control de acceso del sistema (SACL) contiene ACE heredadas de la SACL de ParentDescriptor, así como de las ACE explícitas especificadas en la SACL de CreatorDescriptor. Si no se establece esta marca, el nuevo SACL no hereda las ACE.

[in, optional] Token

Identificador del token de acceso para el proceso de cliente en cuyo nombre se crea el objeto. Si se trata de un token de suplantación, debe estar en el nivel SecurityIdentification o superior. Para obtener una descripción completa del nivel de suplantación SecurityIdentification, consulte el SECURITY_IMPERSONATION_LEVEL tipo enumerado.

El token de cliente contiene información de seguridad predeterminada, como el propietario predeterminado, el grupo principal y DACL. La función usa estos valores predeterminados si la información no está en los descriptores de seguridad de entrada. El token debe estar abierto para TOKEN_QUERY acceso.

Si se cumplen todas las condiciones siguientes, el identificador debe abrirse para TOKEN_DUPLICATE acceso además de TOKEN_QUERY acceso.

El identificador de token hace referencia a un token principal.
El descriptor de seguridad del token contiene uno o varios ACE con el SID OwnerRights .
Se especifica un descriptor de seguridad para el parámetro CreatorDescriptor .
El autor de la llamada de esta función no establece la marca SEF_AVOID_OWNER_RESTRICTION en el parámetro AutoInheritFlags .

[in] GenericMapping

Puntero a una estructura de GENERIC_MAPPING que especifica la asignación de cada derecho genérico a derechos específicos para el objeto.

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. Algunos de los códigos de error extendidos y sus significados se enumeran en la tabla siguiente.

Código devuelto	Descripción
ERROR_INVALID_OWNER	La función no puede recuperar un propietario para el nuevo descriptor de seguridad o el SID no se puede asignar como propietario. Esto se produce al validar el SID de propietario con el token pasado.
ERROR_INVALID_PRIMARY_GROUP	La función no puede recuperar un grupo principal para el nuevo descriptor de seguridad.
ERROR_NO_TOKEN	La función recibió NULL en lugar de un token para la validación del propietario o la comprobación de privilegios.
ERROR_PRIVILEGE_NOT_HELD	Se establece una SACL, no se pasó SEF_AVOID_PRIVILEGE_CHECK y el token pasado no tenía habilitado SE_SECURITY_NAME.

Comentarios

La función CreatePrivateObjectSecurity es idéntica a llamar a la función CreatePrivateObjectSecurityEx con ObjectType establecido en NULL y AutoInheritFlags establecido en cero.

El parámetro AutoInheritFlags es distinto de los bits con nombre similar del miembro Control de la estructura SECURITY_DESCRIPTOR . Para obtener una explicación de los bits de control, consulte SECURITY_DESCRIPTOR_CONTROL.

Si AutoInheritFlags especifica el bit de SEF_DACL_AUTO_INHERIT, la función aplica las siguientes reglas a la DACL en el nuevo descriptor de seguridad:

La marca SE_DACL_AUTO_INHERITED se establece en el miembro Control del nuevo descriptor de seguridad.
La DACL del nuevo descriptor de seguridad hereda las ACE del parentDescriptor , independientemente de si CreatorDescriptor es el descriptor de seguridad predeterminado o se especificó explícitamente por el creador. La nueva DACL es una combinación de las DACL primarias y creadores definidas por las reglas de herencia.
Las ACE heredadas se marcan como 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, ciertos tipos de ACE en ParentDescriptor y CreatorDescriptor se manipularán y posiblemente se reemplazarán por dos ACE en NewDescriptor. En concreto, una ACE heredable que contiene al menos uno de los siguientes elementos asignables puede dar lugar a dos ACE en el descriptor de seguridad de salida. Entre los elementos asignables se incluyen:

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

Las ACE con cualquiera de los elementos asignables mencionados anteriormente darán lugar a las siguientes ACE en NewDescriptor:

Ace que es una copia del original, pero con la marca INHERIT_ONLY establecida. Sin embargo, esta ACE no se creará si existe alguna de las dos condiciones siguientes:
- El parámetro IsContainerObject es FALSE. Los AEC heredables no tienen sentido en objetos que no son de contenedor.
- La ACE original contiene la marca NO_PROPAGATE_INHERIT. La ACE original está pensada para ser heredada como una ACE efectiva en los elementos secundarios, pero no se pueden heredar por debajo de esos elementos secundarios.
Una ACE eficaz en la que el bit de INHERITED_ACE está activado y los elementos genéricos se asignan a elementos específicos, entre los que se incluyen:
- 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 el newdescriptor resultante.
- El SID del grupo de creadores se reemplaza por el grupo en el newDescriptor resultante.

Si AutoInheritFlags no especifica el bit de SEF_AVOID_OWNER_CHECK, se realiza la comprobación de validez del propietario. El propietario del NewDescriptor resultante debe ser un SID con formato legal y debe coincidir con tokenUser en Token o coincidir con un grupo de TokenGroups en Token donde los atributos del grupo deben incluir SE_GROUP_OWNER y no deben incluir SE_GROUP_USE_FOR_DENY_ONLY.

Los autores de llamadas que no tienen acceso al token del cliente que en última instancia establecerán el propietario pueden optar por omitir la comprobación de validación del propietario.

Para crear un descriptor de seguridad para un nuevo objeto, llame a CreatePrivateObjectSecurityEx con ParentDescriptor establecido en el descriptor de seguridad del contenedor primario y CreatorDescriptor establecido en el descriptor de seguridad propuesto por el creador del objeto.

Si el descriptor de seguridad CreatorDescriptor contiene una SACL, el token debe tener habilitado el privilegio SE_SECURITY_NAME o el autor de la llamada debe especificar la marca SEF_AVOID_PRIVILEGE_CHECK en AutoInheritFlags.

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