RtlCreateAcl-Funktion (ntifs.h)

Artikel
02/27/2024

Die RtlCreateAcl-Routine erstellt und initialisiert eine Zugriffssteuerungsliste (Access Control List, ACL).

Syntax

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

Parameter

[out] Acl

Zeiger auf einen vom Aufrufer zugewiesenen Puffer, um die initialisierte ACL-Struktur zu empfangen. Dieser Puffer muss mindestens sizeof (ACL) sein,

[in] AclLength

Länge des Puffers in Bytes, auf den der Acl-Parameter verweist. Dieser Wert muss groß genug sein, um den ACL-Header und alle Zugriffssteuerungseinträge (Access Control Entries, ACE) zu enthalten, die in der ACL gespeichert werden sollen. Informationen zum Berechnen der Größe einer ACL finden Sie im folgenden Abschnitt mit den Hinweisen.

AclRevision

ACL-Revisionsebene des hinzuzufügenden ACE. Die Windows-Versionsanforderung ist wie folgt:

Wert	Bedeutung
ACL_REVISION	Die Revisionsebene, die für alle Windows-Versionen gültig ist.
ACL_REVISION_DS	HinweisAceRevision muss ACL_REVISION_DS werden, wenn die ACL in Acl einen objektspezifischen ACE enthält.

Rückgabewert

RtlCreateAcl kann einen der folgenden status-Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die ACL wurde erfolgreich erstellt und initialisiert.
STATUS_BUFFER_TOO_SMALL	Die neue ACL passt nicht in den Puffer bei Acl. Ein größerer ACL-Puffer ist erforderlich.
STATUS_INVALID_PARAMETER	Die angegebene Revision ist nicht aktuell, oder der Wert von AclLength ist zu groß.

Hinweise

Die von RtlCreateAcl initialisierte ACL enthält keine Zugriffssteuerungseinträge (ACE). Diese ACL ist leer, anstatt eine nicht vorhandene ACL zu sein. Wenn eine leere ACL auf ein Objekt angewendet wird, verweigert die ACL implizit jeglichen Zugriff auf dieses Objekt. Verwenden Sie RtlAddAccessAllowedAce, um der ACL ACEs hinzuzufügen.

Um die Größe einer ACL zu berechnen, fügen Sie sizeof (ACL) zur Größe aller ACEs hinzu, die in der ACL gespeichert werden sollen. Um die Größe eines ACE zu berechnen, fügen Sie die Größe der ACE-Struktur, z. B. sizeof(ACCESS_ALLOWED_ACE), der Länge der SID hinzu, die dem ACE zugeordnet ist, und subtrahieren Sie dann die Größe des SidStart-Elements (der Sowohl Teil der ACE-Struktur als auch der SID ist). Verwenden Sie die RtlLengthSid-Funktion , um die Länge einer angegebenen SID abzurufen.

Im folgenden Beispiel wird gezeigt, wie die Größe eines zugriffsgeschützten ACE berechnet wird:

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

Verwenden Sie zum Berechnen der Größe einer ACL den folgenden Algorithmus, und ersetzen Sie dabei die entsprechende ACE-Struktur im sizeof(ACE)-Ausdruck:

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;
}

Weitere Informationen zur Sicherheit und Zugriffssteuerung finden Sie unter Windows-Sicherheitsmodell für Treiberentwickler und in der Dokumentation zu diesen Themen im Windows SDK.