Funzione CreatePrivateObjectSecurityEx (securitybaseapi.h)

Articolo
03/01/2024

La funzione CreatePrivateObjectSecurityEx alloca e inizializza un descrittore di sicurezza self-relative per un nuovo oggetto privato creato da Resource Manager chiamando questa funzione.

Sintassi

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

Parametri

[in, optional] ParentDescriptor

Puntatore al descrittore di sicurezza per il contenitore padre dell'oggetto. Se non esiste alcun contenitore padre, questo parametro è NULL.

[in, optional] CreatorDescriptor

Puntatore a un descrittore di sicurezza fornito dall'autore dell'oggetto. Se l'autore dell'oggetto non passa in modo esplicito informazioni di sicurezza per il nuovo oggetto, questo parametro può essere NULL. In alternativa, questo parametro può puntare a un descrittore di sicurezza predefinito.

[out] NewDescriptor

Puntatore a una variabile che riceve un puntatore al descrittore di sicurezza auto-relativo appena allocato. Al termine dell'uso del descrittore di sicurezza, liberarlo chiamando il
Funzione DestroyPrivateObjectSecurity .

[in, optional] ObjectType

Puntatore a una struttura GUID che identifica il tipo di oggetto associato a NewDescriptor. Se l'oggetto non ha un GUID, impostare ObjectType su NULL.

[in] IsContainerObject

Specifica se il nuovo oggetto può contenere altri oggetti. Un valore true indica che il nuovo oggetto è un contenitore. Un valore false indica che il nuovo oggetto non è un contenitore.

[in] AutoInheritFlags

Set di flag di bit che controllano il modo in cui le voci di controllo di accesso vengono ereditate da ParentDescriptor. Questo parametro può essere una combinazione dei valori seguenti.

Valore	Significato
SEF_AVOID_OWNER_CHECK 0x10	La funzione non controlla la validità del proprietario nel newDescriptor risultante , come descritto in Osservazioni di seguito. Se il flag SEF_AVOID_PRIVILEGE_CHECK è impostato anche, il parametro Token può essere NULL.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Tutte le restrizioni specificate dal parentDescriptor che limitano la capacità del chiamante di specificare un'elenco dati nel CreatorDescriptor vengono ignorate .
SEF_AVOID_PRIVILEGE_CHECK 0x08	La funzione non esegue il controllo dei privilegi. Se il flag SEF_AVOID_OWNER_CHECK è impostato anche, il parametro Token può essere NULL. Questo flag è utile durante l'implementazione dell'ereditarietà automatica per evitare il controllo dei privilegi in ogni elemento figlio aggiornato.
SEF_DACL_AUTO_INHERIT 0x01	Il nuovo elenco di controllo di accesso discrezionale (DACL) contiene gli ACL ereditati dall'elenco DACL di ParentDescriptor, nonché gli ACL espliciti specificati nell'elenco DACL di CreatorDescriptor. Se questo flag non è impostato, il nuovo daCL non eredita aces.
SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT 0x04	CreatorDescriptor è il descrittore predefinito per il tipo di oggetto specificato da ObjectType. Di conseguenza, CreatorDescriptor viene ignorato se ParentDescriptor ha ACL specifici dell'oggetto per il tipo di oggetto specificato dal parametro ObjectType . Se non vengono ereditati tali ACL, CreatorDescriptor viene gestito come se questo flag non fosse specificato.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	Il gruppo di NewDescriptor è predefinito per il gruppo da ParentDescriptor. Se non è impostato, il gruppo di NewDescriptor è predefinito per il gruppo del token specificato dal parametro Token . Il gruppo del token viene specificato nel token stesso. In entrambi i casi, se il parametro CreatorDescriptor non è NULL, il gruppo NewDescriptor è impostato sul gruppo da CreatorDescriptor.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	Il proprietario di NewDescriptor è predefinito al proprietario da ParentDescriptor. In caso contrario, il proprietario di NewDescriptor viene predefinito al proprietario del token specificato dal parametro Token . Il proprietario del token viene specificato nel token stesso. In entrambi i casi, se il parametro CreatorDescriptor non è NULL, il proprietario di NewDescriptor è impostato sul proprietario da CreatorDescriptor.
SEF_MACL_NO_EXECUTE_UP 0x400	Quando questo flag è impostato, l'etichetta obbligatoria ACE in CreatorDescriptor non viene usata per creare un'etichetta obbligatoria ACE in NewDescriptor. Al contrario, viene aggiunta una nuova SYSTEM_MANDATORY_LABEL_ACE con una maschera di accesso di SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP e il SID dal SID dell'integrità del token viene aggiunto a NewDescriptor.
SEF_MACL_NO_READ_UP 0x200	Quando questo flag è impostato, l'etichetta obbligatoria ACE in CreatorDescriptor non viene usata per creare un'etichetta obbligatoria ACE in NewDescriptor. Al contrario, viene aggiunta una nuova SYSTEM_MANDATORY_LABEL_ACE con una maschera di accesso di SYSTEM_MANDATORY_LABEL_NO_READ_UP e il SID dal SID dell'integrità del token viene aggiunto a NewDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Quando questo flag è impostato, l'etichetta obbligatoria ACE in CreatorDescriptor non viene usata per creare un'etichetta obbligatoria ACE in NewDescriptor. Al contrario, viene aggiunta una nuova SYSTEM_MANDATORY_LABEL_ACE con una maschera di accesso di SYSTEM_MANDATORY_LABEL_NO_WRITE_UP e il SID dal SID dell'integrità del token viene aggiunto a NewDescriptor.
SEF_SACL_AUTO_INHERIT 0x02	Il nuovo elenco di controllo di accesso al sistema (SACL) contiene aces ereditati dal SACL di ParentDescriptor, nonché eventuali ACL espliciti specificati nel SACL di CreatorDescriptor. Se questo flag non è impostato, il nuovo SACL non eredita ACEs.

[in, optional] Token

Handle per il token di accesso per il processo client per il cui conto viene creato l'oggetto. Se si tratta di un token di rappresentazione, deve essere a livello di SecurityIdentification o superiore. Per una descrizione completa del livello di rappresentazione di SecurityIdentification, vedere il tipo enumerato SECURITY_IMPERSONATION_LEVEL .

Il token client contiene informazioni di sicurezza predefinite, ad esempio il proprietario predefinito, il gruppo primario e l'elenco dati. La funzione usa queste impostazioni predefinite se le informazioni non sono presenti nei descrittori di sicurezza di input. Il token deve essere aperto per l'accesso TOKEN_QUERY .

Se tutte le condizioni seguenti sono vere, l'handle deve essere aperto per l'accesso TOKEN_DUPLICATE oltre all'accesso TOKEN_QUERY.

L'handle del token fa riferimento a un token primario.
Il descrittore di sicurezza del token contiene uno o più ACL con il SID OwnerRights .
Per il parametro CreatorDescriptor viene specificato un descrittore di sicurezza.
Il chiamante di questa funzione non imposta il flag di SEF_AVOID_OWNER_RESTRICTION nel parametro AutoInheritFlags .

[in] GenericMapping

Puntatore a una struttura GENERIC_MAPPING che specifica il mapping da ogni diritto generico a diritti specifici per l'oggetto.

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. Alcuni codici di errore estesi e i relativi significati sono elencati nella tabella seguente.

Codice restituito	Descrizione
ERROR_INVALID_OWNER	La funzione non può recuperare un proprietario per il nuovo descrittore di sicurezza o il SID non può essere assegnato come proprietario. Ciò si verifica quando si convalida il SID del proprietario con il token passato.
ERROR_INVALID_PRIMARY_GROUP	La funzione non può recuperare un gruppo primario per il nuovo descrittore di sicurezza.
ERROR_NO_TOKEN	La funzione ha ricevuto NULL anziché un token per la convalida o il controllo dei privilegi del proprietario.
ERROR_PRIVILEGE_NOT_HELD	È in corso l'impostazione di un oggetto SACL, SEF_AVOID_PRIVILEGE_CHECK non è stato passato e il token passato non ha SE_SECURITY_NAME abilitato.

Commenti

La funzione CreatePrivateObjectSecurity è identica alla chiamata della funzione CreatePrivateObjectSecurityEx con ObjectType impostato su NULL e AutoInheritFlags impostato su zero.

Il parametro AutoInheritFlags è diverso dai bit denominati in modo analogo nel membro Control della struttura SECURITY_DESCRIPTOR . Per una spiegazione dei bit del controllo, vedere SECURITY_DESCRIPTOR_CONTROL.

Se AutoInheritFlags specifica il bit SEF_DACL_AUTO_INHERIT, la funzione applica le regole seguenti all'elenco di controllo di accesso alla riga di controllo di accesso nel nuovo descrittore di sicurezza:

Il flag SE_DACL_AUTO_INHERITED viene impostato nel membro Control del nuovo descrittore di sicurezza.
Il DACL del nuovo descrittore di sicurezza eredita gli ACL dal ParentDescriptor indipendentemente dal fatto che CreatorDescriptor sia il descrittore di sicurezza predefinito o sia stato specificato in modo esplicito dall'autore. Il nuovo DACL è una combinazione di DACL padre e creatore, come definito dalle regole di ereditarietà.
Gli ACL ereditati vengono contrassegnati come INHERITED_ACE.

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 in ParentDescriptor e CreatorDescriptor verranno modificati ed eventualmente sostituiti da due ACL in NewDescriptor. In particolare, un ace ereditabile che contiene almeno uno dei seguenti elementi mappabili può comportare due ACL nel descrittore di sicurezza di output. Gli elementi mappabili includono:

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

Gli ACL con uno degli elementi mappabili menzionati in precedenza genereranno gli ACL seguenti in NewDescriptor:

Ace che è una copia dell'originale, ma con il flag INHERIT_ONLY impostato. Tuttavia, questa ace non verrà creata se esistono una delle due condizioni seguenti:
- Il parametro IsContainerObject è FALSE. Gli ACL ereditabili sono senza significato per gli oggetti non contenitore.
- L'ace originale contiene il flag di NO_PROPAGATE_INHERIT. L'ACE originale deve essere ereditato come ace efficace per gli elementi figlio, ma non ereditabili sotto tali elementi figlio.
Ace efficace in cui viene attivato il bit INHERITED_ACE e gli elementi generici vengono mappati a elementi specifici, tra cui:
- I diritti di accesso generico vengono sostituiti dai diritti di accesso standard e specifici corrispondenti indicati nell'input GenericMapping.
- Il SID proprietario del creatore viene sostituito con il proprietario nel newDescriptor risultante
- Il SID del gruppo creatore viene sostituito con il gruppo nel newDescriptor risultante

Se AutoInheritFlags non specifica il bit SEF_AVOID_OWNER_CHECK, viene eseguito il controllo della validità del proprietario. Il proprietario nel NewDescriptor risultante deve essere un SID formato legalmente e deve corrispondere a TokenUser in Token o deve corrispondere a un gruppo nei TokenGroup in Token in cui gli attributi del gruppo devono includere SE_GROUP_OWNER e non devono includere SE_GROUP_USE_FOR_DENY_ONLY.

I chiamanti che non hanno accesso al token del client che in ultima analisi impostano il proprietario possono scegliere di ignorare il controllo della convalida del proprietario.

Per creare un descrittore di sicurezza per un nuovo oggetto, chiamare CreatePrivateObjectSecurityEx con ParentDescriptor impostato sul descrittore di sicurezza del contenitore padre e creatorDescriptor impostato sul descrittore di sicurezza proposto dall'autore dell'oggetto.

Se il descrittore di sicurezza CreatorDescriptor contiene un sacl, il token deve avere il privilegio SE_SECURITY_NAME abilitato oppure il chiamante deve specificare il flag SEF_AVOID_PRIVILEGE_CHECK in AutoInheritFlags.

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