Função CreatePrivateObjectSecurityEx (securitybaseapi.h)

Artigo
03/01/2024

A função CreatePrivateObjectSecurityEx aloca e inicializa um descritor de segurança auto-relativo para um novo objeto privado criado pelo gerenciador de recursos que chama essa função.

Sintaxe

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

Um ponteiro para o descritor de segurança para o contêiner pai do objeto. Se não houver nenhum contêiner pai, esse parâmetro será NULL.

[in, optional] CreatorDescriptor

Um ponteiro para um descritor de segurança fornecido pelo criador do objeto. Se o criador do objeto não passar explicitamente informações de segurança para o novo objeto, esse parâmetro poderá ser NULL. Como alternativa, esse parâmetro pode apontar para um descritor de segurança padrão.

[out] NewDescriptor

Um ponteiro para uma variável que recebe um ponteiro para o descritor de segurança auto-relativo recém-alocado. Quando terminar de usar o descritor de segurança, libere-o chamando o
Função DestroyPrivateObjectSecurity .

[in, optional] ObjectType

Um ponteiro para uma estrutura GUID que identifica o tipo de objeto associado a NewDescriptor. Se o objeto não tiver um GUID, defina ObjectType como NULL.

[in] IsContainerObject

Especifica se o novo objeto pode conter outros objetos. Um valor true indica que o novo objeto é um contêiner. Um valor false indica que o novo objeto não é um contêiner.

[in] AutoInheritFlags

Um conjunto de sinalizadores de bits que controlam como as ACEs ( entradas de controle de acesso ) são herdadas de ParentDescriptor. Esse parâmetro pode ser uma combinação dos seguintes valores.

Valor	Significado
SEF_AVOID_OWNER_CHECK 0x10	A função não marcar a validade do proprietário no NewDescriptor resultante, conforme descrito nos Comentários abaixo. Se o sinalizador SEF_AVOID_PRIVILEGE_CHECK também estiver definido, o parâmetro Token poderá ser NULL.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Todas as restrições especificadas pelo ParentDescriptor que limitariam a capacidade do chamador de especificar uma DACL no CreatorDescriptor são ignoradas.
SEF_AVOID_PRIVILEGE_CHECK 0x08	A função não executa a verificação de privilégios. Se o sinalizador SEF_AVOID_OWNER_CHECK também estiver definido, o parâmetro Token poderá ser NULL. Esse sinalizador é útil ao implementar a herança automática para evitar a verificação de privilégios em cada filho atualizado.
SEF_DACL_AUTO_INHERIT 0x01	A nova DACL ( lista de controle de acesso discricionário ) contém ACEs herdadas da DACL de ParentDescriptor, bem como quaisquer ACEs explícitas especificadas na DACL de CreatorDescriptor. Se esse sinalizador não estiver definido, a nova DACL não herdará ACEs.
SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT 0x04	CreatorDescriptor é o descritor padrão para o tipo de objeto especificado por ObjectType. Dessa forma, CreatorDescriptor será ignorado se ParentDescriptor tiver ACEs específicas do objeto para o tipo de objeto especificado pelo parâmetro ObjectType . Se esses ACEs não forem herdados, CreatorDescriptor será tratado como se esse sinalizador não tivesse sido especificado.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	O grupo de NewDescriptor usa como padrão o grupo de ParentDescriptor. Se não for definido, o grupo de NewDescriptor usará como padrão o grupo do token especificado pelo parâmetro Token . O grupo do token é especificado no próprio token. Em ambos os casos, se o parâmetro CreatorDescriptor não for NULL, o grupo NewDescriptor será definido como o grupo de CreatorDescriptor.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	O proprietário de NewDescriptor usa como padrão o proprietário de ParentDescriptor. Se não for definido, o proprietário de NewDescriptor usará como padrão o proprietário do token especificado pelo parâmetro Token . O proprietário do token é especificado no próprio token. Em ambos os casos, se o parâmetro CreatorDescriptor não for NULL, o proprietário de NewDescriptor será definido como o proprietário do CreatorDescriptor.
SEF_MACL_NO_EXECUTE_UP 0x400	Quando esse sinalizador é definido, o rótulo obrigatório ACE em CreatorDescriptor não é usado para criar um rótulo obrigatório ACE em NewDescriptor. Em vez disso, um novo SYSTEM_MANDATORY_LABEL_ACE com uma máscara de acesso de SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP e o SID do SID de integridade do token é adicionado ao NewDescriptor.
SEF_MACL_NO_READ_UP 0x200	Quando esse sinalizador é definido, o rótulo obrigatório ACE em CreatorDescriptor não é usado para criar um rótulo obrigatório ACE em NewDescriptor. Em vez disso, um novo SYSTEM_MANDATORY_LABEL_ACE com uma máscara de acesso de SYSTEM_MANDATORY_LABEL_NO_READ_UP e o SID do SID de integridade do token é adicionado ao NewDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Quando esse sinalizador é definido, o rótulo obrigatório ACE em CreatorDescriptor não é usado para criar um rótulo obrigatório ACE em NewDescriptor. Em vez disso, um novo SYSTEM_MANDATORY_LABEL_ACE com uma máscara de acesso de SYSTEM_MANDATORY_LABEL_NO_WRITE_UP e o SID do SID de integridade do token é adicionado ao NewDescriptor.
SEF_SACL_AUTO_INHERIT 0x02	A nova SACL ( lista de controle de acesso do sistema ) contém ACEs herdadas da SACL de ParentDescriptor, bem como quaisquer ACEs explícitas especificadas na SACL de CreatorDescriptor. Se esse sinalizador não estiver definido, a nova SACL não herdará ACEs.

