Função SetPrivateObjectSecurityEx (securitybaseapi.h)

Artigo
03/01/2024

A função SetPrivateObjectSecurityEx modifica o descritor de segurança de um objeto privado mantido pelo gerenciador de recursos que chama essa função. A função SetPrivateObjectSecurityEx tem um parâmetro flags que especifica se o gerenciador de recursos dá suporte à herança automática de ACEs ( entradas de controle de acesso ).

Sintaxe

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

As partes do descritor de segurança a ser definido. Esse valor pode ser uma combinação dos sinalizadores de bit SECURITY_INFORMATION.

[in] ModificationDescriptor

Um ponteiro para uma estrutura SECURITY_DESCRIPTOR . As partes desse descritor de segurança indicadas pelo parâmetro SecurityInformation são aplicadas ao descritor de segurança ObjectsSecurityDescriptor .

[in, out] ObjectsSecurityDescriptor

Um ponteiro para um ponteiro para uma estrutura SECURITY_DESCRIPTOR . Esse descritor de segurança deve estar em forma auto-relativa . A memória do descritor de segurança deve ser alocada do heap de processo (GetProcessHeap) com a função HeapAlloc.

Na entrada, esse é o descritor de segurança atual do objeto privado. A função a modifica para produzir o novo descritor de segurança. Se necessário, a função SetPrivateObjectSecurityEx aloca memória adicional para produzir um descritor de segurança maior.

[in] AutoInheritFlags

Especifica a herança automática de ACEs. Se o servidor protegido não implementar a herança automática, ele deverá especificar zero; caso contrário, ele pode especificar uma combinação dos valores a seguir, definidos em Winnt.h.

Valor	Significado
SEF_DACL_AUTO_INHERIT 0x01	A nova DACL ( lista de controle de acesso discricionário ) contém ACEs herdadas da DACL do pai do objeto, bem como quaisquer ACEs explícitas especificadas na DACL de ModificationDescriptor. Se esse sinalizador não estiver definido, a nova DACL não herdará ACEs.
SEF_SACL_AUTO_INHERIT 0x02	A nova SACL ( lista de controle de acesso do sistema ) contém ACEs herdadas da SACL do descritor de segurança associado ao pai do objeto, bem como quaisquer ACEs explícitas especificadas na SACL de ModificationDescriptor. Se esse sinalizador não estiver definido, a nova SACL não herdará ACEs.
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. Use esse sinalizador ao implementar a herança automática para evitar a verificação de privilégios em cada filho atualizado.
SEF_AVOID_OWNER_CHECK 0x10	A função não marcar a validade do proprietário no ObjectsSecurityDescriptor resultante, conforme descrito em Comentários. Se o sinalizador SEF_AVOID_PRIVILEGE_CHECK também estiver definido, o parâmetro Token poderá ser NULL.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	O proprietário de ObjectsSecurityDescriptor usa como padrão o proprietário do pai do objeto. Se esse sinalizador não estiver definido, o proprietário de ObjectsSecurityDescriptor 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 ModificationDescriptor não for NULL, o proprietário objectsSecurityDescriptor será definido como o proprietário de ModificationDescriptor.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	O grupo de ObjectsSecurityDescriptor usa como padrão o grupo do proprietário do pai do objeto. Se esse sinalizador não estiver definido, o grupo de ObjectsSecurityDescriptor 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 ModificationDescriptor não for NULL, o grupo ObjectsSecurityDescriptor será definido como o grupo de ModificationDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Uma entidade de segurança com um nível obrigatório inferior ao do objeto não pode gravar no objeto.
SEF_MACL_NO_READ_UP 0x200	Uma entidade de segurança com um nível obrigatório inferior ao do objeto não pode ler o objeto.
SEF_MACL_NO_EXECUTE_UP 0x400	Uma entidade de segurança com um nível obrigatório inferior ao do objeto não pode executar o objeto.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Todas as restrições especificadas pelo proprietário do pai do objeto que limitariam a capacidade do chamador de especificar uma DACL no ObjectsSecurityDescriptor são ignoradas.

[in] GenericMapping

Um ponteiro para uma estrutura GENERIC_MAPPING que especifica os direitos de acesso específicos e padrão que correspondem a cada um dos direitos de acesso genéricos.

[in, optional] Token

Identifica o token de acesso para o cliente em cujo nome a segurança do objeto privado está sendo modificada. Esse parâmetro é necessário para garantir que o cliente tenha fornecido um valor legítimo para um novo SID ( identificador de segurança do proprietário). O token deve estar aberto para acesso TOKEN_QUERY.

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.

Comentários

Se o parâmetro AutoInheritFlags for zero, SetPrivateObjectSecurityEx será idêntico à função SetPrivateObjectSecurity .

Essa função destina-se apenas ao uso por gerenciadores de recursos. Para implementar a semântica de controle de acesso padrão do Windows para atualizar descritores de segurança, um gerenciador de recursos deve verificar se as seguintes condições foram atendidas antes de chamar SetPrivateObjectSecurityEx:

Se o proprietário do objeto estiver sendo definido, o processo de chamada deverá ter WRITE_OWNER permissão ou ser o proprietário do objeto.
Se a DACL do objeto estiver sendo definida, o processo de chamada deverá ter WRITE_DAC permissão ou ser o proprietário do objeto.
Se a SACL do objeto estiver sendo definida, o privilégio SE_SECURITY_NAME deverá ser habilitado para o processo de chamada.

Se as condições anteriores não forem atendidas, uma chamada para essa função não falhará, no entanto, a política de acesso padrão do Windows não será imposta.

O processo que chama essa função não deve representar um cliente porque os clientes normalmente não têm privilégios apropriados necessários para operações de token subjacentes.

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

Se o sinalizador SE_DACL_PROTECTED não estiver definido nos bits de controle do descritor de segurança atual ou do ModificationDescriptor, a função construirá o descritor de segurança de saída dos ACEs herdados do descritor de segurança atual e acEs não herdadas de ModificationDescriptor. Ou seja, é impossível alterar uma ACE herdada alterando a ACL ( lista de controle de acesso ) em um objeto . Esse comportamento preserva as ACEs herdadas, pois elas foram herdadas do contêiner pai.
Um editor de ACL deve tornar as ACEs herdadas indisponíveis para impedir que sejam modificadas.
Se SE_DACL_PROTECTED estiver definido em ModificationDescriptor, o descritor de segurança atual será ignorado. O descritor de segurança de saída é criado como uma cópia de ModificationDescriptor com qualquer INHERITED_ACE bits desativados.
Idealmente, um editor de ACL deve desativar os bits INHERITED_ACE que indicam ao chamador que os ACEs herdados do pai do objeto agora estão sendo definidos explicitamente no objeto.
Se SE_DACL_PROTECTED estiver definido no descritor de segurança atual e não em ModificationDescriptor, o descritor de segurança atual será ignorado. O descritor de segurança de saída é criado como uma cópia de ModificationDescriptor. É responsabilidade do chamador garantir que as ACEs corretas tenham o INHERITED_ACE bit ativado.

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 no ObjectsSecurityDescriptor de entrada e em ModificationDescriptor serão substituídos por duas ACEs no ObjectsSecurityDescriptor de saída. Especificamente, uma ACE herdável que contém pelo menos um dos seguintes elementos maplicativos resultará em dois ACEs na saída ObjectsSecurityDescriptor. Os elementos maplicativos incluem:

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

AcEs com qualquer um desses elementos mappable resultarão nos dois ACEs a seguir na saída ObjectsSecurityDescriptor:

Uma ACE que é uma cópia do original, mas com o sinalizador INHERIT_ONLY definido
Uma ACE na qual o INHERITED_ACE bit é ativado e os elementos genéricos são mapeados para elementos específicos:
- 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 SecurityDescriptor de saída
- O SID do Grupo do Criador é substituído pelo Grupo no SecurityDescriptor de saída

Se AutoInheritFlags não especificar o bit SEF_AVOID_PRIVILEGE_CHECK, a verificação de validade do proprietário será executada de acordo com as regras a seguir. O proprietário em ModificationDescriptor:

Deve ser um SID legalmente formado
Deve corresponder ao TokenUser no Token

Deve corresponder a um grupo no TokenGroups no Token em que os atributos no grupo:
- Incluir SE_GROUP_OWNER
- Incluir SE_GROUP_USE_FOR_DENY_ONLY

Um gerenciador de recursos que está definindo o Proprietário em uma subárvore de objetos pode evitar a sobrecarga da verificação de validade do proprietário redundante. Se o Proprietário em ModificationDescriptor e Token permanecer o mesmo para chamadas iterativas para essa função, o bit SEF_AVOID_PRIVILEGE_CHECK poderá ser definido em AutoInheritFlags para chamadas subsequentes a uma chamada inicial na qual a verificação de validade do proprietário é executada. Os chamadores que não têm acesso ao token do cliente que, por fim, definirão o proprietário também devem optar por ignorar a verificação de validação do proprietário.

Nota O bit SEF_AVOID_PRIVILEGE_CHECK usado na função SetPrivateObjectSecurityEx é equivalente ao bit SEF_AVOID_OWNER_CHECK usado na função CreatePrivateObjectSecurityEx .

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