Funzione SetPrivateObjectSecurityEx (securitybaseapi.h)

Articolo
08/25/2023

La funzione SetPrivateObjectSecurityEx modifica il descrittore di sicurezza di un oggetto privato gestito dal gestore risorse che chiama questa funzione. La funzione SetPrivateObjectSecurityEx ha un parametro flags che specifica se gestione risorse supporta l'ereditarietà automatica delle voci di controllo di accesso (AE).

Sintassi

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

Parametri

[in] SecurityInformation

Parti del descrittore di sicurezza da impostare. Questo valore può essere una combinazione dei flag di bit SECURITY_INFORMATION .

[in] ModificationDescriptor

Puntatore a una struttura SECURITY_DESCRIPTOR . Le parti di questo descrittore di sicurezza indicate dal parametro SecurityInformation vengono applicate al descrittore di sicurezza ObjectsSecurityDescriptor .

[in, out] ObjectsSecurityDescriptor

Puntatore a un puntatore a una struttura SECURITY_DESCRIPTOR . Questo descrittore di sicurezza deve essere in formato auto-relativo . La memoria per il descrittore di sicurezza deve essere allocata dall'heap del processo (GetProcessHeap) con la funzione HeapAlloc.

In input, questo è il descrittore di sicurezza corrente dell'oggetto privato. La funzione lo modifica per produrre il nuovo descrittore di sicurezza. Se necessario, la funzione SetPrivateObjectSecurityEx alloca memoria aggiuntiva per produrre un descrittore di sicurezza più grande.

[in] AutoInheritFlags

Specifica l'ereditarietà automatica degli ACL. Se il server protetto non implementa l'ereditarietà automatica, deve specificare zero; in caso contrario, può specificare una combinazione dei valori seguenti, definiti in Winnt.h.

Valore	Significato
SEF_DACL_AUTO_INHERIT 0x01	Il nuovo elenco di controllo di accesso discrezionale (DACL) contiene gli ACL ereditati dall'elenco DACL dell'elemento padre dell'oggetto, nonché gli ACL espliciti specificati nell'elenco DACL di ModificationDescriptor. Se questo flag non è impostato, il nuovo DACL non eredita gli ACL.
SEF_SACL_AUTO_INHERIT 0x02	Il nuovo elenco di controllo di accesso di sistema (SACL) contiene gli ACL ereditati dall'elenco SACL del descrittore di sicurezza associato all'elemento padre dell'oggetto, nonché gli ACL espliciti specificati nell'elenco SACL di ModificationDescriptor. Se questo flag non è impostato, il nuovo sacl non eredita gli ACL.
SEF_AVOID_PRIVILEGE_CHECK 0x08	La funzione non esegue il controllo dei privilegi. Se viene impostato anche il flag SEF_AVOID_OWNER_CHECK , il parametro Token può essere NULL. Usare questo flag quando si implementa l'ereditarietà automatica per evitare di controllare i privilegi per ogni elemento figlio aggiornato.
SEF_AVOID_OWNER_CHECK 0x10	La funzione non controlla la validità del proprietario nel risultante ObjectsSecurityDescriptor , come descritto in Osservazioni. Se viene impostato anche il flag SEF_AVOID_PRIVILEGE_CHECK , il parametro Token può essere NULL.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	Per impostazione predefinita, il proprietario di ObjectsSecurityDescriptor è il proprietario dell'elemento padre dell'oggetto. Se questo flag non è impostato, il proprietario di ObjectsSecurityDescriptor viene impostato per impostazione predefinita sul proprietario del token specificato dal parametro Token . Il proprietario del token viene specificato nel token stesso. In entrambi i casi, se il parametro ModificationDescriptor non è NULL, il proprietario di ObjectsSecurityDescriptor viene impostato sul proprietario da ModificationDescriptor.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	Il gruppo di ObjectsSecurityDescriptor viene predefinito per il gruppo dal proprietario dell'elemento padre dell'oggetto. Se questo flag non è impostato, il gruppo di ObjectsSecurityDescriptor viene impostato per impostazione predefinita sul gruppo del token specificato dal parametro Token . Il gruppo del token viene specificato nel token stesso. In entrambi i casi, se il parametro ModificationDescriptor non è NULL, il gruppo ObjectsSecurityDescriptor viene impostato sul gruppo da ModificationDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Un'entità con un livello obbligatorio inferiore a quello dell'oggetto non può scrivere nell'oggetto .
SEF_MACL_NO_READ_UP 0x200	Un'entità con un livello obbligatorio inferiore a quello dell'oggetto non può leggere l'oggetto.
SEF_MACL_NO_EXECUTE_UP 0x400	Un'entità con un livello obbligatorio inferiore a quello dell'oggetto non può eseguire l'oggetto .
SEF_AVOID_OWNER_RESTRICTION 0x1000	Eventuali restrizioni specificate dal proprietario dell'elemento padre dell'oggetto che limitano la capacità del chiamante di specificare un DACL in ObjectsSecurityDescriptor vengono ignorate .

[in] GenericMapping

Puntatore a una struttura di GENERIC_MAPPING che specifica i diritti di accesso specifici e standard corrispondenti a ognuno dei diritti di accesso generici.

[in, optional] Token

Identifica il token di accesso per il client per cui viene modificata la sicurezza dell'oggetto privato. Questo parametro è necessario per garantire che il client abbia fornito un valore legittimo per un nuovo IDENTIFICATORe di sicurezza del proprietario (SID). Il token deve essere aperto per l'accesso TOKEN_QUERY.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.

Se la funzione ha esito negativo, restituisce zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Se il parametro AutoInheritFlags è zero, SetPrivateObjectSecurityEx è identico alla funzione SetPrivateObjectSecurity .