[in, optional] Token

Um identificador para o token de acesso para o processo do cliente em cujo nome o objeto está sendo criado. Se esse for um token de representação, ele deverá estar no nível securityIdentification ou superior. Para obter uma descrição completa do nível de representação SecurityIdentification, consulte o SECURITY_IMPERSONATION_LEVEL tipo enumerado.

O token de cliente contém informações de segurança padrão, como o proprietário padrão, o grupo primário e a DACL. A função usará esses padrões se as informações não estiverem nos descritores de segurança de entrada. O token deve estar aberto para acesso TOKEN_QUERY .

Se todas as condições a seguir forem verdadeiras, o identificador deverá ser aberto para acesso TOKEN_DUPLICATE além de acesso TOKEN_QUERY .

O identificador de token refere-se a um token primário.
O descritor de segurança do token contém um ou mais ACEs com o SID OwnerRights .
Um descritor de segurança é especificado para o parâmetro CreatorDescriptor .
O chamador dessa função não define o sinalizador SEF_AVOID_OWNER_RESTRICTION no parâmetro AutoInheritFlags .

[in] GenericMapping

Um ponteiro para uma estrutura GENERIC_MAPPING que especifica o mapeamento de cada direito genérico para direitos específicos para o objeto.

Retornar valor

Se a função for bem-sucedida, a função retornará diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError. Alguns dos códigos de erro estendidos e seus significados estão listados na tabela a seguir.

Código de retorno	Descrição
ERROR_INVALID_OWNER	A função não pode recuperar um proprietário para o novo descritor de segurança ou o SID não pode ser atribuído como proprietário. Isso ocorre ao validar o SID do proprietário em relação ao token passado.
ERROR_INVALID_PRIMARY_GROUP	A função não pode recuperar um grupo primário para o novo descritor de segurança.
ERROR_NO_TOKEN	A função recebeu NULL em vez de um token para validação de proprietário ou verificação de privilégios.
ERROR_PRIVILEGE_NOT_HELD	Uma SACL está sendo definida, SEF_AVOID_PRIVILEGE_CHECK não foi passada e o token passado não tinha SE_SECURITY_NAME habilitado.

Comentários

A função CreatePrivateObjectSecurity é idêntica a chamar a função CreatePrivateObjectSecurityEx com ObjectType definido como NULL e AutoInheritFlags definido como zero.

O parâmetro AutoInheritFlags é distinto dos bits nomeados da mesma forma no membro Control da estrutura SECURITY_DESCRIPTOR . Para obter uma explicação dos bits de controle, consulte SECURITY_DESCRIPTOR_CONTROL.

Se AutoInheritFlags especificar o bit SEF_DACL_AUTO_INHERIT, a função aplicará as seguintes regras à DACL no novo descritor de segurança:

O sinalizador SE_DACL_AUTO_INHERITED é definido no membro Control do novo descritor de segurança.
A DACL do novo descritor de segurança herda ACEs do ParentDescriptor , independentemente de CreatorDescriptor ser o descritor de segurança padrão ou ter sido explicitamente especificado pelo criador. A nova DACL é uma combinação dos DACLs pai e criador, conforme definido pelas regras de herança.
ACEs herdados são marcados como INHERITED_ACE.

Se AutoInheritFlags especificar o bit SEF_SACL_AUTO_INHERIT, a função aplicará regras semelhantes à nova SACL.

Para DACLs e SACLs, determinados tipos de ACEs em ParentDescriptor e CreatorDescriptor serão manipulados e possivelmente substituídos por duas ACEs em NewDescriptor. Especificamente, uma ACE herdável que contém pelo menos um dos seguintes elementos maplicativos pode resultar em dois ACEs no descritor de segurança de saída. Os elementos maplicativos incluem:

Direitos de acesso genéricos no ACCESS_MASK
SID do Proprietário do Criador ou SID do Grupo do Criador como o identificador de assunto ace

AcEs com qualquer um dos elementos mappable mencionados anteriormente resultarão nos seguintes ACEs em NewDescriptor:

Uma ACE que é uma cópia do original, mas com o sinalizador INHERIT_ONLY definido. No entanto, essa ACE não será criada se uma das duas condições a seguir existir:
- O parâmetro IsContainerObject é FALSE. ACEs herdáveis não têm sentido em objetos não pertencentes a contêineres.
- O ACE original contém o sinalizador NO_PROPAGATE_INHERIT. A ACE original destina-se a ser herdada como uma ACE eficaz em crianças, mas não herdável abaixo desses filhos.
Uma ACE efetiva na qual o INHERITED_ACE bit é ativado e os elementos genéricos são mapeados para elementos específicos, incluindo:
- Os direitos de acesso genéricos são substituídos pelos direitos de acesso padrão e específicos correspondentes indicados no GenericMapping de entrada.
- O SID do Proprietário do Criador é substituído pelo Proprietário no NewDescriptor resultante
- O SID do Grupo do Criador é substituído pelo Grupo no NewDescriptor resultante

Se AutoInheritFlags não especificar o bit SEF_AVOID_OWNER_CHECK, a verificação de validade do proprietário será executada. O Proprietário no NewDescriptor resultante deve ser um SID formado legalmente e deve corresponder ao TokenUser em Token ou corresponder a um grupo em TokenGroups no Token em que os atributos no grupo devem incluir SE_GROUP_OWNER e não devem incluir SE_GROUP_USE_FOR_DENY_ONLY.

Os chamadores que não têm acesso ao token do cliente que, em última análise, definirão o proprietário podem optar por ignorar a verificação de validação do proprietário.

Para criar um descritor de segurança para um novo objeto, chame CreatePrivateObjectSecurityEx com ParentDescriptor definido como o descritor de segurança do contêiner pai e CreatorDescriptor definido como o descritor de segurança proposto pelo criador do objeto.

Se o descritor de segurança CreatorDescriptor contiver uma SACL, o Token deverá ter o privilégio SE_SECURITY_NAME habilitado ou o chamador deverá especificar o sinalizador SEF_AVOID_PRIVILEGE_CHECK em AutoInheritFlags.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll