Fonction SetPrivateObjectSecurityEx (securitybaseapi.h)

Article
03/04/2024

La fonction SetPrivateObjectSecurityEx modifie le descripteur de sécurité d’un objet privé géré par le gestionnaire de ressources appelant cette fonction. La fonction SetPrivateObjectSecurityEx a un paramètre flags qui spécifie si le gestionnaire de ressources prend en charge l’héritage automatique des entrées de contrôle d’accès (ACE).

Syntaxe

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

Paramètres

[in] SecurityInformation

Parties du descripteur de sécurité à définir. Cette valeur peut être une combinaison des indicateurs de bits SECURITY_INFORMATION .

[in] ModificationDescriptor

Pointeur vers une structure SECURITY_DESCRIPTOR . Les parties de ce descripteur de sécurité indiquées par le paramètre SecurityInformation sont appliquées au descripteur de sécurité ObjectsSecurityDescriptor .

[in, out] ObjectsSecurityDescriptor

Pointeur vers un pointeur vers une structure SECURITY_DESCRIPTOR . Ce descripteur de sécurité doit être auto-relatif . La mémoire du descripteur de sécurité doit être allouée à partir du tas de processus (GetProcessHeap) avec la fonction HeapAlloc.

En entrée, il s’agit du descripteur de sécurité actuel de l’objet privé. La fonction le modifie pour produire le nouveau descripteur de sécurité. Si nécessaire, la fonction SetPrivateObjectSecurityEx alloue de la mémoire supplémentaire pour produire un descripteur de sécurité plus volumineux.

[in] AutoInheritFlags

Spécifie l’héritage automatique des AE. Si le serveur protégé n’implémente pas l’héritage automatique, il doit spécifier zéro ; sinon, il peut spécifier une combinaison des valeurs suivantes, définies dans Winnt.h.

Valeur	Signification
SEF_DACL_AUTO_INHERIT 0x01	La nouvelle liste de contrôle d’accès discrétionnaire (DACL) contient des ACÉ hérités du DACL du parent de l’objet, ainsi que tous les ACÉ explicites spécifiés dans le DACL de ModificationDescriptor. Si cet indicateur n’est pas défini, la nouvelle liste de contrôle d’accès n’hérite pas d’ACA.
SEF_SACL_AUTO_INHERIT 0x02	La nouvelle liste de contrôle d’accès système (SACL) contient des AÉC héritées de la saCL du descripteur de sécurité associé au parent de l’objet, ainsi que tous les AIC explicites spécifiés dans la liste SACL de ModificationDescriptor. Si cet indicateur n’est pas défini, la nouvelle liste SACL n’hérite pas des ACA.
SEF_AVOID_PRIVILEGE_CHECK 0x08	La fonction n’effectue pas de vérification des privilèges. Si l’indicateur SEF_AVOID_OWNER_CHECK est également défini, le paramètre Token peut avoir la valeur NULL. Utilisez cet indicateur lors de l’implémentation de l’héritage automatique pour éviter de vérifier les privilèges sur chaque enfant mis à jour.
SEF_AVOID_OWNER_CHECK 0x10	La fonction ne case activée pas la validité du propriétaire dans l’objet ObjectsSecurityDescriptor résultant, comme décrit dans Remarques. Si l’indicateur SEF_AVOID_PRIVILEGE_CHECK est également défini, le paramètre Token peut avoir la valeur NULL.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	Le propriétaire de ObjectsSecurityDescriptor est par défaut le propriétaire du parent de l’objet. Si cet indicateur n’est pas défini, le propriétaire d’ObjectsSecurityDescriptor est par défaut le propriétaire du jeton spécifié par le paramètre Token . Le propriétaire du jeton est spécifié dans le jeton lui-même. Dans les deux cas, si le paramètre ModificationDescriptor n’est pas NULL, le propriétaire ObjectsSecurityDescriptor est défini sur le propriétaire à partir de ModificationDescriptor.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	Le groupe de ObjectsSecurityDescriptor est défini par défaut sur le groupe du propriétaire du parent de l’objet. Si cet indicateur n’est pas défini, le groupe de ObjectsSecurityDescriptor est défini par défaut sur le groupe du jeton spécifié par le paramètre Token . Le groupe du jeton est spécifié dans le jeton lui-même. Dans les deux cas, si le paramètre ModificationDescriptor n’est pas NULL, le groupe ObjectsSecurityDescriptor est défini sur le groupe à partir de ModificationDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Un principal dont le niveau obligatoire est inférieur à celui de l’objet ne peut pas écrire dans l’objet.
SEF_MACL_NO_READ_UP 0x200	Un principal dont le niveau obligatoire est inférieur à celui de l’objet ne peut pas lire l’objet.
SEF_MACL_NO_EXECUTE_UP 0x400	Un principal dont le niveau obligatoire est inférieur à celui de l’objet ne peut pas exécuter l’objet.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Toutes les restrictions spécifiées par le propriétaire du parent de l’objet qui limiteraient la capacité de l’appelant à spécifier une liste de contrôle d’accès (DACL) dans l’objet ObjectsSecurityDescriptor sont ignorées.

[in] GenericMapping

Pointeur vers une structure GENERIC_MAPPING qui spécifie les droits d’accès spécifiques et standard qui correspondent à chacun des droits d’accès génériques.

[in, optional] Token

Identifie le jeton d’accès pour le client pour lequel la sécurité de l’objet privé est en cours de modification. Ce paramètre est requis pour vérifier que le client a fourni une valeur légitime pour un nouvel identificateur de sécurité de propriétaire (SID). Le jeton doit être ouvert pour TOKEN_QUERY accès.

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Si le paramètre AutoInheritFlags est égal à zéro, SetPrivateObjectSecurityEx est identique à la fonction SetPrivateObjectSecurity .

Cette fonction est destinée uniquement aux gestionnaires de ressources. Pour implémenter la sémantique de contrôle d’accès Windows standard pour la mise à jour des descripteurs de sécurité, un gestionnaire de ressources doit vérifier que les conditions suivantes sont remplies avant d’appeler SetPrivateObjectSecurityEx :

Si le propriétaire de l’objet est défini, le processus appelant doit avoir l’autorisation WRITE_OWNER ou être le propriétaire de l’objet.
Si la liste DACL de l’objet est définie, le processus appelant doit avoir WRITE_DAC autorisation ou être le propriétaire de l’objet.
Si la liste SACL de l’objet est définie, le privilège SE_SECURITY_NAME doit être activé pour le processus d’appel.

Si les conditions précédentes ne sont pas remplies, un appel à cette fonction n’échoue pas. Toutefois, la stratégie d’accès Windows standard n’est pas appliquée.

Le processus appelant cette fonction ne doit pas emprunter l’identité d’un client, car les clients ne disposent généralement pas des privilèges appropriés requis pour les opérations de jeton sous-jacentes.

Si AutoInheritFlags spécifie le bit SEF_DACL_AUTO_INHERIT, la fonction applique les règles suivantes à la liste de contrôle d’accès automatique pour créer le nouveau descripteur de sécurité à partir du descripteur actuel :

Si l’indicateur de SE_DACL_PROTECTED n’est pas défini dans les bits de contrôle du descripteur de sécurité actuel ou de l’indicateur ModificationDescriptor, la fonction construit le descripteur de sécurité de sortie à partir des ACÉ hérités du descripteur de sécurité actuel et des éléments D’AÉC nonhéridés de ModificationDescriptor. Autrement dit, il est impossible de modifier un ACE hérité en modifiant la liste de contrôle d’accès (ACL) sur un objet. Ce comportement conserve les AE hérités, car ils ont été hérités du conteneur parent.
Un éditeur de listes de contrôle d’accès doit rendre les AIC hérités indisponibles pour empêcher leur modification.
Si SE_DACL_PROTECTED est défini dans ModificationDescriptor, le descripteur de sécurité actuel est ignoré. Le descripteur de sécurité de sortie est généré en tant que copie de ModificationDescriptor avec tous les bits INHERITED_ACE désactivés.
Dans l’idéal, un éditeur ACL doit désactiver les bits INHERITED_ACE qui indiquent à son appelant que les AIC hérités du parent de l’objet sont désormais définis explicitement sur l’objet.
Si SE_DACL_PROTECTED est défini dans le descripteur de sécurité actuel et non dans ModificationDescriptor, le descripteur de sécurité actuel est ignoré. Le descripteur de sécurité de sortie est généré en tant que copie de ModificationDescriptor. Il incombe à l’appelant de s’assurer que les AE appropriés ont le INHERITED_ACE bit activé.

Si AutoInheritFlags spécifie le SEF_SACL_AUTO_INHERIT bit, la fonction applique des règles similaires à la nouvelle liste SACL.

Pour les DACLs et les SACL, certains types d’ACÉ dans l’entrée ObjectsSecurityDescriptor et dans ModificationDescriptor seront remplacés par deux ACÉ dans la sortie ObjectsSecurityDescriptor. Plus précisément, un ACE pouvant être hérité qui contient au moins un des éléments mappables suivants aboutira à deux AE dans la sortie ObjectsSecurityDescriptor. Les éléments Mappable sont les suivants :

Droits d’accès génériques dans la structure ACCESS_MASK
SID propriétaire du créateur ou SID du groupe de créateurs en tant qu’identificateur d’objet ACE

Les ACÉ avec l’un de ces éléments mappables entraînent les deux ACÉ suivants dans la sortie ObjectsSecurityDescriptor :

Ace qui est une copie de l’original, mais avec l’indicateur INHERIT_ONLY défini
Ace dans lequel le bit INHERITED_ACE est activé et les éléments génériques sont mappés à des éléments spécifiques :
- Les droits d’accès génériques sont remplacés par les droits d’accès standard et spécifiques correspondants indiqués dans l’entrée GenericMapping.
- Le SID du propriétaire du créateur est remplacé par le propriétaire dans le SecurityDescriptor de sortie
- Creator Group SID est remplacé par le groupe dans le SecurityDescriptor de sortie

Si AutoInheritFlags ne spécifie pas le bit SEF_AVOID_PRIVILEGE_CHECK, la vérification de la validité du propriétaire est effectuée conformément aux règles suivantes. Propriétaire dans ModificationDescriptor :

Doit être un SID légalement formé
Doit correspondre à TokenUser dans Token

Doit correspondre à un groupe dans TokenGroups dans Token où les attributs sur le groupe :
- Inclure SE_GROUP_OWNER
- Inclure SE_GROUP_USE_FOR_DENY_ONLY

Un gestionnaire de ressources qui configure le propriétaire sur une sous-arborescence d’objets peut éviter la surcharge liée à la vérification de la validité du propriétaire redondant. Si le propriétaire dans ModificationDescriptor et le jeton restent identiques pour les appels itératifs à cette fonction, le bit SEF_AVOID_PRIVILEGE_CHECK peut être défini dans AutoInheritFlags pour les appels postérieurs à un appel initial dans lequel la vérification de la validité du propriétaire est effectuée. Les appelants qui n’ont pas accès au jeton du client qui définira finalement le propriétaire doivent également choisir d’ignorer la vérification de la validation du propriétaire.

Note Le bit SEF_AVOID_PRIVILEGE_CHECK utilisé dans la fonction SetPrivateObjectSecurityEx équivaut au bit SEF_AVOID_OWNER_CHECK utilisé dans la fonction CreatePrivateObjectSecurityEx .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	securitybaseapi.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll