Función RtlCreateAcl (ntifs.h)

Artículo
02/26/2024

La rutina RtlCreateAcl crea e inicializa una lista de control de acceso (ACL).

Sintaxis

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

Parámetros

[out] Acl

Puntero a un búfer asignado por el autor de la llamada para recibir la estructura de ACL inicializada. Este búfer debe ser al menos sizeof(ACL),

[in] AclLength

Longitud, en bytes, del búfer al que apunta el parámetro Acl . Este valor debe ser lo suficientemente grande como para contener el encabezado ACL y todas las entradas de control de acceso (ACE) que se almacenarán en la ACL. Consulte la siguiente sección Comentarios para obtener información sobre cómo calcular el tamaño de una ACL.

AclRevision

Nivel de revisión de ACL de la ACE que se va a agregar. Las solicitudes de versión de Windows son las siguientes:

Valor	Significado
ACL_REVISION	Nivel de revisión válido en todas las versiones de Windows.
ACL_REVISION_DS	NotaAceRevision debe ser ACL_REVISION_DS si la ACL de Acl contiene una ACE específica del objeto.

Valor devuelto

RtlCreateAcl puede devolver uno de los siguientes valores de estado:

Código devuelto	Descripción
STATUS_SUCCESS	La ACL se creó e inicializó correctamente.
STATUS_BUFFER_TOO_SMALL	La nueva ACL no encaja en el búfer en Acl. Se requiere un búfer de ACL mayor.
STATUS_INVALID_PARAMETER	La revisión especificada no es actual o el valor de AclLength es demasiado grande.

Comentarios

La ACL inicializada por RtlCreateAcl no contiene entradas de control de acceso (ACE). Esta ACL está vacía, en lugar de ser una ACL inexistente. Si se aplica una ACL vacía a un objeto, la ACL deniega implícitamente todo el acceso a ese objeto. Para agregar ACL a la ACL, use RtlAddAccessAllowedAce.

Para calcular el tamaño de una ACL, agregue sizeof(ACL) al tamaño de todas las ACE que se almacenarán en la ACL. Para calcular el tamaño de una ACE, agregue el tamaño de la estructura ACE, como sizeof(ACCESS_ALLOWED_ACE), a la longitud del SID asociado a la ACE y, a continuación, reste el tamaño del miembro SidStart (que forma parte de la estructura ACE y el SID). Use la función RtlLengthSid para obtener la longitud de un SID especificado.

En el ejemplo siguiente se muestra cómo calcular el tamaño de una ACE permitida por el acceso:

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

Para calcular el tamaño de una ACL, use el siguiente algoritmo, sustituyendo la estructura ACE adecuada en la expresión 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;
}

Para obtener más información sobre la seguridad y el control de acceso, consulte Modelo de seguridad de Windows para desarrolladores de controladores y la documentación sobre estos temas en Windows SDK.