Funzione AccessCheckByTypeResultList (securitybaseapi.h)

Articolo
03/05/2024

La funzione AccessCheckByTypeResultList determina se un descrittore di sicurezza concede un set specificato di diritti di accesso al client identificato da un token di accesso. La funzione può controllare l'accesso del client a una gerarchia di oggetti, ad esempio un oggetto, i set di proprietà e le proprietà. La funzione segnala i diritti di accesso concessi o negati a ogni tipo di oggetto nella gerarchia. In genere, le applicazioni server usano questa funzione per controllare l'accesso a un oggetto privato.

Sintassi

BOOL AccessCheckByTypeResultList(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [out]               PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList
);

Parametri

[in] pSecurityDescriptor

Puntatore a una struttura SECURITY_DESCRIPTOR su cui viene controllato l'accesso.

[in, optional] PrincipalSelfSid

Puntatore a un identificatore di sicurezza (SID). Se il descrittore di sicurezza è associato a un oggetto che rappresenta un'entità (ad esempio un oggetto utente), il parametro PrincipalSelfSid deve essere il SID dell'oggetto . Quando si valuta l'accesso, questo SID sostituisce logicamente il SID in qualsiasi voce di controllo di accesso (ACE) contenente il SID noto PRINCIPAL_SELF SID (S-1-5-10). Per informazioni sui SID noti, vedere SID noti.

Se l'oggetto protetto non rappresenta un'entità, impostare questo parametro su NULL.

[in] ClientToken

Handle a un token di rappresentazione che rappresenta il client che tenta di ottenere l'accesso. L'handle deve avere TOKEN_QUERY accesso al token; in caso contrario, la funzione ha esito negativo con ERROR_ACCESS_DENIED.

[in] DesiredAccess

Maschera di accesso che specifica i diritti di accesso da controllare. Questa maschera deve essere stata mappata dalla funzione MapGenericMask per non contenere diritti di accesso generici.

Se questo parametro è MAXIMUM_ALLOWED, la funzione imposta le maschere di accesso nella matrice GrantedAccess per indicare i diritti di accesso massimi del client a ogni elemento nell'elenco dei tipi di oggetto.

[in, out, optional] ObjectTypeList

Puntatore a una matrice di strutture OBJECT_TYPE_LIST che identificano la gerarchia dei tipi di oggetto per cui controllare l'accesso. Ogni elemento della matrice specifica un GUID che identifica il tipo di oggetto e un valore che indica il livello del tipo di oggetto nella gerarchia dei tipi di oggetto. La matrice non deve avere due elementi con lo stesso GUID.

La matrice deve avere almeno un elemento. Il primo elemento della matrice deve essere a livello zero e identificare l'oggetto stesso. La matrice può avere un solo elemento zero di livello. Il secondo elemento è un oggetto secondario, ad esempio un set di proprietà, a livello 1. Dopo ogni voce di livello 1 sono voci subordinate per il livello 2 a 4 oggetti secondari. Pertanto, i livelli per gli elementi nella matrice potrebbero essere {0, 1, 2, 2, 1, 2, 2, 3}. Se l'elenco dei tipi di oggetto è non ordinato, AccessCheckByTypeResultList ha esito negativo e GetLastError restituisce ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

Numero di elementi nella matrice ObjectTypeList . Si tratta anche del numero di elementi nelle matrici a cui puntano i parametri GrantedAccessList e AccessStatusList .

[out] GenericMapping

Puntatore alla struttura GENERIC_MAPPING associata all'oggetto per cui viene controllato l'accesso.

[out, optional] PrivilegeSet

Puntatore a una struttura PRIVILEGE_SET che riceve i privilegi usati per eseguire la convalida dell'accesso. Se non sono stati usati privilegi, la funzione imposta il membro PrivilegeCount su zero.

[in, out] PrivilegeSetLength

Dimensioni, in byte, del buffer a cui punta il parametro PrivilegeSet .

[out] GrantedAccessList

Puntatore a una matrice di maschere di accesso. La funzione imposta ogni maschera di accesso per indicare i diritti di accesso concessi all'elemento corrispondente nell'elenco dei tipi di oggetto. Se la funzione ha esito negativo, non imposta le maschere di accesso.

[out] AccessStatusList

Puntatore a una matrice di codici di stato per gli elementi corrispondenti nell'elenco dei tipi di oggetto. La funzione imposta un elemento su zero per indicare l'esito positivo o un valore diverso da zero per indicare l'errore specifico durante il controllo di accesso. Se la funzione ha esito negativo, non imposta alcun elemento nella matrice.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.

Se la funzione ha esito negativo, restituisce zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Per altre informazioni, vedere la panoramica su Come AccessCheck Works .

La funzione AccessCheckByTypeResultList confronta il descrittore di sicurezza specificato con il token di accesso specificato e indica, nel parametro AccessStatusList , se l'accesso viene concesso o negato per ognuno degli elementi nell'elenco dei tipi di oggetto.

La matrice ObjectTypeList non rappresenta necessariamente l'intero oggetto definito. Invece, rappresenta il subset dell'oggetto per cui controllare l'accesso. Ad esempio, per controllare l'accesso a due proprietà in un set di proprietà, specificare un elenco di tipi di oggetto con quattro elementi: l'oggetto stesso a livello zero, la proprietà impostata a livello 1 e le due proprietà a livello 2.

La funzione AccessCheckByTypeResultList valuta gli ACL che si applicano all'oggetto stesso e gli ACL specifici dell'oggetto per i tipi di oggetto elencati nella matrice ObjectTypeList . La funzione ignora gli ACL specifici dell'oggetto per i tipi di oggetto non elencati nella matrice ObjectTypeList . Pertanto, i risultati restituiti per l'elemento zero nel parametro AccessStatusList indicano l'accesso consentito al subset dell'oggetto definito dal parametro ObjectTypeList , non all'intero oggetto.

Per altre informazioni sul modo in cui una gerarchia degli ACL controlla l'accesso a un oggetto e ai relativi oggetti secondari, vedere ACL per controllare l'accesso alle proprietà di un oggetto.

Se il descrittore di sicurezza dell'elenco di controllo di accesso discrezionale (DACL) è NULL, la funzione concede l'accesso richiesto a tutti gli elementi dell'elenco dei tipi di oggetto.

Se il descrittore di sicurezza non contiene i SID del proprietario e del gruppo, AccessCheckByTypeResultList ha esito negativo con ERROR_INVALID_SECURITY_DESCR.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll