Функция RtlCreateAcl (ntifs.h)

Статья
02/07/2025

Программа RtlCreateAcl создает и инициализирует список управления доступом (ACL).

Синтаксис

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

Параметры

[out] Acl

Указатель на выделенный вызывающим буфером для получения инициализированной структуры ACL. Этот буфер должен быть по крайней мере размер(ACL),

[in] AclLength

Длина буфера в байтах, на который указывает параметр Acl. Это значение должно быть достаточно большим, чтобы содержать заголовок ACL и все записи управления доступом (ACE), которые будут храниться в ACL. Дополнительные сведения о вычислении размера ACL см. в следующем разделе "Примечания".

AclRevision

Уровень редакции ACL добавляемого ACE. Требования к версии Windows приведены ниже.

Ценность	Значение
ACL_REVISION	Допустимый уровень редакции для всех версий Windows.
ACL_REVISION_DS	ПримечаниеAceRevision должно быть ACL_REVISION_DS, если ACL в Acl содержит объект ACE.

Возвращаемое значение

RtlCreateAcl может возвращать одно из следующих значений состояния:

Возвращаемый код	Описание
STATUS_SUCCESS	ACL успешно создан и инициализирован.
STATUS_BUFFER_TOO_SMALL	Новый ACL не помещается в буфер в Acl. Требуется больший буфер ACL.
STATUS_INVALID_PARAMETER	Указанная редакция не является текущей, или значение AclLength слишком велик.

Замечания

ACL, инициализированный RtlCreateAcl не содержит записей управления доступом (ACE). Этот ACL пуст, в отличие от того, чтобы быть несуществующим ACL. Если к объекту применяется пустой ACL, ACL неявно запрещает доступ ко всему объекту. Чтобы добавить acEs в ACL, используйте RtlAddAccessAllowedAce.

Чтобы вычислить размер ACL, добавьте размер(ACL) к размеру всех ACL, которые будут храниться в списке ACL. Чтобы вычислить размер ACE, добавьте размер структуры ACE, например размер(ACCESS_ALLOWED_ACE), к длине идентификатора безопасности, связанного с ACE, а затем вычитайте размер элемента SidStart (который является частью структуры ACE и SID). Используйте функцию RtlLengthSid, чтобы получить длину указанного идентификатора безопасности.

В следующем примере показано, как вычислить размер разрешенного доступа ACE:

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

Чтобы вычислить размер ACL, используйте следующий алгоритм, заменив соответствующую структуру ACE в выражении 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;
}

Дополнительные сведения о безопасности и управлении доступом см. в модели безопасности Windows для разработчиков драйверов и документации по этим разделам в пакете SDK для Windows.

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL