GetSecurityInfo, fonction (aclapi.h)

Article
08/22/2023

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

Syntaxe

DWORD GetSecurityInfo(
  [in]            HANDLE               handle,
  [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] handle

Handle de l’objet à partir duquel récupérer des informations de sécurité.

[in] ObjectType

SE_OBJECT_TYPE valeur d’énumération qui indique le type d’objet.

[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. Le pointeur retourné est valide uniquement si vous définissez l’indicateur OWNER_SECURITY_INFORMATION. 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é. Le pointeur retourné est valide uniquement si vous définissez l’indicateur GROUP_SECURITY_INFORMATION. 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é. Le pointeur retourné est valide uniquement si vous définissez l’indicateur DACL_SECURITY_INFORMATION. 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é. Le pointeur retourné est valide uniquement si vous définissez l’indicateur SACL_SECURITY_INFORMATION. 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 les paramètres ppsidOwner, ppsidGroup, ppDacl et ppSacl ne sont 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.

Pour lire le propriétaire, le groupe ou la liste dacl à partir du descripteur de sécurité de l’objet, le processus appelant doit avoir reçu un accès READ_CONTROL lors de l’ouverture du handle. Pour obtenir READ_CONTROL accès, l’appelant doit être le propriétaire de l’objet ou la liste dacl de l’objet doit accorder l’accès.

Pour lire la liste SACL à partir du descripteur de sécurité, le processus appelant doit avoir reçu un accès ACCESS_SYSTEM_SECURITY lors de l’ouverture du handle. La bonne façon d’obtenir cet accès consiste à activer le privilège SE_SECURITY_NAME dans le jeton actuel de l’appelant, à ouvrir le handle pour l’accès ACCESS_SYSTEM_SECURITY, puis à désactiver le privilège. 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 GetSecurityInfo avec les types d’objets suivants :

Fichiers ou répertoires locaux ou distants sur un système de fichiers NTFS
Canaux nommés
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
Processus, threads, travaux et objets de mappage de fichiers
Stations de bureau et stations de travail de fenêtre de service interactives
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.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Recherche du propriétaire d’un objet File.

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