BuildSecurityDescriptorA, fonction (aclapi.h)

Article
08/22/2023

La fonction BuildSecurityDescriptor alloue et initialise un nouveau descripteur de sécurité. Cette fonction peut initialiser le nouveau descripteur de sécurité en fusionnant les informations de sécurité spécifiées avec les informations d’un descripteur de sécurité existant. Si vous ne spécifiez pas de descripteur de sécurité existant, la fonction initialise un nouveau descripteur de sécurité en fonction des informations de sécurité spécifiées.

La fonction BuildSecurityDescriptor crée un descripteur de sécurité auto-relatif. Le format auto-relatif rend le descripteur de sécurité approprié pour le stockage dans un flux.

Syntaxe

DWORD BuildSecurityDescriptorA(
  [in, optional] PTRUSTEE_A           pOwner,
  [in, optional] PTRUSTEE_A           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

Paramètres

[in, optional] pOwner

Pointeur vers une structure TRUSTEE qui identifie le propriétaire du nouveau descripteur de sécurité. Si la structure utilise le formulaire TRUSTEE_IS_NAME, BuildSecurityDescriptor recherche l’identificateur de sécurité (SID) associé au nom d’administrateur spécifié.

Si ce paramètre a la valeur NULL, la fonction utilise le SID propriétaire du descripteur de sécurité d’origine pointé par pOldSD. Si pOldSD a la valeur NULL ou si le SID propriétaire dans pOldSD est NULL, le SID de propriétaire est NULL dans le nouveau descripteur de sécurité.

[in, optional] pGroup

Pointeur vers une structure TRUSTEE qui identifie le SID de groupe principal pour le nouveau descripteur de sécurité. Si la structure utilise le formulaire TRUSTEE_IS_NAME, BuildSecurityDescriptor recherche le SID associé au nom d’administrateur spécifié.

Si ce paramètre a la valeur NULL, la fonction utilise le SID de groupe du descripteur de sécurité d’origine pointé par pOldSD. Si pOldSD a la valeur NULL ou si le SID de groupe dans pOldSD est NULL, le SID de groupe est NULL dans le nouveau descripteur de sécurité.

[in] cCountOfAccessEntries

Nombre de structures EXPLICIT_ACCESS dans le tableau pListOfAccessEntries .

[in, optional] pListOfAccessEntries

Pointeur vers un tableau de structures EXPLICIT_ACCESS qui décrivent les informations de contrôle d’accès pour la liste de contrôle d’accès discrétionnaire (DACL) du nouveau descripteur de sécurité. La fonction crée le nouveau DACL en fusionnant les informations du tableau avec la liste DACL dans pOldSD, le cas échéant. Si pOldSD a la valeur NULL ou si la liste dacl dans pOldSD a la valeur NULL, la fonction crée une liste DACL basée uniquement sur les informations du tableau. Pour obtenir une description des règles de création d’une liste de contrôle d’accès à partir d’un tableau de structures EXPLICIT_ACCESS , consultez la fonction SetEntriesInAcl .

Si pListOfAccessEntries a la valeur NULL, le nouveau descripteur de sécurité obtient le DACL de pOldSD. Dans ce cas, si pOldSD a la valeur NULL ou si la liste dacl dans pOldSD a la valeur NULL, la nouvelle liste DACL est NULL.

[in] cCountOfAuditEntries

Nombre de structures EXPLICIT_ACCESS dans le tableau pListOfAuditEntries .

[in, optional] pListOfAuditEntries

Pointeur vers un tableau de structures EXPLICIT_ACCESS qui décrivent les informations de contrôle d’audit pour la SACL du nouveau descripteur de sécurité. La fonction crée la nouvelle SACL en fusionnant les informations du tableau avec la SACL dans pOldSD, le cas échéant. Si pOldSD a la valeur NULL ou si la liste SACL dans pOldSD a la valeur NULL, la fonction crée une nouvelle liste SACL basée uniquement sur les informations contenues dans le tableau.

Si pListOfAuditEntries a la valeur NULL, le nouveau descripteur de sécurité obtient la SACL de pOldSD. Dans ce cas, si pOldSD a la valeur NULL ou si la liste SACL dans pOldSD a la valeur NULL, la nouvelle SACL est NULL.

[in, optional] pOldSD

Pointeur vers une structure de SECURITY_DESCRIPTOR auto-relative existante et ses informations de sécurité associées. La fonction génère le nouveau descripteur de sécurité en fusionnant les informations de propriétaire, de groupe, de contrôle d’accès et de contrôle d’audit spécifiées avec les informations de ce descripteur de sécurité. Ce paramètre peut être NULL.

[out] pSizeNewSD

Pointeur vers une variable qui reçoit la taille, en octets, du descripteur de sécurité.

[out] pNewSD

Pointeur vers une variable qui reçoit un pointeur vers le nouveau descripteur de sécurité. La fonction alloue de la mémoire pour le nouveau descripteur de sécurité. Vous devez appeler la fonction LocalFree pour libérer la mémoire tampon retournée.

Valeur retournée

Si la fonction réussit, la fonction retourne ERROR_SUCCESS.

Si la fonction échoue, elle retourne un code d’erreur différent de zéro défini dans WinError.h.

Remarques

La fonction BuildSecurityDescriptor est destinée aux serveurs approuvés qui implémentent ou exposent la sécurité sur leurs propres objets. La fonction utilise des descripteurs de sécurité auto-relatifs adaptés à la sérialisation dans un flux et au stockage sur disque, comme un serveur approuvé peut l’exiger.

Notes

L’en-tête aclapi.h définit BuildSecurityDescriptor en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

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	aclapi.h
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll