Função RtlCreateAcl (ntifs.h)

Artigo
02/26/2024

A rotina RtlCreateAcl cria e inicializa uma ACL (lista de controle de acesso).

Sintaxe

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

Parâmetros

[out] Acl

Ponteiro para um buffer alocado pelo chamador para receber a estrutura de ACL inicializada. Esse buffer deve ser pelo menos sizeof(ACL),

[in] AclLength

Comprimento, em bytes, do buffer apontado pelo parâmetro Acl . Esse valor deve ser grande o suficiente para conter o cabeçalho acl e todas as ACE (entradas de controle de acesso) a serem armazenadas na ACL. Consulte a seção Comentários a seguir para obter informações sobre como calcular o tamanho de uma ACL.

AclRevision

Nível de revisão de ACL do ACE a ser adicionado. As exigências de versão do Windows são as seguintes:

Valor	Significado
ACL_REVISION	O nível de revisão válido em todas as versões do Windows.
ACL_REVISION_DS	ObservaçãoAceRevision deverá ser ACL_REVISION_DS se a ACL na Acl contiver um ACE específico do objeto.

Retornar valor

RtlCreateAcl pode retornar um dos seguintes valores de status:

Código de retorno	Descrição
STATUS_SUCCESS	A ACL foi criada e inicializada com êxito.
STATUS_BUFFER_TOO_SMALL	A nova ACL não se encaixa no buffer em Acl. Um buffer de ACL maior é necessário.
STATUS_INVALID_PARAMETER	A revisão especificada não é atual ou o valor de AclLength é muito grande.

Comentários

A ACL inicializada por RtlCreateAcl não contém nenhuma ACE (entradas de controle de acesso). Essa ACL está vazia, em vez de ser uma ACL inexistente. Se uma ACL vazia for aplicada a um objeto , a ACL negará implicitamente todo o acesso a esse objeto. Para adicionar ACEs à ACL, use RtlAddAccessAllowedAce.

Para calcular o tamanho de uma ACL, adicione sizeof(ACL) ao tamanho de todos os ACEs a serem armazenados na ACL. Para calcular o tamanho de um ACE, adicione o tamanho da estrutura ACE, como sizeof(ACCESS_ALLOWED_ACE), ao comprimento do SID associado ao ACE e subtraia o tamanho do membro SidStart (que faz parte da estrutura ACE e do SID). Use a função RtlLengthSid para obter o comprimento de um SID especificado.

O exemplo a seguir mostra como calcular o tamanho de um ACE permitido pelo acesso:

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

Para calcular o tamanho de uma ACL, use o seguinte algoritmo, substituindo a estrutura ACE apropriada na expressão 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 obter mais informações sobre segurança e controle de acesso, consulte Modelo de segurança do Windows para desenvolvedores de driver e a documentação sobre esses tópicos no SDK do Windows.