Fonction RtlCreateAcl (ntifs.h)

Article
02/26/2024

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 sizeof(ACL),

[in] AclLength

Longueur, en octets, de la mémoire tampon pointée vers 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) pour être stockées dans la liste de contrôle d’accès. Consultez la section Remarques suivante pour plus d’informations sur le calcul de la taille d’une liste de contrôle d’accès.

AclRevision

Niveau de révision ACL de l’ACE à ajouter. Les réquirtions de version Windows sont les suivantes :

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 Acl contient un ACE spécifique à un objet.

Valeur retournée

RtlCreateAcl peut retourner l’une des valeurs de status suivantes :

Code de retour	Description
STATUS_SUCCESS	L’ACL a été créée et initialisée avec succès.
STATUS_BUFFER_TOO_SMALL	La nouvelle liste de contrôle d’accès ne tient pas dans la mémoire tampon sur Acl. Une mémoire tampon ACL plus grande est requise.
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 AES à la liste de contrôle d’accès, utilisez RtlAddAccessAllowedAce.

Pour calculer la taille d’une liste de contrôle d’accès, ajoutez sizeof(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, telle que sizeof(ACCESS_ALLOWED_ACE), à la longueur du SID associé à l’ACE, puis soustrayez la taille du membre SidStart (qui fait partie à la fois 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’une ace autorisée 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.