Questa funzione è destinata all'uso solo da parte dei gestori di risorse. Per implementare la semantica di controllo di accesso di Windows standard per l'aggiornamento dei descrittori di sicurezza, un gestore di risorse deve verificare che le condizioni seguenti vengano soddisfatte prima di chiamare SetPrivateObjectSecurityEx:

Se il proprietario dell'oggetto è impostato, il processo chiamante deve disporre dell'autorizzazione WRITE_OWNER o essere il proprietario dell'oggetto.
Se l'elenco DACL dell'oggetto è impostato, il processo chiamante deve disporre dell'autorizzazione WRITE_DAC o essere il proprietario dell'oggetto.
Se l'oggetto SACL è impostato, è necessario abilitare il privilegio SE_SECURITY_NAME per il processo chiamante.

Se le condizioni precedenti non vengono soddisfatte, una chiamata a questa funzione non ha esito negativo, ma i criteri di accesso standard di Windows non vengono applicati.

Il processo che chiama questa funzione non deve rappresentare un client perché i client in genere non dispongono dei privilegi appropriati necessari per le operazioni di token sottostanti.

Se AutoInheritFlags specifica il bit SEF_DACL_AUTO_INHERIT, la funzione applica le regole seguenti all'elenco DACL per creare il nuovo descrittore di sicurezza dal descrittore corrente:

Se il flag di SE_DACL_PROTECTED non è impostato nei bit di controllo del descrittore di sicurezza corrente o nel descrittore di modificaDescriptor, la funzione costruisce il descrittore di sicurezza di output dagli ACL ereditati del descrittore di sicurezza corrente e degli ACL non crittografati di ModificationDescriptor. Ciò significa che è impossibile modificare un ace ereditato modificando l'elenco di controllo di accesso (ACL) in un oggetto . Questo comportamento mantiene gli ACL ereditati perché sono stati ereditati dal contenitore padre.
Un editor ACL deve rendere gli ACL ereditati non disponibili per impedirne la modifica.
Se SE_DACL_PROTECTED è impostato in ModificationDescriptor, il descrittore di sicurezza corrente viene ignorato. Il descrittore di sicurezza di output viene compilato come copia di ModificationDescriptor con qualsiasi bit INHERITED_ACE disattivato.
Idealmente, un editor ACL deve disattivare i bit INHERITED_ACE che indicano al chiamante che gli ACL ereditati dall'oggetto padre dell'oggetto vengono ora impostati in modo esplicito sull'oggetto.
Se SE_DACL_PROTECTED è impostato nel descrittore di sicurezza corrente e non in ModificationDescriptor, il descrittore di sicurezza corrente viene ignorato. Il descrittore di sicurezza di output viene compilato come copia di ModificationDescriptor. È responsabilità del chiamante assicurarsi che gli ACL corretti abbiano il bit di INHERITED_ACE attivato.

Se AutoInheritFlags specifica il bit SEF_SACL_AUTO_INHERIT, la funzione applica regole simili al nuovo SACL.

Per entrambi i dacl e sacche, determinati tipi di ACL nell'input ObjectsSecurityDescriptor e in ModificationDescriptor verranno sostituiti da due ACL nell'output ObjectsSecurityDescriptor. In particolare, un ace ereditabile che contiene almeno uno degli elementi mappabili seguenti comporterà due ACL nell'output ObjectsSecurityDescriptor. Gli elementi mappabili includono:

Diritti di accesso generico nella struttura di ACCESS_MASK
SID proprietario creatore o SID del gruppo creatore come identificatore del soggetto ACE

Gli ACL con uno di questi elementi mappabili genereranno i due ACL seguenti nell'output ObjectsSecurityDescriptor:

Ace che è una copia dell'originale, ma con il flag INHERIT_ONLY impostato
Ace in cui è attivato il bit INHERITED_ACE e gli elementi generici vengono mappati a elementi specifici:
- I diritti di accesso generico vengono sostituiti dai diritti di accesso standard e specifici corrispondenti indicati nell'input GenericMapping.
- Il SID proprietario di Creator viene sostituito con il proprietario nell'output SecurityDescriptor
- Il SID del gruppo creatore viene sostituito con il gruppo nell'output SecurityDescriptor

Se AutoInheritFlags non specifica il bit di SEF_AVOID_PRIVILEGE_CHECK, il controllo di validità del proprietario viene eseguito in base alle regole seguenti. Proprietario in ModificationDescriptor:

Deve essere un SID formato legalmente
Deve corrispondere a TokenUser nel token

Oppure

Deve corrispondere a un gruppo nei TokenGroup in Token in cui gli attributi del gruppo:
- Includere SE_GROUP_OWNER
- Includere SE_GROUP_USE_FOR_DENY_ONLY

Gestione risorse che imposta il proprietario su un sottoalbero di oggetti può evitare il sovraccarico del controllo di validità del proprietario ridondante. Se il proprietario in ChangeDescriptor e token rimangono invariati per le chiamate iterative a questa funzione, il bit di SEF_AVOID_PRIVILEGE_CHECK può essere impostato in AutoInheritFlags per le chiamate successive a una chiamata iniziale in cui viene eseguito il controllo di validità del proprietario. I chiamanti che non hanno accesso al token del client che in definitiva impostano il proprietario devono scegliere anche di ignorare il controllo della convalida del proprietario.

Nota Il bit di SEF_AVOID_PRIVILEGE_CHECK usato nella funzione SetPrivateObjectSecurityEx equivale al bit SEF_AVOID_OWNER_CHECK usato nella funzione CreatePrivateObjectSecurityEx .

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll