GetNamedSecurityInfoA, fonction (aclapi.h)

Article
02/26/2024

La fonction GetNamedSecurityInfo récupère une copie du descripteur de sécurité pour un objet spécifié par le nom.

Syntaxe

DWORD GetNamedSecurityInfoA(
  [in]            LPCSTR               pObjectName,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Paramètres

[in] pObjectName

Pointeur vers une chaîne terminée par un caractère Null qui spécifie le nom de l’objet à partir duquel récupérer des informations de sécurité. Pour obtenir des descriptions des formats de chaîne pour les différents types d’objets, consultez SE_OBJECT_TYPE.

[in] ObjectType

Spécifie une valeur de l’énumération SE_OBJECT_TYPE qui indique le type d’objet nommé par le paramètre pObjectName .

[in] SecurityInfo

Ensemble d’indicateurs de bits qui indiquent le type d’informations de sécurité à récupérer. Ce paramètre peut être une combinaison des indicateurs de bits SECURITY_INFORMATION .

[out, optional] ppsidOwner

Pointeur vers une variable qui reçoit un pointeur vers le SID propriétaire dans le descripteur de sécurité retourné dans ppSecurityDescriptor ou NULL si le descripteur de sécurité n’a pas de SID de propriétaire. Le pointeur retourné est valide uniquement si vous définissez l’indicateur OWNER_SECURITY_INFORMATION. En outre, ce paramètre peut être NULL si vous n’avez pas besoin du SID du propriétaire.

[out, optional] ppsidGroup

Pointeur vers une variable qui reçoit un pointeur vers le SID du groupe principal dans le descripteur de sécurité retourné ou NULL si le descripteur de sécurité n’a pas de SID de groupe. Le pointeur retourné est valide uniquement si vous définissez l’indicateur GROUP_SECURITY_INFORMATION. En outre, ce paramètre peut être NULL si vous n’avez pas besoin du SID de groupe.

[out, optional] ppDacl

Pointeur vers une variable qui reçoit un pointeur vers le DACL dans le descripteur de sécurité retourné ou NULL si le descripteur de sécurité n’a pas de DACL. Le pointeur retourné est valide uniquement si vous définissez l’indicateur DACL_SECURITY_INFORMATION. En outre, ce paramètre peut être NULL si vous n’avez pas besoin de la liste DACL.

[out, optional] ppSacl

Pointeur vers une variable qui reçoit un pointeur vers la SACL dans le descripteur de sécurité retourné ou NULL si le descripteur de sécurité n’a pas de SACL. Le pointeur retourné est valide uniquement si vous définissez l’indicateur SACL_SECURITY_INFORMATION. En outre, ce paramètre peut être NULL si vous n’avez pas besoin de la SACL.

[out, optional] ppSecurityDescriptor

Pointeur vers une variable qui reçoit un pointeur vers le descripteur de sécurité de l’objet . Lorsque vous avez terminé d’utiliser le pointeur, libérez la mémoire tampon retournée en appelant la fonction LocalFree .

Ce paramètre est obligatoire si l’un des paramètres ppsidOwner, ppsidGroup, ppDacl ou ppSacl n’est pas NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

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

Remarques

Si l’un des paramètres ppsidOwner, ppsidGroup, ppDacl ou ppSacl n’est pas NULL et que le paramètre SecurityInfo spécifie qu’ils sont récupérés à partir de l’objet, ces paramètres pointent vers les paramètres correspondants dans le descripteur de sécurité retourné dans ppSecurityDescriptor. Si le descripteur de sécurité ne contient pas les informations demandées, le paramètre correspondant est défini sur NULL.

Pour lire le propriétaire, le groupe ou le dacl à partir du descripteur de sécurité de l’objet, la liste DACL de l’objet doit accorder READ_CONTROL accès à l’appelant, ou l’appelant doit être le propriétaire de l’objet.

Pour lire la liste de contrôle d’accès système de l’objet, le privilège SE_SECURITY_NAME doit être activé pour le processus appelant. Pour plus d’informations sur les implications de sécurité de l’activation des privilèges, consultez Exécution avec des privilèges spéciaux.

Vous pouvez utiliser la fonction GetNamedSecurityInfo avec les types d’objets suivants :

Fichiers ou répertoires locaux ou distants sur un système de fichiers NTFS
Imprimantes locales ou distantes
Services Windows locaux ou distants
Partages réseau
les clés de Registre
Sémaphores, événements, mutex et minuteurs d’attente
Objets de mappage de fichiers
Objets du service d’annuaire

Cette fonction ne gère pas les conditions de concurrence. Si votre thread appelle cette fonction au moment approximatif où un autre thread modifie le descripteur de sécurité de l’objet, cette fonction peut échouer.

Cette fonction transfère des informations en texte clair. Les informations transférées par cette fonction sont signées, sauf si la signature a été désactivée pour le système, mais qu’aucun chiffrement n’est effectué.

Pour plus d’informations sur le contrôle de l’accès aux objets via des comptes d’utilisateur, des comptes de groupe ou des sessions d’ouverture de session, consultez Comment les DACL contrôlent l’accès à un objet.

Exemples

Pour obtenir un exemple qui utilise GetNamedSecurityInfo, consultez Modification des listes de contrôle d’accès d’un objet.

Notes

L’en-tête aclapi.h définit GetNamedSecurityInfo 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 \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	aclapi.h
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll