Fonction RtlCreateAcl (ntifs.h)

Article
02/07/2025

La routine RtlCreateAcl crée et initialise une liste de contrôle d’accès (ACL).

Syntaxe

NTSYSAPI NTSTATUS RtlCreateAcl(
  [out] PACL  Acl,
  [in]  ULONG AclLength,
        ULONG AclRevision
);

Paramètres

[out] Acl

Pointeur vers une mémoire tampon allouée par l’appelant pour recevoir la structure ACL initialisée. Cette mémoire tampon doit être au moins taille de(ACL),

[in] AclLength

Longueur, en octets, de la mémoire tampon pointée par le paramètre Acl. Cette valeur doit être suffisamment grande pour contenir l’en-tête ACL et toutes les entrées de contrôle d’accès (ACE) à stocker dans la liste de contrôle d’accès. Pour plus d’informations sur le calcul de la taille d’une liste de contrôle d’accès, consultez la section Remarques suivantes.

AclRevision

Niveau de révision ACL de l’ACE à ajouter. La configuration requise pour la version de Windows est la suivante :

Valeur	Signification
ACL_REVISION	Niveau de révision valide sur toutes les versions de Windows.
ACL_REVISION_DS	RemarqueAceRevision doit être ACL_REVISION_DS si la liste de contrôle d’accès dans de liste de contrôle contient un ACE spécifique à l’objet.

Valeur de retour

RtlCreateAcl pouvez retourner l’une des valeurs d’état suivantes :

Retourner le code	Description
STATUS_SUCCESS	La liste de contrôle d’accès a été créée et initialisée.
STATUS_BUFFER_TOO_SMALL	La nouvelle liste de contrôle d’accès ne s’intègre pas dans la mémoire tampon à acl. Une mémoire tampon de liste de contrôle d’accès plus grande est nécessaire.
STATUS_INVALID_PARAMETER	La révision spécifiée n’est pas actuelle, ou la valeur de AclLength est trop grande.

Remarques

La liste de contrôle d’accès initialisée par RtlCreateAcl ne contient aucune entrée de contrôle d’accès (ACE). Cette liste de contrôle d’accès est vide, au lieu d’être une liste de contrôle d’accès inexistante. Si une liste de contrôle d’accès vide est appliquée à un objet, la liste de contrôle d’accès refuse implicitement tout accès à cet objet. Pour ajouter des ACL à la liste de contrôle d’accès, utilisez RtlAddAccessAllowedAce.

Pour calculer la taille d’une liste de contrôle d’accès, ajoutez taille de(ACL) à la taille de toutes les ACL à stocker dans la liste de contrôle d’accès. Pour calculer la taille d’un ACE, ajoutez la taille de la structure ACE, par exemple taille de(ACCESS_ALLOWED_ACE), à la longueur du SID associé à l’ACE, puis soustrait la taille du membre SidStart (qui fait partie de la structure ACE et du SID). Utilisez la fonction RtlLengthSid pour obtenir la longueur d’un SID spécifié.

L’exemple suivant montre comment calculer la taille d’un ACE autorisé par accès :

sizeof (ACCESS_ALLOWED_ACE) - sizeof (ACCESS_ALLOWED_ACE.SidStart) 
        + GetLengthSid (pAceSid);

Pour calculer la taille d’une liste de contrôle d’accès, utilisez l’algorithme suivant, en remplaçant la structure ACE appropriée dans l’expression sizeof(ACE) :

cbAcl = sizeof (ACL);
for (i = 0 ; i < nAceCount ; i++) {
    // subtract ACE.SidStart from the size
    cbAce = sizeof (ACE) - sizeof (DWORD);
    // add this ACE's SID length
    cbAce += GetLengthSid (pAceSid[i]);
    // add the length of each ACE to the total ACL length
    cbAcl += cbAce;
}

Pour plus d’informations sur la sécurité et le contrôle d’accès, consultez modèle de sécurité Windows pour les développeurs de pilotes et la documentation sur ces rubriques dans le Kit de développement logiciel (SDK) Windows.