FltQuerySecurityObject, fonction (fltkernel.h)

FltQuerySecurityObject récupère une copie du descripteur de sécurité d’un objet.

Syntaxe

NTSTATUS FLTAPI FltQuerySecurityObject(
  [in]            PFLT_INSTANCE        Instance,
  [in]            PFILE_OBJECT         FileObject,
  [in]            SECURITY_INFORMATION SecurityInformation,
  [in, out]       PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in]            ULONG                Length,
  [out, optional] PULONG               LengthNeeded
);

Paramètres

[in] Instance

Pointeur d’instance opaque pour l’appelant. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] FileObject

Pointeur d’objet de fichier pour l’objet dont le descripteur de sécurité est interrogé. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] SecurityInformation

SECURITY_INFORMATION valeur. Ce paramètre est obligatoire et doit être l’un des éléments suivants :

[in, out] SecurityDescriptor

Pointeur vers une mémoire tampon de sortie fournie par l’appelant qui reçoit une copie du descripteur de sécurité pour l’objet spécifié. La structure SECURITY_DESCRIPTOR est retournée au format auto-relatif. Ce paramètre est facultatif et peut être NULL.

[in] Length

Taille, en octets, de la mémoire tampon SecurityDescriptor.

[out, optional] LengthNeeded

Pointeur vers une variable allouée par l’appelant qui reçoit le nombre d’octets requis pour stocker le descripteur de sécurité copié retourné dans la mémoire tampon pointée par le paramètre SecurityDescriptor . Ce paramètre est facultatif et peut être NULL. Si SecurityDescriptor a la valeur NULL, ce paramètre reçoit la taille de mémoire tampon requise lorsque la fonction retourne STATUS_BUFFER_TOO_SMALL.

Valeur de retour

FltQuerySecurityObject retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple l’une des valeurs suivantes :

Remarques

Un descripteur de sécurité peut être sous forme absolue ou auto-relative. Sous forme auto-relative, tous les membres de la structure se trouvent contiguëment en mémoire. Sous forme absolue, la structure contient uniquement des pointeurs vers ses membres.

Le système de fichiers NTFS impose une limite de 64 Ko à la taille du descripteur de sécurité écrit sur disque pour un fichier. (Le système de fichiers FAT ne prend pas en charge les descripteurs de sécurité pour les fichiers.) Ainsi, une mémoire tampon de 64 Ko pointée par le paramètre SecurityDescriptor est garantie d’être suffisamment volumineuse pour contenir la structure de SECURITY_DESCRIPTOR retournée.

Objet que le FileObject points de paramètre pour représenter un flux de données nommé. Pour plus d’informations sur les flux de données nommés, consultez FILE_STREAM_INFORMATION.

Pour plus d’informations sur la sécurité et le contrôle d’accès, consultez la documentation du Kit de développement logiciel (SDK) Microsoft Windows.

modèle de requête Two-Step

Un modèle d’utilisation courant implique deux appels à FltQuerySecurityObject pour déterminer dynamiquement la taille de mémoire tampon requise :

Étape 1 : Interroger la taille de mémoire tampon requise

Appelez la fonction avec une mémoire tampon NULL et une longueur nulle pour obtenir la taille de mémoire tampon requise :

ULONG bytesNeeded;

status = FltQuerySecurityObject(
    instance,
    fileObj,
    securityInfo,
    NULL,           // SecurityDescriptor - NULL to query size
    0,              // Length - zero since no buffer provided
    &bytesNeeded);  // Receives required buffer size

Cet appel retourne STATUS_BUFFER_TOO_SMALL et remplit les octetsNeeded avec la taille de mémoire tampon requise.

Étape 2 : Allouer et récupérer le descripteur de sécurité

Allouez une mémoire tampon de la taille requise et appelez à nouveau la fonction :

secDescriptor = ExAllocatePoolWithTag(PagedPool, bytesNeeded, 'cSeD');
if (secDescriptor != NULL) {
    status = FltQuerySecurityObject(
        instance,
        fileObj,
        securityInfo,
        secDescriptor,  // Allocated buffer
        bytesNeeded,    // Size from first call
        NULL);          // LengthNeeded - optional, can be NULL
}

Le paramètre LengthNeeded est facultatif et peut être NULL sur le deuxième appel lorsque la logique de nouvelle tentative en cas d’échec n’est pas nécessaire.

Exigences

Voir aussi

• FILE_STREAM_INFORMATION
• SECURITY_DESCRIPTOR
• SECURITY_INFORMATION