Funzione RtlCreateAcl (ntifs.h)

Articolo
02/26/2024

La routine RtlCreateAcl crea e inizializza un elenco di controllo di accesso (ACL).

Sintassi

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

Parametri

[out] Acl

Puntatore a un buffer allocato dal chiamante per ricevere la struttura ACL inizializzata. Questo buffer deve essere almeno sizeof(ACL),

[in] AclLength

Lunghezza, in byte, del buffer a cui punta il parametro Acl . Questo valore deve essere sufficientemente grande da contenere l'intestazione ACL e tutte le voci di controllo di accesso (ACE) da archiviare nell'ACL. Per informazioni sul calcolo delle dimensioni di un elenco di controllo di accesso, vedere la sezione Osservazioni seguente.

AclRevision

Livello di revisione ACL dell'ace da aggiungere. I riquirmenti delle versioni di Windows sono i seguenti:

Valore	Significato
ACL_REVISION	Livello di revisione valido in tutte le versioni di Windows.
ACL_REVISION_DS	NotaAceRevision deve essere ACL_REVISION_DS se l'ACL in Acl contiene un ace specifico dell'oggetto.

Valore restituito

RtlCreateAcl può restituire uno dei valori di stato seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	L'elenco di controllo di accesso è stato creato e inizializzato correttamente.
STATUS_BUFFER_TOO_SMALL	Il nuovo ACL non rientra nel buffer in Acl. È necessario un buffer ACL più grande.
STATUS_INVALID_PARAMETER	La revisione specificata non è corrente o il valore di AclLength è troppo grande.

Commenti

L'ACL inizializzato da RtlCreateAcl non contiene voci di controllo di accesso (ACE). Questo ACL è vuoto, anziché essere un ACL inesistente. Se a un oggetto viene applicato un ACL vuoto, l'ACL nega in modo implicito l'accesso a tale oggetto. Per aggiungere ACL gli ACL, usare RtlAddAccessAllowedAce.

Per calcolare le dimensioni di un ACL, aggiungere sizeof(ACL) alle dimensioni di tutti gli ACL da archiviare nell'ACL. Per calcolare le dimensioni di un ACE, aggiungere le dimensioni della struttura ACE, ad esempio sizeof(ACCESS_ALLOWED_ACE), alla lunghezza del SID associato all'ACE e quindi sottrarre le dimensioni del membro SidStart (che fa parte sia della struttura ACE che del SID). Usare la funzione RtlLengthSid per ottenere la lunghezza di un SID specificato.

L'esempio seguente illustra come calcolare le dimensioni di un ace consentito per l'accesso:

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

Per calcolare le dimensioni di un ACL, usare l'algoritmo seguente, sostituendo la struttura ACE appropriata nell'espressione 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;
}

Per altre informazioni sulla sicurezza e sul controllo di accesso, vedere Modello di sicurezza di Windows per sviluppatori di driver e la documentazione su questi argomenti in Windows SDK.