RtlCreateAcl 函数 (ntifs.h)

项目
02/26/2024

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

要添加的 ACE 的 ACL 修订级别。 Windows 版本要求如下：

值	含义
ACL_REVISION	修订级别在所有 Windows 版本上都有效。
ACL_REVISION_DS	注意如果 Acl 中的 ACL 包含特定于对象的 ACE，则必须ACL_REVISION_DS AceRevision。

返回值

RtlCreateAcl 可以返回以下状态值之一：

返回代码	说明
STATUS_SUCCESS	已成功创建并初始化 ACL。
STATUS_BUFFER_TOO_SMALL	新的 ACL 不适合 Acl 的缓冲区。需要更大的 ACL 缓冲区。
STATUS_INVALID_PARAMETER	指定的修订不是最新的，或者 AclLength 的值太大。

注解

由 RtlCreateAcl 初始化的 ACL 不包含 (ACE) 的访问控制项。此 ACL 为空，而不是不存在的 ACL。如果将空 ACL 应用于对象，则 ACL 将隐式拒绝对该对象的所有访问。若要将 ACE 添加到 ACL，请使用 RtlAddAccessAllowedAce。

若要计算 ACL 的大小，请将 size of (ACL) 添加到要存储在 ACL 中的所有 ACE 的大小。若要计算 ACE 的大小，请将 ACE 结构的大小（如 size of (ACCESS_ALLOWED_ACE) ）添加到与 ACE 关联的 SID 的长度，然后减去 SidStart 成员 (的大小，该成员是 ACE 结构和 SID) 的一部分。使用 RtlLengthSid 函数获取指定 SID 的长度。

以下示例演示如何计算允许访问的 ACE 的大小：

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

若要计算 ACL 的大小，请使用以下算法，将适当的 ACE 结构替换为 size of (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 中有关这些主题的文档。