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

Статья
02/29/2024

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

Синтаксис

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

Параметры

[out] Acl

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

[in] AclLength

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

AclRevision

Уровень редакции ACL добавляемого элемента управления. Ниже приведены запросы версий 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 слишком велико.

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

Чтобы вычислить размер ACL, добавьте sizeof(ACL) к размеру всех ACL, которые будут храниться в списке ACL. Чтобы вычислить размер ACE, добавьте размер структуры ACE, например sizeof(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 для разработчиков драйверов и в документации по этим темам в windows SDK.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL